# `ImagePipe.Telemetry`
[🔗](https://github.com/hlindset/image_pipe/blob/v0.2.0/image_pipe/lib/image_pipe/telemetry.ex#L1)

Attaches ImagePipe's optional Logger handler and span tracer.

ImagePipe emits `:telemetry` events and attaches no handlers itself.
`attach_default_logger/1` logs them with `Logger`, and `attach_tracer/1`
turns them into trace spans. The events are listed in the
[event reference](telemetry-events.md).

# `attach_default_logger`

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

Attaches a `Logger` handler that logs one line per ImagePipe event.

    ImagePipe.Telemetry.attach_default_logger(events: [:request, :source])

Call it once at application startup. Calling it again replaces the
handler's options. Remove it with `detach_default_logger/0`. Setting it up
is covered in [Monitoring with telemetry](telemetry.md).

## Event groups

`:events` selects groups from the
[event reference](telemetry-events.md):

  * `:request`: request, processing pool, send, deliver, and encode events,
    except the encode-search probe cost spans, which aren't logged.
  * `:parse`: parsing and preset lookup.
  * `:source`: source events.
  * `:transform`: transform and detection events.
  * `:cache`: cache events.
  * `:output`: output format negotiation, info and placeholder bodies, and
    output clamping.
  * `:http_cache`: HTTP cache header events.
  * `:debug`: debug header collection errors.

## Log levels

Lines log at `:level`. These log at `:warning`:

  * Exceptions, and results such as `:source_error`, `:cache_error`,
    `:materialize_error`, `:parser_error`, and `:plan_error`.
  * Encode, color-management, output negotiation, info or placeholder, and
    preset lookup failures.
  * Processing pool rejections, timeouts, and worker failures.
  * Detection that fell back to attention (`:unavailable`, `:error`, or no
    detector configured).
  * A quality search with outcome `:best_effort`.
  * An output clamp, a debug collection error, and cache coordination
    results `:busy` and `:bypass`.

## Options

* `:level` - The level for ordinary lines. Failures and degraded results log at `:warning`. The default value is `:info`.

* `:events` - `:all`, or a list of the event groups to log. See the groups above. The default value is `:all`.

* `:prefix` - The telemetry prefix to subscribe to, a non-empty list of atoms. Must match the `telemetry_prefix` ImagePipe is configured with. The default value is `[:image_pipe]`.

* `:debug` (`t:boolean/0`) - When `true`, also logs each event's raw measurements and metadata at `:debug`, including operation parameters. The default value is `false`.

Raises `ArgumentError` for invalid options.

# `attach_tracer`

```elixir
@spec attach_tracer(keyword()) :: :ok
```

Attaches the span tracer, which turns ImagePipe's telemetry events into
OpenTelemetry spans through the OpenTelemetry API.

    ImagePipe.Telemetry.attach_tracer()

Your application provides and configures the OpenTelemetry SDK. ImagePipe
depends on `:opentelemetry_api` as an optional dependency.

Call it once at application startup. Calling it again replaces the whole
tracer configuration. Remove it with `detach_tracer/0`. How spans form a
trace is explained in [Request tracing](tracing.md).

## Options

* `:prefix` (list of `t:atom/0`) - The telemetry prefix to subscribe to. Must match the `telemetry_prefix` ImagePipe is configured with. The default value is `[:image_pipe]`.

* `:extract_inbound` (`t:boolean/0`) - When `true`, a request with a valid W3C `traceparent` header continues the caller's trace, unless a span of your own is already current. Enable it only when a proxy you control sets the header or removes it from outside requests. See [inbound trace context](tracing.md#inbound-trace-context). The default value is `false`.

* `:finch_spans` (`t:boolean/0`) - Also records a span for each HTTP request a source makes through Finch, including connection setup. `false` records none. The default value is `true`.

Raises `ArgumentError` for invalid options, or when ImagePipe was compiled
without `:opentelemetry_api`. Add `:opentelemetry` to your dependencies and
recompile ImagePipe (`mix deps.compile image_pipe --force`).

# `default_prefix`

```elixir
@spec default_prefix() :: [atom()]
```

# `detach_default_logger`

```elixir
@spec detach_default_logger() :: :ok | {:error, :not_found}
```

Detach the default Logger handler.

# `detach_tracer`

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

Remove the opt-in span tracer attached with `attach_tracer/1`.

---

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