@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.

Event groups

:events selects groups from the event reference:

• :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 (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.

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

Attaches the span tracer, which builds spans from ImagePipe's telemetry events and passes each finished span to an exporter.

ImagePipe.Telemetry.attach_tracer(exporter: ImagePipe.Telemetry.Trace.LogExporter)

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.

Options

• :exporter (atom/0) - Required. A module implementing ImagePipe.Telemetry.Trace.Exporter, such as ImagePipe.Telemetry.Trace.LogExporter or ImagePipe.Telemetry.Trace.OpenTelemetryExporter.

• :prefix (list of 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 (boolean/0) - When true, a request with a valid W3C traceparent header (version 00, lowercase hexadecimal fields, non-zero IDs) continues the caller's trace. Enable it only when a proxy you control sets the header or removes it from outside requests. See inbound trace context. The default value is false.

• :finch_spans (boolean/0) - Also records a span for each HTTP request a source makes through Finch, including connection setup. false removes a Finch handler attached earlier. The default value is true.

Raises ArgumentError for invalid options, or for an exporter that can't be loaded, has no export/1, or whose ready?/0 returns false.

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

Detach the default Logger handler.

@spec detach_tracer() :: :ok

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