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.
Summary
Functions
Attaches a Logger handler that logs one line per request.
Attaches the span tracer, which turns ImagePipe's telemetry events into OpenTelemetry spans through the OpenTelemetry API.
Detach the default Logger handler.
Remove the opt-in span tracer attached with attach_tracer/1.
Functions
@spec attach_default_logger(keyword()) :: :ok
Attaches a Logger handler that logs one line per request.
ImagePipe.Telemetry.attach_default_logger()The line is the [:request, :summary]
event: the method, path, status, duration, and bytes sent, then the
request's other fields as key=value. The fields are also in the line's
Logger metadata, as a map under :image_pipe. Cache sweeps and evictions,
which belong to no request, log their own lines, and so does a request
that raised, which has no summary. Failed and dropped cache writes also
log their own lines, at :warning, because a write can finish after its
request's line. With stages: true, every stage of each request
logs a line as well.
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. Without stages: true, only these
have lines: from :request, the summary and raised requests, and from
:cache, sweeps, evictions, and failed or dropped writes. The groups are:
:request: the request summary, and 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. A summary line logs at :error for a 5xx
response or one that failed partway through sending, and at :warning for
a 4xx, a degraded result, a cache read error, detection whose detector
failed, was unavailable, or isn't configured, a quality search that missed
its target or size limit, a result scaled down to fit the limits, or a
failed ImagePipe.run/4. A low-priority request that a full processing
pool turned away logs at :level. With stages: true, these stage lines
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
:busyand: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 thetelemetry_prefixImagePipe is configured with. The default value is[:image_pipe].:stages(boolean/0) - Whentrue, also logs a line for each stage of each request, such as parsing, each cache lookup, decoding, and encoding, for debugging. By default, each request logs one summary line. The default value isfalse.:debug(boolean/0) - Whentrue, also logs each event's raw measurements and metadata at:debug, including operation parameters. The default value isfalse.
Raises ArgumentError for invalid options.
@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.
Options
:prefix(list ofatom/0) - The telemetry prefix to subscribe to. Must match thetelemetry_prefixImagePipe is configured with. The default value is[:image_pipe].:extract_inbound(boolean/0) - Whentrue, a request with a valid W3Ctraceparentheader 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. The default value isfalse.:finch_spans(boolean/0) - Also records a span for each HTTP request a source makes through Finch, including connection setup.falserecords none. The default value istrue.
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).
@spec default_prefix() :: [atom()]
@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.