Merge pull request #292 from tsloughter/exporter-docs

improve exporter module documentation and readme

apps/opentelemetry_exporter/README.md

@@ -6,7 +6,9 @@ The OpenTelemetry Protocol exporter for use with the [OpenTelemetry Collector](h
 
 Currently only supports the Tracer protocol using either GRPC or Protobuffers over HTTP1.1. Metrics are to come soon.
 
-## Using
+## Configuration
+
+### Options to Batch Processor
 
 Easiest way to setup is to add configuration for the batch processor in OpenTelemetry application environment.
 
@@ -16,7 +18,9 @@ For an Erlang release in `sys.config`:
 {opentelemetry,
   [{processors, 
     [{otel_batch_processor,
-        #{exporter => {opentelemetry_exporter, #{endpoints => [{http, "localhost", 9090, []}]}}}}]}]}
+        #{exporter => {opentelemetry_exporter, #{endpoints =>
+        ["http://localhost:9090"],
+            headers => [{"x-honeycomb-dataset", "experiments"}]}}}}]}]}
 ```
 
 The default protocol is `http_protobuf`, to override this and use grpc add `protocol` to the config map:
@@ -26,18 +30,56 @@ The default protocol is `http_protobuf`, to override this and use grpc add `prot
   [{processors, 
     [{otel_batch_processor,
         #{exporter => {opentelemetry_exporter, #{protocol => grpc,
-                                                 endpoints => [{http, "localhost", 9090, []}]}}}}]}]}
+                                                 endpoints => ["http://localhost:9090"],
+                                                 headers => [{"x-honeycomb-dataset", "experiments"}]}}}}]}]}
 ```
 
 An Elixir release uses `releases.exs`:
 
 ``` elixir
 config :opentelemetry, :processors,
   otel_batch_processor: %{
-    exporter: {:opentelemetry_exporter, %{endpoints: [{:http, 'localhost', 9090, []}]}}
+    exporter: {:opentelemetry_exporter, %{endpoints: ["http://localhost:9090"],
+                                          headers: [{"x-honeycomb-dataset", "experiments"}]}}
   }
 ```
 
+### Application Environment
+
+- `otlp_endpoint`: The URL to send traces and metrics to, for traces the path `v1/traces` is appended to the path in the URL.
+- `otlp_traces_endpoint`: URL to send only traces to. This takes precedence for exporting traces and the path of the URL is kept as is, no suffix is appended.
+- `otlp_headers`: List of additional headers (`[{unicode:chardata(), unicode:chardata()}]`) to add to export requests.
+- `otlp_traces_headers`: Additional headers (`[{unicode:chardata(), unicode:chardata()}]`) to add to only trace export requests.
+
+
+``` erlang
+{opentelemetry_exporter,
+  [{otlp_endpoint, "https://api.honeycomb.io:443"},
+   {otlp_headers, [{"x-honeycomb-dataset", "experiments"}]}]}
+```
+
+An Elixir release uses `releases.exs`:
+
+``` elixir
+config :opentelemetry_exporter,
+  otlp_endpoint: "https://api.honeycomb.io:443",
+  otlp_headers: [{"x-honeycomb-dataset", "experiments"}]
+```
+
+### OS Environment
+
+- `OTEL_EXPORTER_OTLP_ENDPOINT`: The URL to send traces and metrics to, for traces the path `v1/traces` is appended to the path in the URL.
+- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`: URL to send only traces to. This takes precedence for exporting traces and the path of the URL is kept as is, no suffix is appended.
+- `OTEL_EXPORTER_OTLP_HEADERS`: List of additional headers to add to export requests.
+- `OTEL_EXPORTER_OTLP_TRACES_HEADERS`: Additional headers to add to only trace export requests.
+
+Example usage of setting the environment variables:
+```
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.honeycomb.io:443
+OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-honeycomb-team=<HONEYCOMB API TOKEN>,x-honeycomb-dataset=experiments
+```
+
 ## Contributing
 
 This project uses a submodule during developement, it is not needed if the application is being used as a dependency, so be sure to clone with the option `recurse-submodules`:

