CouncilEx.Telemetry (CouncilEx v0.1.0)

Copy Markdown View Source

Helpers for emitting CouncilEx telemetry events.

Event prefixes:

  • [:council_ex, :run, :start | :stop | :exception]

  • [:council_ex, :round, :start | :stop | :exception]

  • [:council_ex, :member, :start | :stop | :exception]

  • [:council_ex, :provider, :request, :start | :stop | :exception]

[:council_ex, :member, :stop] payload

Designed so a handler can persist a complete per-member observability row without subscribing to PubSub or replaying round-level events.

Measurements:

%{
  duration:      integer,  # native time units
  input_tokens:  non_neg_integer,
  output_tokens: non_neg_integer
}

Metadata:

%{
  run_id:        String.t,
  member_id:     atom | String.t,
  member_module: module,
  round_name:    atom,
  round_idx:     non_neg_integer,
  model:         String.t | nil,
  provider:      atom | nil,
  status:        :ok | :error | :timeout | :skipped | :invalid_output | :eliminated,
  attempts:      pos_integer,
  confidence:    float | nil
}

cost_usd is intentionally not emitted — integrators compute spend from input_tokens, output_tokens, and their own pricing model.

Summary

Functions

attach_default_logger(opts \\ [])

Attach default Logger handlers to all CouncilEx telemetry events.

detach_default_logger()

Detach all default-logger handlers. Idempotent.

provider_request(metadata, fun)

Wrap a provider request invocation in telemetry events.

span(prefix, base_metadata, fun)

Functions

attach_default_logger(opts \\ [])

@spec attach_default_logger(keyword()) :: :ok

Attach default Logger handlers to all CouncilEx telemetry events.

Options

  • :level — Logger level for :start / :stop events (default :info). :exception events always log at :warning.
  • :events — list of event kinds to attach (default [:run, :round, :member, :provider]).

Idempotent: re-attach detaches the existing handlers first.

detach_default_logger()

@spec detach_default_logger() :: :ok

Detach all default-logger handlers. Idempotent.

provider_request(metadata, fun)

@spec provider_request(map(), (-> result)) :: result when result: term()

Wrap a provider request invocation in telemetry events.

Emits [:council_ex, :provider, :request, :start | :stop | :exception] around the function. Result classification is added to :stop metadata as :result.

metadata MUST include at minimum: :run_id, :member_id, :provider, :adapter, :model, :attempt. The Runner is responsible for populating it.

span(prefix, base_metadata, fun)

@spec span([atom()], map(), (-> {result :: term(), measurements :: map(),
                           metadata :: map()})) :: term()