repository·main·Indexed 42 days ago
https://github.com/open-telemetry/opentelemetry-erlang-contribA collection of community-contributed OpenTelemetry instrumentations and utilities for the Erlang and Elixir ecosystems. It extends the core OpenTelemetry SDK with support for recording exceptions, custom span attributes, and specific instrumentations such as opentelemetry_absinthe, opentelemetry_phoenix, and opentelemetry_ecto.
opentelemetry-erlang-contrib repository contains OpenTelemetry contribution libraries for Erlang and Elixir. These libraries provide additional functionality, such as specific instrumentations, that are not included in the core OpenTelemetry Erlang API and SDK repositories. Use this repository to extend your observability capabilities with specialized instrumentations for popular Erlang/Elixir frameworks and libraries.opentelemetry_process_propagator package provides functions to enable OpenTelemetry context propagation across different processes. This is essential for maintaining trace continuity when a request or operation moves from one Erlang/Elixir process to another (e.g., via message passing or distributed systems).opentelemetry_req package provides an OpenTelemetry plugin for the Req HTTP client. It enables automatic instrumentation and trace propagation for HTTP requests made using Req.OpentelemetryOban.setup() is called, a new trace is automatically started whenever an Oban job is processed.The instrumentation packages in this repository map OpenTelemetry Semantic Convention requirement levels to specific configuration options:
| SemConv Level | Instrumentation Behavior | User Control |
|---|---|---|
| Required | Always included | None |
| Recommended | Included by default | opt_out_attrs |
| Opt-In | Excluded by default | opt_in_attrs |
| Experimental | Excluded by default | opt_in_attrs |
To avoid collisions and maintain standards, follow these naming rules for custom attribute keys:
Modules follow the pattern Opentelemetry[PackageName].[ComponentName]Attributes.
OpentelemetryEcto.EctoAttributes or OpentelemetryMylib.MylibAttributes.mylib.).snake_case segments separated by dots.otel. as this prefix is reserved for OpenTelemetry. Do not use existing SemConv namespaces unless intentionally extending them.| Example | Status | Reason |
|---|---|---|
mylib.cache | ✅ | Correct prefix and format |
mylib.queue_name | ✅ | Correct prefix and format |
otel.mylib.cache | ❌ | otel. prefix is reserved |
cache | ❌ | Missing namespace |
telemetry events. It listens for Nebulex command events and translates them into OpenTelemetry spans. It supports both Nebulex v2 and v3 command events.To correctly record a failure on an OpenTelemetry span, you must use both record_exception and set_status. These two functions are complementary and serve different purposes:
record_exception: Adds an event to the span containing structured fields like exception.type, exception.message, and exception.stacktrace. This is used by trace backends for detailed error inspection.set_status(status, description): Marks the span status as errored. This is used by dashboards and UIs to quickly identify failed spans.Warning: Do not add other span events. New events should be handled via the Logs API once available in Erlang. record_exception without set_status will leave the span appearing successful, while set_status without record_exception will lose the structured error details.
When using OpenTelemetry in a Phoenix/Ecto application, you can export traces using two primary architectural patterns:
Via OpenTelemetry Collector (Recommended for multi-destination):
The application sends traces to a local or centralized OpenTelemetry Collector. The Collector is then configured to route those traces to one or more backends (e.g., Zipkin, Jaeger, Honeycomb, or Lightstep).
Pattern: Application --> OpenTelemetry Collector --> [Zipkin, Jaeger, etc.]
Direct Export (OTLP):
The application sends traces directly to an external service that supports the OTLP (OpenTelemetry Protocol).
Pattern: Application --> External Service
If you choose to export to external services like Honeycomb or Lightstep, ensure you update your .env file with the required credentials and consult the specific service's documentation for OTLP configuration.
OpentelemetryHTTPoison is designed to work in tandem with 'server-side' instrumented libraries (like opentelemetry_plug).
SERVER span.OpentelemetryHTTPoison creates a span for the outgoing request and injects the trace context into the request headers.This allows trace information to propagate across microservices through HTTP 'jumps'.
Critical Note on Process Boundaries: The Erlang OpenTelemetry SDK stores the active span in a pdict (per-process dictionary). If OpentelemetryHTTPoison is called from a different process than the one that handled the initial request, it will not find the parent span and will create a new root span, breaking the trace. In such cases, you must manually pass the parent span to the HTTP client request.
:telemetry handlers, be aware of the context propagation precedence: handlers must first check for an already-attached context before falling back to a $callers ancestor. This prevents incorrect context association during event handling.