Elixir

This guide shows you how to instrument an Elixir application with the upstream OpenTelemetry Erlang/Elixir SDK and send traces directly to Middleware. It covers Phoenix, Bandit (or Cowboy) and Ecto out of the box. No Middleware Host Agent is required: the OTLP exporter in your application sends data straight to your Middleware account.

Prerequisites#

• Elixir 1.15+ on Erlang/OTP 25+. Check using:
  bash

  elixir --version

• Middleware account & project: your Middleware UID (https://<uid>.middleware.io) and API key (MW_API_KEY)
• Network access from your application to https://<uid>.middleware.io:443

For a deeper overview of Middleware's OTLP endpoints and headers, see the OpenTelemetry getting started guide.

Setup#

export OTEL_EXPORTER_OTLP_ENDPOINT="https://<MW_UID>.middleware.io:443"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="authorization=<MW_API_KEY>"
export OTEL_SERVICE_NAME="<service-name>"
export OTEL_RESOURCE_ATTRIBUTES="service.version=<service-version>,deployment.environment=<environment>"

config :opentelemetry,
  resource: [service: [name: "<service-name>"]]

config :opentelemetry_exporter,
  otlp_protocol: :http_protobuf,
  otlp_endpoint: "https://<MW_UID>.middleware.io:443",
  otlp_headers: [{"authorization", "<MW_API_KEY>"}]

defp deps do
  [
    # ... your existing dependencies
    {:opentelemetry_exporter, "~> 1.11"},
    {:opentelemetry, "~> 1.7"},
    {:opentelemetry_api, "~> 1.5"},
    {:opentelemetry_phoenix, "~> 2.0"},
    {:opentelemetry_bandit, "~> 0.3"},
    {:opentelemetry_ecto, "~> 1.2"}
  ]
end

mix deps.get

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

defmodule MyApp.Application do
  @moduledoc false

  use Application

  @impl true
  def start(_type, _args) do
    OpentelemetryBandit.setup()
    OpentelemetryPhoenix.setup(adapter: :bandit)
    OpentelemetryEcto.setup([:my_app, :repo])

    children = [
      MyApp.Repo,
      MyAppWeb.Endpoint
    ]

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

mix phx.server

Create custom spans#

Wrap your own code in spans with OpenTelemetry.Tracer, and attach attributes you can filter on in Middleware:

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

  def handle_order(order_id) do
    Tracer.with_span "handle-order" do
      Tracer.set_attributes(%{"order.id": order_id})
      # ...
    end
  end
end

Other deployment targets#

The OpenTelemetry configuration is the same everywhere; only the way you declare environment variables changes.

docker run \
  -e OTEL_EXPORTER_OTLP_ENDPOINT="https://<MW_UID>.middleware.io:443" \
  -e OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf" \
  -e OTEL_EXPORTER_OTLP_HEADERS="authorization=<MW_API_KEY>" \
  -e OTEL_SERVICE_NAME="<service-name>" \
  <your-image>

env:
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: "https://<MW_UID>.middleware.io:443"
  - name: OTEL_EXPORTER_OTLP_PROTOCOL
    value: "http/protobuf"
  - name: OTEL_EXPORTER_OTLP_HEADERS
    value: "authorization=<MW_API_KEY>"
  - name: OTEL_SERVICE_NAME
    value: "<service-name>"

View your data#

After you start the application and send some traffic, wait 3–5 minutes, then open APM → Services or the Traces explorer in Middleware and filter by your service name.

Environment variables#

Troubleshooting#

• No data in Middleware: confirm the environment variables are set in the BEAM process that runs your app, and that the endpoint does not already include /v1/traces.
• Spans dropped in releases: make sure opentelemetry_exporter is listed before opentelemetry in deps and in the release applications list, as shown in step 2.
• Ecto queries missing: check that the prefix passed to OpentelemetryEcto.setup/1 matches your repo's telemetry_prefix.
• Debugging locally: to print spans to stdout instead of exporting them, temporarily add config :opentelemetry, traces_exporter: {:otel_exporter_stdout, []} to your config. The Erlang/Elixir SDK does not support OTEL_TRACES_EXPORTER=console.