# `Malla.Plugins.Tracer`
[🔗](https://github.com/netkubes/malla/blob/main/lib/malla/plugins/tracer.ex#L21)

Plugin that provides observability callbacks for Malla services.

This module defines the callback interface that telemetry plugins can override
to integrate with observability backends (OpenTelemetry, Datadog, etc.).

For the user-facing API, see `Malla.Tracer`.

For comprehensive documentation, see the guide:
- **[Tracing and Instrumentation](guides/09-observability/01-tracing.md)**: For a guide on how to use the tracer.

# `span_id`

```elixir
@type span_id() :: Malla.Tracer.span_id()
```

# `malla_span`
*optional* 

```elixir
@callback malla_span(span_id(), keyword(), (-> any())) :: any()
```

Creates a tracing span around the given code block.

Called when user code uses `Malla.Tracer.span/2` or `span/3` macros.

By default, it will simply:
1. Call `Malla.metric([:malla, :tracer, :starts], %{counter: 1}, %{span_name: name, opts: opts})`
2. Execute the code
3. Call `Malla.metric([:malla, :tracer, :stops], %{counter: 1}, %{span_name: name, result: res})`

# `malla_span_error`
*optional* 

```elixir
@callback malla_span_error(any(), keyword() | map()) :: any()
```

Record an error within the current span.

Called when user code calls `Malla.Tracer.error/1` with a non-string value.

It simply returns the error unchanged.

# `malla_span_event`
*optional* 

```elixir
@callback malla_span_event(span_id(), keyword() | map(), keyword() | map()) :: :ok
```

Record an event within a span.

Called when user code calls `Malla.Tracer.event/1`, `event/2`, or `event/3`.

By default it does nothing.

# `malla_span_get_base`
*optional* 

```elixir
@callback malla_span_get_base() :: any()
```

Get the base span context for propagation.

Called when user code calls `Malla.Tracer.get_base/0`.

By default it returns `nil`.

# `malla_span_globals`
*optional* 

```elixir
@callback malla_span_globals(keyword() | map()) :: :ok
```

Set global attributes that apply to all spans in this context.

Called when user code calls `Malla.Tracer.globals/1`.

By default it does nothing.

# `malla_span_info`
*optional* 

```elixir
@callback malla_span_info(keyword()) :: map() | nil
```

Retrieve information about the current span.

Called when user code calls `Malla.Tracer.get_info/0` or `get_info/1`.

By default it returns `nil`.

# `malla_span_labels`
*optional* 

```elixir
@callback malla_span_labels(keyword() | map()) :: :ok
```

Set labels for the current span.

Called when user code calls `Malla.Tracer.labels/1`.

By default it does nothing.

# `malla_span_log`
*optional* 

```elixir
@callback malla_span_log(
  atom() | pos_integer(),
  String.t() | (-> String.t()),
  keyword() | map()
) :: :ok
```

Log a message within the current span.

Called when user code calls logging macros like `debug/1`, `info/1`, etc.

By default it delegates to Elixir's `Logger.bare_log/3` with appropriate level mapping.

# `malla_span_metric`
*optional* 

```elixir
@callback malla_span_metric(span_id(), number() | keyword() | map(), keyword() | map()) ::
  :ok
```

Record a metric within a span.

Called when user code calls `Malla.Tracer.metric/2` or `metric/3`.

By default it calls `Malla.metric([:malla, :tracer, id], data, meta)`

# `malla_span_update`
*optional* 

```elixir
@callback malla_span_update(keyword()) :: :ok
```

Update the current span with new attributes.

Called when user code calls `Malla.Tracer.span_update/1`.

By default it does nothing.

---

*Consult [api-reference.md](api-reference.md) for complete listing*