ArkeOpentelemetryEx

This package is under heavy development. APIs may change without notice.

The go-to package for setting up OpenTelemetry in Arke applications. One dependency replaces seven — get traces (Phoenix, Cowboy, Ecto) and OTLP log export out of the box.

Installation

Add the dependency to mix.exs:

def deps do
  [
    {:arke_opentelemetry_ex, "~> 0.1.0"}
  ]
end

For releases, add the required OTP applications:

def project do
  [
    releases: [
      my_app: [
        applications: [
          opentelemetry_exporter: :permanent,
          opentelemetry: :temporary
        ]
      ]
    ]
  ]
end

Quick Start

1. Configure in config/config.exs:

config :opentelemetry,
  resource: %{service: %{name: "my_service"}}

config :arke_opentelemetry_ex,
  ecto_repos: [[:my_app, :repo]]

config :logger,
  backends: [:console, ArkeOpentelemetryEx.LoggerBackend]

1. Set environment variables:

OTLP_ENDPOINT=https://collector:4317
OTLP_LOGS_ENDPOINT=https://collector:4318/v1/logs

1. Call setup/0 in your application.ex:

def start(_type, _args) do
  ArkeOpentelemetryEx.setup()

  children = [...]
  Supervisor.start_link(children, strategy: :one_for_one)
end

That's it. The package reads OTLP_ENDPOINT (gRPC, for traces) and OTLP_LOGS_ENDPOINT (HTTP, for logs) automatically.

Overriding Defaults

The smart defaults cover the common case. Override any of them in config/runtime.exs:

# Override trace exporter settings
config :opentelemetry_exporter,
  otlp_endpoint: "https://custom-collector:4317",
  otlp_protocol: :http_protobuf,
  otlp_headers: [{"x-api-key", "secret"}],
  otlp_compression: :gzip

# Override logger backend settings
config :logger, ArkeOpentelemetryEx.LoggerBackend,
  endpoint: "https://custom-collector:4318/v1/logs",
  level: :warning,
  batch_size: 200,
  flush_interval: 10_000

Explicit config always takes precedence over environment variables.

Default Headers

The package automatically resolves headers from environment variables and attaches them to both trace and log exports. Explicit config always takes precedence.

OTEL_TENANT_ID=my_tenant
OTEL_EXPORTER_OTLP_AUTH_HEADER=Bearer my_token

Headers are merged with any existing headers configured via :otlp_headers or :headers and won't override already-present keys.

Default Resource

The package resolves resource attributes from environment variables, falling back to built-in defaults. Explicit config :opentelemetry, :resource takes precedence.

OTEL_SERVICE_NAME=my_service

This means you don't need to set config :opentelemetry, resource: %{service: %{name: "..."}} manually — just set the env var or rely on the default.

Disabling

Set enabled: false to turn off all tracing, instrumentation, and log export:

config :arke_opentelemetry_ex,
  enabled: false

When disabled, setup/0 is a no-op (OTP apps are not started, instrumentations are not attached) and the logger backend silently drops all log records. Defaults to true.

Configuration Reference

:opentelemetry

Standard opentelemetry SDK config. See opentelemetry-erlang docs.

:opentelemetry_exporter

ArkeOpentelemetryEx.LoggerBackend

Configured via config :logger, ArkeOpentelemetryEx.LoggerBackend.

:arke_opentelemetry_ex

Package-specific options for telemetry instrumentation.

License

MIT