Mailglass.Credo.TelemetryEventConvention (Mailglass v1.3.0)

Basics

This check has a base priority of high and works with any version of Elixir.

Explanation

Telemetry event names must follow mailglass's 4-level convention and start with :mailglass (or :mailglass_inbound for the inbound package).

The convention validates LITERAL atom-list event names at three call-site forms:

• direct :telemetry.execute/3 call sites — the full event name;
• direct :telemetry.span/3 call sites — the event PREFIX; and
• the package's own span-WRAPPER call sites — a call to a function whose name starts with span (span, span_with_enrichment), covering the inbound private wrapper, the outbound Mailglass.Telemetry.span/3, and the webhook span_with_enrichment/3. The literal event PREFIX lives here — this is where the inbound (and webhook) event names actually live.

The inbound package wraps every emission in a private span/3 that forwards a VARIABLE prefix to :telemetry.span/3; the literal full prefix lives at the span([...], ...) wrapper call sites inside the *_span/2 helpers. Validating the span-wrapper call site is what gives REAL inbound coverage — a literal-only :telemetry.span/3 clause would never fire on inbound code, because the inbound :telemetry.span call carries a variable.

The wrapper is matched by a span-prefixed name, NOT a *_span suffix: the public helpers END with _span and pass a PARTIAL suffix or no literal at their call site (outbound persist_span([:delivery, …], …) passes a suffix the wrapper prepends a root onto), so a suffix match would false-positive. The span-WRAPPER (span-prefixed) always carries the full literal prefix.

A :telemetry.span/3 prefix and a span/3 wrapper prefix are both validated against min_segments - 1 because the runtime appends :start/:stop/:exception to the prefix, so the emitted event name reaches the full segment count.

A NON-LITERAL (variable) prefix is intentionally NOT validated at any call-site form — including the private span/3 wrapper itself, whose :telemetry.span(event_prefix, ...) forwards a variable. That is not a gap: the literal lives one level up at the span([...], ...) wrapper call site, which IS covered. Validating the variable forward would only produce false positives.

Check-Specific Parameters

Use the following parameters to configure this check:

:required_root

Allowed first segment(s) in telemetry event lists. A single atom or a list of atoms.

This parameter defaults to :mailglass.

:min_segments

Minimum number of literal atom segments required.

This parameter defaults to 4.

General Parameters

Like with all checks, general params can be applied.

Parameters can be configured via the .credo.exs config file.