Jido.Observe.Tracer behaviour (Jido v2.3.0)

Copy Markdown View Source

Behaviour for tracing backends.

Implement this behaviour to integrate OpenTelemetry or other tracing systems. The default implementation is Jido.Observe.NoopTracer which does nothing.

Example Implementation

A future jido_otel package could implement this:

defmodule JidoOtel.Tracer do
  @behaviour Jido.Observe.Tracer

  def span_start(event_prefix, metadata) do
    # Create OpenTelemetry span and return context
  end

  def span_stop(tracer_ctx, measurements) do
    # End the span with success status
  end

  def span_exception(tracer_ctx, kind, reason, stacktrace) do
    # End the span with error status
  end
end

Summary

Callbacks

Called when a span completes with an exception.

Called when a span starts.

Called when a span completes successfully.

Optional synchronous span callback.

Types

event_prefix()

@type event_prefix() :: [atom()]

measurements()

@type measurements() :: map()

metadata()

@type metadata() :: map()

result()

@type result() :: term()

tracer_ctx()

@type tracer_ctx() :: term()

Callbacks

span_exception(tracer_ctx, kind, reason, stacktrace)

@callback span_exception(
  tracer_ctx(),
  kind :: atom(),
  reason :: term(),
  stacktrace :: list()
) :: :ok

Called when a span completes with an exception.

span_start(event_prefix, metadata)

@callback span_start(event_prefix(), metadata()) :: tracer_ctx()

Called when a span starts.

Returns context to be passed to span_stop/2 or span_exception/4.

span_stop(tracer_ctx, measurements)

@callback span_stop(tracer_ctx(), measurements()) :: :ok

Called when a span completes successfully.

with_span_scope(event_prefix, metadata, function)

(optional)
@callback with_span_scope(event_prefix(), metadata(), (-> result())) :: result()

Optional synchronous span callback.

When implemented, Jido.Observe.with_span/3 will call this callback for sync spans instead of the span_start/span_stop/span_exception lifecycle trio.

Callback contract:

  • Call the provided function in the caller process
  • Call the provided function exactly once
  • Preserve the function's return value
  • Preserve the function's exception/throw/exit semantics