# `ExDataSketch.Telemetry.OpenTelemetry`
[🔗](https://github.com/thanos/ex_data_sketch/blob/main/lib/ex_data_sketch/telemetry/open_telemetry.ex#L1)

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.

# `handle_event`

```elixir
@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`

```elixir
@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`

```elixir
@spec teardown() :: :ok
```

Detaches all OpenTelemetry handlers previously attached by `setup/0`.

## Examples

    ExDataSketch.Telemetry.OpenTelemetry.teardown()
    :ok

---

*Consult [api-reference.md](api-reference.md) for complete listing*