OpenTelemetry.Honeycomb

opentelemetry_honeycomb provides an in-process OpenTelemetry exporter for Honeycomb.

Installation

Add opentelemetry, opentelemetry_api, and opentelemetry_honeycomb to your deps in mix.exs:

{:opentelemetry, "~> 0.5.0"},
{:opentelemetry_api, "~> 0.5.0"},
{:opentelemetry_honeycomb, "~> 0.5.0-rc.1"},

If you're using the default back ends, you'll also need hackney and poison:

{:hackney, ">= 1.11.0"},
{:poison, ">= 1.5.0"},

Configuration

A compact config/config.exs for opentelemetry_honeycomb is:

use Config

# You can also supply opentelemetry resources using environment variables, eg.:
# OTEL_RESOURCE_ATTRIBUTES=service.name=name,service.namespace=namespace

config :opentelemetry, :resource,
  service: [
    name: "service-name",
    namespace: "service-namespace"
]

config :opentelemetry,
  processors: [
    otel_batch_processor: %{
      exporter:
        {OpenTelemetry.Honeycomb.Exporter, write_key: System.get_env("HONEYCOMB_WRITEKEY")}
    }
  ]

processors specifies otel_batch_processor, which specifies exporter, a 2-tuple of the exporter's module name and options to be supplied to its init/1. Our exporter takes a list of t:OpenTelemetry.Honeycomb.Config.config_opt/0 as its options.

Attribute Handling

OpenTelemetry supports a flat map of attribute keys to string, number, and boolean values (see t.OpenTelemetry.attribute_value/0). The API does not enforce this, implicitly supporting other attribute value types eg. maps until export time.

Honeycomb expects a flat JSON-serialisable object, but can be configured to flatten maps and stringify arrays at import time.

The data models being quite similar, we:

Pass string, number, and boolean values through unmodified
Flatten map values as described below
Convert most other values to strings using inspect/1 with a short limit
Trim string values longer than 49127 bytes

When trimming strings, we replace the last 3-7 characters of the trimmed string or so with an ellipsis ("...") of equal length. We choose the length of the ellipsis to avoid ending the trimmed string with a high-bit character, eg. splitting a UTF-8 code point.

We drop:

Entire attribute lists that don't start as a list or map
Entire list members that don't resemble key/value pairs

When flattening maps, we use periods (.) to delimit keys, for example this input:

%{
  http: %{
    host:  "localhost",
    method: "POST",
    path: "/api"
  }
}

... to this output:

%{
  "http.host" => "localhost",
  "http.method" => "POST",
  "http.path" => "/api",
}

Verification

First, we need to check :opentelemetry and :opentelemetry_api. Fire up iex -S mix and paste in the following code to install the :otel_exporter_stdout exporter:

:otel_batch_processor.set_exporter(:otel_exporter_stdout, [])

After a delay, you should see:

*SPANS FOR DEBUG*
*SPANS FOR DEBUG*
*SPANS FOR DEBUG*

Now, paste in some trace-sending code:

require OpenTelemetry.Tracer

OpenTelemetry.Tracer.with_span "example" do
  IO.inspect(OpenTelemetry.Tracer.current_span_ctx())
  OpenTelemetry.Tracer.set_attribute(:a, 1)
  OpenTelemetry.Tracer.set_attributes(b: 2, c: 3)
  OpenTelemetry.Tracer.set_attributes(d: %{e: "f"})
end

You should get output resembling:

{span,142297071326187490948809128380223875835,10977461588491893807,undefined,
      undefined,<<"example">>,'INTERNAL',-576460738804789000,
      -576460738804601000,
      [{a,1},{b,2},{c,3},{d,#{e => <<"f">>}}],
      [],[],undefined,1,false,undefined}

Next, we need to check OpenTelemetry.Honeycomb.Exporter. Paste in:

# hard way
:otel_batch_processor.set_exporter(OpenTelemetry.Honeycomb.Exporter,
  http_module: OpenTelemetry.Honeycomb.Http.ConsoleBackend,
  write_key: "HONEYCOMB_WRITEKEY"
)

# easy way
OpenTelemetry.Honeycomb.Http.ConsoleBackend.activate()

Paste in the trace-sending code again to see what the OpenTelemetry Honeycomb Exporter would have sent to Honeycomb:

POST /1/batch/opentelemetry HTTP/1.1
Host: api.honeycomb.io
Content-Type: application/json
User-Agent: opentelemetry_honeycomb/0.3.0-rc.0
X-Honeycomb-Team: HONEYCOMB_WRITEKEY

[
  {
    "time": "2020-04-24T06:12:16.698425Z",
    "samplerate": 1,
    "data": {
      "trace.trace_id": "6c14288156831d40602dc1f5a61489c0",
      "trace.span_id": "377fce3346b92811",
      "trace.parent_id": null,
      "service.namespace": "service-namespace",
      "service.name": "service-name",
      "name": "example",
      "duration_ms": 6.06005859375,
      "d.e": "f",
      "c": 3,
      "b": 2,
      "a": 1
    }
  }
]

Restore your configured exporter by pasting:

OpenTelemetry.Honeycomb.Http.ConsoleBackend.deactivate()

Development

Dependency management:

mix deps.get to get your dependencies
mix deps.compile to compile them
mix licenses to check their license declarations, recursively

Finding problems:

mix compile to compile your code
mix credo to suggest more idiomatic style for it
mix dialyzer to find problems static typing might spot... slowly
mix test to run unit tests
mix test.watch to run the tests again whenever you change something
mix coveralls to check test coverage

Documentation:

mix docs to generate documentation for this project
mix help to find out what else you can do with mix

Changes since Opencensus.Honeycomb

Removed decorator: use resources or extra processors.