ExLLM.Infrastructure.Telemetry (ex_llm v0.8.1)

View Source

Telemetry instrumentation for ExLLM.

This module provides telemetry event definitions and helpers for instrumenting ExLLM operations. It follows the standard :telemetry conventions and can be integrated with various observability backends.

Event Structure

All events follow the pattern: [:ex_llm, :component, :operation, :phase]

Where phase is one of: :start, :stop, :exception

Integration Options

  1. Logging: Attach handlers to log events
  2. Metrics: Use ExLLM.Infrastructure.Telemetry.Metrics with telemetry_metrics
  3. Tracing: Use ExLLM.Infrastructure.Telemetry.OpenTelemetry for distributed tracing

Example

# Attach a simple logger
:telemetry.attach(
  "log-llm-requests",
  [:ex_llm, :chat, :stop],
  &MyApp.handle_event/4,
  nil
)

Summary

Functions

attach_default_logger(level \\ :debug)

Attach a basic logger handler for debugging.

This is useful during development to see all telemetry events.

detach_default_logger()

Detach the default logger.

emit_cache_hit(key)

Helper to emit cache events.

emit_cache_miss(key)

emit_cache_put(key, size_bytes)

emit_cost_calculated(provider, model, cost_cents)

Helper to emit cost events.

emit_cost_threshold_exceeded(cost_cents, threshold_cents)

emit_stream_chunk(provider, model, chunk_size)

emit_stream_complete(provider, model, total_chunks, duration)

emit_stream_start(provider, model)

Helper for streaming events.

events()

Returns all telemetry event names.

span(event_prefix, metadata \\ %{}, fun)

Execute a function and emit telemetry events.

This is the core instrumentation helper that emits start/stop/exception events and measures duration automatically.

Options

  • :telemetry_metadata - Additional metadata to include in events
  • :telemetry_options - Options like sampling rate

Example

span([:ex_llm, :chat], %{model: "gpt-4"}, fn ->
  # Your code here
  {:ok, result}
end)