OpenTelemetry Instrumentation for Erlang/Elixir

Overview

OpenTelemetry provides instrumentation for Erlang/Elixir applications, enabling you to collect telemetry data such as traces and metrics. Although Lumigo does not offer its own OpenTelemetry Distribution for Erlang, you can still configure it. This guide explains how to set up OpenTelemetry Erlang Instrumentation and configure it to report data to Lumigo.

Prerequisites

Before you begin, ensure you have the following:

• **Erlang/OTP: **Version 23 or higher.
• **Elixir: **Version 1.13 or higher (if using Elixir).
• A Lumigo Token, which can be found in Settings > Tracing > Manual Tracing. For more details, see the Lumigo Tokens documentation.

Installation Steps

Install OpenTelemetry Erlang/Elixir Instrumentation and instrument your Erlang/Elixir application using the provided packages.

1. Add Dependencies

Add the necessary OpenTelemetry packages to your project. These include the API, SDK, and exporter for sending data to Lumigo.

For Erlang (usingrebar3):

Add the following to your rebar.config file:

{deps, [
  {opentelemetry, "~> 1.3"},
  {opentelemetry_api, "~> 1.2"},
  {opentelemetry_exporter, "~> 1.6"}
]}.

For Elixir (usingmix):

Update your mix.exs file with:

defp deps do
  [
    {:opentelemetry, "~> 1.3"},
    {:opentelemetry_api, "~> 1.2"},
    {:opentelemetry_exporter, "~> 1.6"}
  ]
end

These dependencies provide the core functionalities for OpenTelemetry instrumentation and exporting capabilities.

2. Configure OpenTelemetry

Next, set up OpenTelemetry to use the OTLP exporter, directing telemetry data to Lumigo's endpoint.

For Erlang:

In your sys.config or runtime configuration file, add:

{opentelemetry, [
  {resource, #{
    <<"service.name">> => <<"your_service_name">>
  }},
  {processors, [
    {otel_batch_processor, #{}}
  ]},
  {traces_exporter, otlp}
]},
{opentelemetry_exporter, [
  {otlp_protocol, http_protobuf},
  {otlp_endpoint, <<"https://ga-otlp.lumigo-tracer-edge.golumigo.com">>},
  {headers, #{
    <<"Authorization">> => <<"LumigoToken YOUR_LUMIGO_TOKEN">>
  }}
]}.

For Elixir:

In your config.exs or runtime configuration file, include:

config :opentelemetry, :resource, %{
  "service.name" => "your_service_name"
}

config :opentelemetry, :processors, [
  {:otel_batch_processor, %{}}
]

config :opentelemetry, :traces_exporter, :otlp

config :opentelemetry_exporter,
  otlp_protocol: :http_protobuf,
  otlp_endpoint: "https://ga-otlp.lumigo-tracer-edge.golumigo.com",
  headers: %{
    "Authorization" => "LumigoToken YOUR_LUMIGO_TOKEN"
  }

Replace "your_service_name" with a descriptive name for your service and "YOUR_LUMIGO_TOKEN" with your actual Lumigo token. This configuration sets up the resource attributes, specifies the batch processor for handling spans, and configures the OTLP exporter to send data to Lumigo's endpoint with the necessary authorization.

3. Initialize OpenTelemetry on Application Start

Ensure that OpenTelemetry starts with your application to begin capturing telemetry data immediately.

For Erlang:

In your application's start function, add:

opentelemetry:start().

For Elixir:

In your application's application.ex file, within the start/2 function, include:

:ok = :opentelemetry.start()

This ensures that the OpenTelemetry processes are initiated when your application starts, allowing it to capture and export telemetry data seamlessly.

4. Instrument Your Code

To capture meaningful telemetry, instrument your application's code by creating spans around operations you want to monitor.

For Erlang:

%% Import the OpenTelemetry tracer module
-include_lib("opentelemetry_api/include/otel_tracer.hrl").

%% Within your function
?with_span(<<"operation_name">>, #{}, fun() ->
  %% Your code here
end).

For Elixir:

require OpenTelemetry.Tracer

OpenTelemetry.Tracer.with_span "operation_name" do
  # Your code here
end

Replace "operation_name" with a descriptive name for the operation being traced. These spans help in tracking the execution flow and performance of specific operations within your application.