ExDataSketch.Telemetry.OpenTelemetry (ExDataSketch v0.10.0)

Copy Markdown View Source

OpenTelemetry span integration for ExDataSketch telemetry events.

This module bridges ExDataSketch's :telemetry events to OpenTelemetry spans when the :opentelemetry_api dependency is available. It attaches handlers that create spans for sketch, persistence, stream, and pipeline events.

Dependency

This module requires the :opentelemetry_api package. If it is not available, calling setup/0 will raise an error directing the user to add it as a dependency.

Usage

# In your application's `start/2` callback:
ExDataSketch.Telemetry.OpenTelemetry.setup()

This attaches handlers for all ExDataSketch telemetry events and creates corresponding OpenTelemetry spans with appropriate attributes.

Span Attributes

Each span includes the following attributes:

  • ex_data_sketch.sketch_type -- the sketch type (e.g., :hll, :cms)
  • ex_data_sketch.backend -- the persistence backend (for persistence events)
  • ex_data_sketch.key -- the storage key (for persistence events)
  • ex_data_sketch.merge_count -- number of sketches merged
  • ex_data_sketch.item_count -- number of items ingested
  • ex_data_sketch.size_bytes -- serialized size in bytes
  • ex_data_sketch.category -- event category (:sketch, :persistence, etc.)

Configuration

OpenTelemetry integration can be disabled via application config:

config :ex_data_sketch, :integrations, opentelemetry: false

When not explicitly configured, availability defaults to whether :opentelemetry_api is loaded at runtime.

Summary

Functions

handle_event(event_name, measurements, metadata, config)

Telemetry handler callback that starts and ends an OpenTelemetry span for a single :telemetry event.

setup()

Attaches OpenTelemetry span handlers for all ExDataSketch telemetry events.

teardown()

Detaches all OpenTelemetry handlers previously attached by setup/0.

Functions

handle_event(event_name, measurements, metadata, config)

@spec handle_event([atom(), ...], map(), map(), term()) :: :ok

Telemetry handler callback that starts and ends an OpenTelemetry span for a single :telemetry event.

This function is attached by setup/0 as a remote function capture (rather than an anonymous function or a local capture) so that :telemetry can dispatch to it without the performance penalty :telemetry warns about for local captures. It is public so it can be captured as &__MODULE__.handle_event/4 and is not intended to be called directly.

Examples

ExDataSketch.Telemetry.OpenTelemetry.handle_event(
  [:ex_data_sketch, :sketch, :ingest],
  %{duration: 100, count: 50},
  %{sketch_type: :hll},
  nil
)
:ok

setup()

@spec setup() :: :ok | {:error, term()}

Attaches OpenTelemetry span handlers for all ExDataSketch telemetry events.

Creates one handler per event that starts an OTEL span with the event's measurements and metadata as span attributes. When a duration measurement is present, the span's start and end times are set from it, producing a span with the correct duration. Events without a duration measurement produce signalling spans (start time equals end time).

Calling setup/0 when the :opentelemetry_api package is not available raises an error with installation instructions.

Examples

ExDataSketch.Telemetry.OpenTelemetry.setup()
:ok

teardown()

@spec teardown() :: :ok

Detaches all OpenTelemetry handlers previously attached by setup/0.

Examples

ExDataSketch.Telemetry.OpenTelemetry.teardown()
:ok