OpenTelemetryDecorator (OpenTelemetryDecorator v1.4.4)

A function decorator for OpenTelemetry traces.

installation

Installation

Add open_telemetry_decorator to your list of dependencies in mix.exs. We include the opentelemetry_api package, but you'll need to add opentelemetry yourself in order to report spans and traces.

def deps do
  [
    {:opentelemetry, "~> 1.2"},
    {:opentelemetry_exporter, "~> 1.4"},
    {:open_telemetry_decorator, "~> 1.4"}
  ]
end

Then follow the directions for the exporter of your choice to send traces to to zipkin, honeycomb, etc. https://github.com/open-telemetry/opentelemetry-erlang/tree/main/apps/opentelemetry_zipkin

honeycomb-example

Honeycomb Example

config/runtime.exs

api_key = Map.fetch!(System.get_env(), "HONEYCOMB_KEY")

config :opentelemetry, :processors,
  otel_batch_processor: %{
    exporter:
      {:opentelemetry_exporter,
       %{
         protocol: :grpc,
         headers: [
           {'x-honeycomb-team', api_key},
           {'x-honeycomb-dataset', 'YOUR_APP_NAME'}
         ],
         endpoints: [{:https, 'api.honeycomb.io', 443, []}]
       }}
  }

usage

Usage

Add use OpenTelemetryDecorator to the module, and decorate any methods you want to trace with @decorate with_span("span name").

The with_span decorator will automatically wrap the decorated function in an opentelemetry span with the provided name.

defmodule MyApp.Worker do
  use OpenTelemetryDecorator

  @decorate with_span("worker.do_work")
  def do_work(arg1, arg2) do
    ...doing work
  end
end

span-attributes

Span Attributes

The with_span decorator allows you to specify an include option which gives you more flexibility with what you can include in the span attributes. Omitting the include option with with_span means no attributes will be added to the span by the decorator.

defmodule MyApp.Worker do
  use OpenTelemetryDecorator

  @decorate with_span("worker.do_work", include: [:arg1, :arg2])
  def do_work(arg1, arg2) do
    # ...doing work
  end
end

The Attributes module includes a helper for setting additional attributes outside of the include option. Attributes added in either a set call or in the include that are not primitive OTLP values will be converted to strings with Kernel.inspect/1.

defmodule MyApp.Worker do
  use OpenTelemetryDecorator
  alias OpenTelemetryDecorator.Attributes

  @decorate with_span("worker.do_work")
  def do_work(arg1, arg2) do
    Attributes.set(arg1: arg1, arg2: arg2)
    # ...doing work
    Attributes.set(:output, "something")
  end
end

The decorator uses a macro to insert code into your function at compile time to wrap the body in a new span and link it to the currently active span. In the example above, the do_work method would become something like this:

defmodule MyApp.Worker do
  require OpenTelemetry.Tracer, as: Tracer

  def do_work(arg1, arg2) do
    Tracer.with_span "my_app.worker.do_work" do
      # ...doing work
      Tracer.set_attributes(arg1: arg1, arg2: arg2)
    end
  end
end

prefixing-span-attributes

Prefixing Span Attributes

Honeycomb suggests that you namespace custom fields, specifically putting manual instrumentation under app.

In order to do this, you'll configure the attr_prefix option in config/config.exs

config :open_telemetry_decorator, attr_prefix: "app."

changing-the-join-character-for-nested-attributes

Changing the join character for nested attributes

By default, nested attributes are joined with an underscore. However, when you have an object with underscores and a property with underscores, this can be hard to visually parse. For example, my_struct.other_struct.field, would be exported as my_struct_other_struct_field.

To override this, you'll configure the attr_joiner option in config/config.exs. The default value will likely change from _ to . in a future version.

config :open_telemetry_decorator, attr_joiner: "."

Thanks to @benregn for the examples and inspiration for these two options!

Link to this section Summary

Link to this section Functions

Link to this macro

trace(var1)

(macro)
Link to this macro

trace(var1, var2)

(macro)
Link to this function

trace(span_name, opts \\ [], body, context)

Link to this macro

with_span(var1)

(macro)
Link to this macro

with_span(var1, var2)

(macro)
Link to this function

with_span(span_name, opts \\ [], body, context)

Decorate a function to add to or create an OpenTelemetry trace with a named span.

You can provide span attributes by specifying a list of variable names as atoms. This list can include:

  • any variables (in the top level closure) available when the function exits,
  • the result of the function by including the atom :result,
  • map/struct properties using nested lists of atoms.
defmodule MyApp.Worker do
  use OpenTelemetryDecorator

  @decorate with_span("my_app.worker.do_work", include: [:arg1, [:arg2, :count], :total, :result])
  def do_work(arg1, arg2) do
    total = arg1.count + arg2.count
    {:ok, total}
  end
end