# `Mailglass.Credo.TelemetryEventConvention`
[🔗](https://github.com/szTheory/mailglass/blob/v2.7.0/credo_checks/telemetry_event_convention.ex#L1)

## Basics

> #### This check is disabled by default. {: .neutral}
>
> [Learn how to enable it](`e:credo:config_file.html#checks`) via `.credo.exs`.

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](`e:credo:check_params.html`) can be applied.

Parameters can be configured via the [`.credo.exs` config file](`e:credo:config_file.html`).

---

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