apps/opentelemetry_exporter/src/opentelemetry_exporter.erl

@@ -28,20 +28,20 @@
 %%     for exporting traces and the path of the URL is kept as is, no suffix is
 %%     appended.
 %%   </li>
-%%   <li>`otlp_headers': Additional headers to add to export requests.</li>
+%%   <li>`otlp_headers': List of additional headers (`[{unicode:chardata(), unicode:chardata()}]') to add to export requests.</li>
 %%   <li>
-%%     `otlp_traces_headers': Additional headers to add to only trace export %% requests.
+%%     `otlp_traces_headers': Additional headers (`[{unicode:chardata(), unicode:chardata()}]') to add to only trace export requests.
 %%   </li>
 %% </ul>
 %%
 %% There also corresponding OS environment variables can also set those
 %% configuration values:
 %%
 %% <ul>
-%%   <li>`OTEL_EXPORTER_OTLP_ENDPOINT'</li>
-%%   <li>`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT'</li>
-%%   <li>`OTEL_EXPORTER_OTLP_HEADERS'</li>
-%%   <li>`OTEL_EXPORTER_OTLP_TRACES_HEADERS'</li>
+%%   <li>`OTEL_EXPORTER_OTLP_ENDPOINT': The URL to send traces and metrics to, for traces the path `v1/traces' is appended to the path in the URL.</li>
+%%   <li>`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT': URL to send only traces to. This takes precedence for exporting traces and the path of the URL is kept as is, no suffix is appended.</li>
+%%   <li>`OTEL_EXPORTER_OTLP_HEADERS': List of additional headers to add to export requests.</li>
+%%   <li>`OTEL_EXPORTER_OTLP_TRACES_HEADERS': Additional headers to add to only trace export requests.</li>
 %% </ul>
 %%
 %% @end
@@ -53,10 +53,12 @@
          shutdown/1]).
 
 %% for testing
+-ifdef(TEST).
 -export([to_proto_by_instrumentation_library/1,
          to_proto/1,
          endpoints/1,
          merge_with_environment/1]).
+-endif.
 
 -include_lib("kernel/include/logger.hrl").
 -include_lib("opentelemetry_api/include/opentelemetry.hrl").
@@ -69,15 +71,34 @@
 -define(DEFAULT_PORT, 4317).
 -define(DEFAULT_TRACES_PATH, "v1/traces").
 
--record(state, {protocol :: grpc | http_protobuf | http_json,
+-type headers() :: [{unicode:chardata(), unicode:chardata()}].
+-type scheme() :: http | https | string() | binary().
+-type host() :: unicode:chardata().
+-type endpoint() :: uri_string:uri_string() | uri_string:uri_map() | #{scheme := scheme(),
+                                                                       host := host(),
+                                                                       port => integer(),
+                                                                       ssl_options => []}.
+-type protocol() :: grpc | http_protobuf | http_json.
+
+-type opts() :: #{endpoints => [endpoint()],
+                  headers => headers(),
+                  protocol => protocol()}.
+
+-export_type([opts/0,
+              headers/0,
+              endpoint/0,
+              protocol/0]).
+
+-record(state, {protocol :: protocol(),
                 channel_pid :: pid() | undefined,
-                headers :: [{unicode:chardata(), unicode:chardata()}],
+                headers :: headers(),
                 grpc_metadata :: map() | undefined,
                 endpoints :: [uri_string:uri_map()]}).
 
 %% @doc Initialize the exporter based on the provided configuration.
-init(Opts0) ->
-    Opts1 = merge_with_environment(Opts0),
+-spec init(opts()) -> {ok, #state{}}.
+init(Opts) ->
+    Opts1 = merge_with_environment(Opts),
     Endpoints = endpoints(maps:get(endpoints, Opts1, ?DEFAULT_ENDPOINTS)),
     Headers = headers(maps:get(headers, Opts1, [])),
     case maps:get(protocol, Opts1, http_protobuf) of