@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})

@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.

@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.

@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.

@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.

@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.

@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.

@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.

@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)

@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.