document configuration

Signed-off-by: Lamont Granquist <lamont@scriptkiddie.org>

1 files changed, 41 insertions, 1 deletions

diff --git a/docs/dev/data_collector.md b/docs/dev/data_collector.md
index 73eba91826..0ac229a5fc 100644
--- a/docs/dev/data_collector.md
+++ b/docs/dev/data_collector.md
@@ -27,6 +27,43 @@ The Data Collector also collects:
 Most of this is done through hooking events directly in the Data Collector itself.  The ErrorHandlers module is broken out into a module which is directly mixed into
 the Data Collector to separate that concern out into a different file (it is straightforwards with fairly little state, but is just a lot of hooked methods).
 
+## Basic Configuration Modes
+
+### Configured for Automate
+
+Do nothing.  The URL is constructed from the base `Chef::Config[:chef_server_url]`, auth is just Chef Server API authentication, and the default behavior is that it
+is configured.
+
+### Configured to Log to a File
+
+Setup a file output location, no token is necessary:
+
+```
+Chef::Config[:data_collector][:output_locations] = { files:  [ "/Users/lamont/data_collector.out" ] }
+```
+
+Note the fact that you can't assign to `Chef::Config[:data_collector][:output_locations][:files]` and will NoMethodError if you try.
+
+### Configured to Log to a Non-Chef Server Endpoint
+
+Setup a server url, requiring a token:
+
+```
+Chef::Config[:data_collector][:server_url] = "https://chef.acme.local/myendpoint.html"
+Chef::Config[:data_collector][:token] = "mytoken"
+```
+
+This works for chef-clients which are configured to hit a chef server, but use a custom non-Chef-Automate endpoint for reporting, or for chef-solo/zero users.
+
+XXX: There is also the `Chef::Config[:data_collector][:output_locations] = { uri: [ "https://chef.acme.local/myendpoint.html" ] }` method -- which is going to behave
+differently, particularly on non-chef-solo use cases.  In that case the data collector `server_url` will still be automatically derived from the `chef_server_url` and
+the data collector will attempt to contact that endpoint, but with the token being supplied it will use that and will not use Chef Server authentication, and the
+server should 403 back, and if `raise_on_failure` is left to the default of false then it will simply drop that failure and continue without raising, which will
+appear to work, and output will be send to the configured `output_locations`.  But given how hopelessly complicated this is, the recommendation is to use the
+`server_url` and to avoid using any `url` options in the `output_locations` since that feature is fairly poorly designed at this point in time.  Note that the presence of
+a token flips all external URIs to using the token so that it is not possible to use this feature to talk to both a Chef Automate endpoint and a custom URI reporting
+endpoint (which would seem to be the most useful of an incredibly marginally useful feature and it does not work).
+
 ## Resiliency to Failures
 
 The Data Collector in Chef >= 15.0 is resilient to failures that occur anywhere in the main loop of the `Chef::Client#run` method.  In order to do this there is a lot
@@ -70,8 +107,11 @@ As it happens in the actual chef-client run:
   * failures during cookbook resolution will cause `events.cookbook_resolution_failed(node, exception)` here and skip to #13
   * failures during cookbook synch will cause `events.cookbook_sync_failed(node, exception)` and skip to #13
 10. `events.cookbook_compilation_start(run_context)`
-11. < the resource events happen here which hit the action collection >
+11. < the resource events happen here which hit the action collection, may throw any of the other failure events >
 12. `events.converge_complete` or `events.converge_failed(exception)`
 13. `run_status.stop_clock`
 14. `run_status.exception = exception` if it failed
 15. `events.run_completed(node, run_status)` or `events.run_failed(exception, run_status)`
+
+
+