Repository files navigation

A function decorator for OpenTelemetry traces.

Addopen_telemetry_decorator to your list of dependencies inmix.exs. We include theopentelemetry_api package, but you'll need to addopentelemetry yourself in order to report spans and traces.

defdepsdo[{:opentelemetry,"~> 1.5"},{:opentelemetry_exporter,"~> 1.8"},{:open_telemetry_decorator,"~> 1.5"}]end

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

config/runtime.exs

api_key=System.fetch_env!("HONEYCOMB_KEY")config:opentelemetry_exporter,otlp_endpoint:"https://api.honeycomb.io:443",otlp_headers:[{"x-honeycomb-team",api_key}]

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

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

defmoduleMyApp.WorkerdouseOpenTelemetryDecorator@decoratewith_span("worker.do_work")defdo_work(arg1,arg2)do...doingworkendend

Thewith_span decorator allows you to specify aninclude option which gives you more flexibility with what you can include in the span attributes. Omitting theinclude option withwith_span means no attributes will be added to the span by the decorator.

defmoduleMyApp.WorkerdouseOpenTelemetryDecorator@decoratewith_span("worker.do_work",include:[:arg1,:arg2])defdo_work(arg1,arg2)do# ...doing workendend

The O11y module includes a helper for setting additional attributes outside of theinclude option. Attributes added in either aset call or in theinclude that are notprimitive OTLP values will be converted to strings withKernel.inspect/1.

defmoduleMyApp.WorkerdouseOpenTelemetryDecorator@decoratewith_span("worker.do_work")defdo_work(arg1,arg2)doO11y.set_attributes(arg1:arg1,arg2:arg2)# ...doing workO11y.set_attribute(:output,"something")endend

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, thedo_work method would become something like this:

defmoduleMyApp.WorkerdorequireOpenTelemetry.Tracer,as:Tracerdefdo_work(arg1,arg2)doTracer.with_span"my_app.worker.do_work"do# ...doing workTracer.set_attributes(arg1:arg1,arg2:arg2)endendend

Honeycomb suggests that younamespace custom fields, specifically prefixing manual instrumentation withapp

✳️ You can now set this in the underlyingo11y library with theattribute_namespace option ✳️

config:o11y,:attribute_namespace,"app"

⚠️ You can still configure it with theattr_prefix option inconfig/config.exs, but that will be deprecated in a future release.⚠️

config:open_telemetry_decorator,attr_prefix:"app."

⚠️ This configuration option is no longer available⚠️

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.Note that variables declared as part of anif,case,cond, orwith block are in a separate scope so NOT available forinclude attributes.

defmoduleMyApp.MathdouseOpenTelemetryDecorator@decoratewith_span("my_app.math.add",include:[:a,:b,:sum])defadd(a,b)dosum=a+b{:ok,sum}endend

The result of the function by including the atom:result:

defmoduleMyApp.MathdouseOpenTelemetryDecorator@decoratewith_span("my_app.math.add",include:[:result])defadd(a,b)do{:ok,a+b}endend

Structs will be converted to maps and included in the span attributes. You can specify which fields to include with the@derive attribute provided byO11y.

defmoduleUserdouseOpenTelemetryDecorator@derive{O11y.SpanAttributes,only:[:id,:name]}defstruct[:id,:name,:email,:password]@decoratewith_span("user.create",include:[:user])defcreate(user)do{:ok,user}endend

make check before you commit! If you'd prefer to do it manually:

• mix do deps.get, deps.unlock --unused, deps.clean --unused if you change dependencies
• mix compile --warnings-as-errors for a stricter compile
• mix coveralls.html to check for test coverage
• mix credo to suggest more idiomatic style for your code
• mix dialyzer to find problems typing might reveal… albeitslowly
• mix docs to generate documentation