long-winded explanation of how initDefaultHoneybadgerConfigContext works

src/edu/stanford/dlss/wowza/SulWowza.java

@@ -141,8 +141,36 @@ public void setHoneybadgerConfigContext(StandardConfigContext configContext)
 
     // TODO:  this approach expects the properties to be set in Application.xml
     //   maybe that's good, or maybe we want to load a java properties file from our plugin jar itself?
+    //
+    // TL;DR:  Application.xml should contain the API key and the instance environment (e.g. stage, prod),
+    // in its <Properties> section.  the property names should be "HONEYBADGER_API_KEY" and "ENV", respective.
+    // see conf/example/Application.xml.
     public void initDefaultHoneybadgerConfigContext(IApplicationInstance appInstance)
     {
+        // this is maybe too much background for here and should prob go in a readme or devops doc, but for now...
+        // the StandardConfigContext constructor first initializes the instance with a DefaultsConfigContext
+        // by way of a super() call to its parent class constructor (BaseChainedConfigContext).  that sets
+        // the honeybadger API URL.  the StandardConfigContext constructor can also take a map of properties,
+        // from which it will override default property values based on expected field names.  in particular,
+        // it'll look for the environment name first in the "ENV" field, then in the "JAVA_ENV" field.  it'll
+        // look for the API key in the "HONEYBADGER_API_KEY" field, then in the "honeybadger.api_key"* field.
+        // since IApplicationInstance.getProperties() returns a subclass of Map (WMSProperties) containing properties
+        // set in Application.xml, we can just set the property names we care about in Application.xml and they'll get
+        // picked up automatically.
+        //
+        // see also:
+        //  https://github.com/honeybadger-io/honeybadger-java#advanced-configuration
+        //  https://github.com/honeybadger-io/honeybadger-java/blob/1.1.0/src/main/java/io/honeybadger/reporter/config/DefaultsConfigContext.java
+        //  https://github.com/honeybadger-io/honeybadger-java/blob/1.1.0/src/main/java/io/honeybadger/reporter/config/BaseChainedConfigContext.java
+        //  https://github.com/honeybadger-io/honeybadger-java/blob/1.1.0/src/main/java/io/honeybadger/reporter/config/StandardConfigContext.java
+        //  https://github.com/honeybadger-io/honeybadger-java/blob/1.1.0/src/main/java/io/honeybadger/reporter/config/MapConfigContext.java
+        //  http://www.wowza.com/resources/serverapi/com/wowza/wms/application/IApplicationInstance.html#getProperties()
+        //  http://www.wowza.com/resources/serverapi/com/wowza/wms/application/WMSProperties.html
+        //
+        // * note: i suspect we shouldn't use "honeybadger.api_key", because it appears that
+        // MapConfigContext.getHoneybadgerUrl() erroneously looks there first for the URL, so we
+        // should avoid confusing it, to be safe:
+        // https://github.com/honeybadger-io/honeybadger-java/blob/1.1.0/src/main/java/io/honeybadger/reporter/config/MapConfigContext.java#L113
         setHoneybadgerConfigContext(new StandardConfigContext(appInstance.getProperties()));
     }