OpenTelemetry Decorator

https://hexdocs.pm/open_telemetry_decorator/1.5.10/
Admin
A function decorator for OpenTelemetry traces.
Tokens:1,829
Snippets:22
Trust Score:9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Internal Macro Expansion of `with_span`

Source: https://hexdocs.pm/open_telemetry_decorator/OpenTelemetryDecorator.html

This example shows how the `@decorate with_span` macro internally transforms the decorated function. It wraps the original function body within `Tracer.with_span` and includes calls to `Tracer.set_attributes` for any specified attributes.

```elixir
defmodule MyApp.Worker do
  require OpenTelemetry.Tracer, as: Tracer

  def do_work(arg1, arg2) do
    Tracer.with_span "my_app.worker.do_work" do
      # ...doing work
      Tracer.set_attributes(arg1: arg1, arg2: arg2)
    end
  end
end
```

--------------------------------

### Configure Honeycomb Exporter

Source: https://hexdocs.pm/open_telemetry_decorator/OpenTelemetryDecorator.html

Configure the `opentelemetry_exporter` in `config/runtime.exs` to send traces to Honeycomb. This requires setting the OTLP endpoint and authentication headers.

```elixir
api_key = System.fetch_env!("HONEYCOMB_KEY")

config :opentelemetry_exporter,
  otlp_endpoint: "https://api.honeycomb.io:443",
  otlp_headers: [{"x-honeycomb-team", api_key}]
```

--------------------------------

### Basic Function Decoration with `with_span`

Source: https://hexdocs.pm/open_telemetry_decorator/OpenTelemetryDecorator.html

Use `use OpenTelemetryDecorator` in your module and apply the `@decorate with_span("span name")` attribute to functions you want to trace. This automatically wraps the function body in an OpenTelemetry span.

```elixir
defmodule MyApp.Worker do
  use OpenTelemetryDecorator

  @decorate with_span("worker.do_work")
  def do_work(arg1, arg2) do
    ...doing work
  end
end
```

--------------------------------

### Configure Attribute Prefix (Deprecated)

Source: https://hexdocs.pm/open_telemetry_decorator/OpenTelemetryDecorator.html

Configure the attribute prefix using `attr_prefix` in `config/config.exs`. This method will be deprecated in a future release.

```elixir
config :open_telemetry_decorator, attr_prefix: "app."
```

--------------------------------

### Add OpenTelemetryDecorator to Dependencies

Source: https://hexdocs.pm/open_telemetry_decorator/OpenTelemetryDecorator.html

Add the `open_telemetry_decorator` and related packages to your `mix.exs` dependencies. Ensure `opentelemetry` is also included to enable span reporting.

```elixir
def deps do
  [
    {:opentelemetry, "~> 1.5"},
    {:opentelemetry_exporter, "~> 1.8"},
    {:open_telemetry_decorator, "~> 1.5"}
  ]
end
```

--------------------------------

### Configure Attribute Namespace for o11y

Source: https://hexdocs.pm/open_telemetry_decorator/OpenTelemetryDecorator.html

Set the attribute namespace for the underlying o11y library to prefix custom fields. This is the recommended approach for manual instrumentation.

```elixir
config :o11y, :attribute_namespace, "app"
```

--------------------------------

### Decorate with Span Attributes using `include`

Source: https://hexdocs.pm/open_telemetry_decorator/OpenTelemetryDecorator.html

Specify the `include` option within the `with_span` decorator to automatically add function arguments as attributes to the span. Omitting `include` results in no attributes being added by default.

```elixir
defmodule MyApp.Worker do
  use OpenTelemetryDecorator

  @decorate with_span("worker.do_work", include: [:arg1, :arg2])
  def do_work(arg1, arg2) do
    # ...doing work
  end
end
```

--------------------------------

### Include Function Result in Span Attributes

Source: https://hexdocs.pm/open_telemetry_decorator/OpenTelemetryDecorator.html

Decorate a function to include its return value as a span attribute. The result is included using the `:result` atom in the `include` list.

```elixir
defmodule MyApp.Math do
  use OpenTelemetryDecorator

  @decorate with_span("my_app.math.add", include: [:result])
  def add(a, b) do
    {:ok, a + b}
  end
end
```

--------------------------------

### Include Specific Struct Fields as Span Attributes

Source: https://hexdocs.pm/open_telemetry_decorator/OpenTelemetryDecorator.html

Decorate a function to include specific fields from a struct as span attributes. Use `@derive {O11y.SpanAttributes, only: [:field1, :field2]}` to specify which fields to include.

```elixir
defmodule User do
  use OpenTelemetryDecorator

  @derive {O11y.SpanAttributes, only: [:id, :name]}
  defstruct [:id, :name, :email, :password]

  @decorate with_span("user.create", include: [:user])
  def create(user) do
    {:ok, user}
  end
end
```

--------------------------------

### Include Local Variables in Span Attributes

Source: https://hexdocs.pm/open_telemetry_decorator/OpenTelemetryDecorator.html

Decorate a function to include specific local variables available at function exit as span attributes. Variables within conditional blocks like `if`, `case`, `cond`, or `with` are not available.

```elixir
defmodule MyApp.Math do
  use OpenTelemetryDecorator

  @decorate with_span("my_app.math.add", include: [:a, :b, :sum])
  def add(a, b) do
    sum = a + b
    {:ok, sum}
  end
end
```

--------------------------------

### Decorate Function with OpenTelemetry Span

Source: https://hexdocs.pm/open_telemetry_decorator/OpenTelemetryDecorator.html

Use the `with_span` decorator to instrument a function. You can specify span attributes by listing variable names, including `:result`, or nested map/struct properties.

```elixir
defmodule MyApp.Worker do
  use OpenTelemetryDecorator

  @decorate with_span("my_app.worker.do_work", include: [:arg1, [:arg2, :count], :total, :result])
  def do_work(arg1, arg2) do
    total = arg1.count + arg2.count
    {:ok, total}
  end
end
```

--------------------------------

### Set Additional Span Attributes Dynamically

Source: https://hexdocs.pm/open_telemetry_decorator/OpenTelemetryDecorator.html

Use `O11y.set_attributes/1` and `O11y.set_attribute/2` within the decorated function to add custom attributes to the span. Non-primitive values will be converted to strings using `Kernel.inspect/1`.

```elixir
defmodule MyApp.Worker do
  use OpenTelemetryDecorator

  @decorate with_span("worker.do_work")
  def do_work(arg1, arg2) do
    O11y.set_attributes(arg1: arg1, arg2: arg2)
    # ...doing work
    O11y.set_attribute(:output, "something")
  end
end
```
Tokens:
Raw