View Source Sibyl.Handlers.OpenTelemetry (Sibyl v0.1.6)

OpenTelemetry is an open source standard telemetry standard which allows us to capture custom metrics and traces of our application.

For local development, you can install tools such as Jaeger to be able to view and test OpenTelemetry traces.

However, much of the BEAM ecosystem (and this library) uses :telemetry as a standard for emitting arbitrary telemetry events.

This handler is a bridge between standard :telemetry span events and OpenTelemetry spec compliant traces.

  • Any event which ends in :start will start an OpenTelemetry span context.

  • Any event which ends in :stop or :exception will stop the currently active OpenTelemetry span context, capturing any metadata that is passed in.

  • Any event which ends in anything else will be attached as a custom event to the currently active span context.

For Elixir's built in Task module, Sibyl.Handlers.OpenTelemetry will be able to internal state and automatically attach said async Task to the original parent.

Distributed traces via non Task means is also supported, but this cannot be automated. To opt into this behaviour, serialize the span state on the consumer end via the build_distributed_trace_context/0 function, and prior to starting any new traces on the consumer end, use attach_distributed_trace_context/1. Doing this should attach both the consumer and producer side of the trace into one for rendering in tools such as Jaeger.

Link to this section Summary

Functions

Processes a serialized OpenTelemetry trace context (obtained via build_distributed_trace_context/0) and persists it within the current process.

Serializes the current OpenTelemetry trace context to allow it to be sent over-the-wire to external services, with the intention to re-attach the context on the consumer's end.

A constant for the undefined OpenTelemetry trace context.

Link to this section Functions

Link to this function

attach_distributed_trace_context(trace_context)

View Source
@spec attach_distributed_trace_context(trace_context :: String.t()) :: :ok

Processes a serialized OpenTelemetry trace context (obtained via build_distributed_trace_context/0) and persists it within the current process.

The next span which is created will be automatically attached to this distributed trace context, allowing for the building of (tooling permitting) distributed traces across multiple different nodes, releases, services, etc.

Link to this function

build_distributed_trace_context()

View Source
@spec build_distributed_trace_context() :: String.t()

Serializes the current OpenTelemetry trace context to allow it to be sent over-the-wire to external services, with the intention to re-attach the context on the consumer's end.

This should allow you (tooling permitting) to build distributed traces across multiple different nodes, releases, services, etc.

Link to this function

undefined_trace_context()

View Source
@spec undefined_trace_context() :: String.t()

A constant for the undefined OpenTelemetry trace context.

Useful for defaulting a distributed trace context parse to a "noop" if data is malformed or mistransmitted.