# `AshHooks.Telemetry`
[🔗](https://github.com/baselabs/ash_hooks/blob/v3.3.0/lib/ash_hooks/telemetry.ex#L1)

Lifecycle events for ingress, queue admission, outbound delivery, and key disposal.

Events carry identifiers, measurements, fixed atoms, and classified reasons.
Package-generated metadata omits bodies, payloads, and resolved signing secrets.
Ingress failure classes can include host-provided text, as described below. For a
secret fingerprint in your own event, `AshHooks.Telemetry.fingerprint/1`
returns an eight-character hexadecimal value; package events do not use it.

Attach handlers to consume these best-effort `:telemetry.execute/3` events:

  * `[:ash_hooks, :ingress, :verify]`: `%{duration_ms}`; `%{source,
    outcome: :ok | :invalid, reason: atom | nil}` (the underscored error-struct name, such as `:invalid_signature` or
    `:unknown_error`; paused sources use `:source_paused`; success uses nil)
  * `[:ash_hooks, :ingress, :dedup]`: `%{source, outcome: :created |
    :duplicate}`
  * `[:ash_hooks, :ingress, :claim]`: `%{source, outcome: :claimed |
    :lease_held}`
  * `[:ash_hooks, :ingress, :failure]`: `%{count: 1}`; `%{source,
    error_class: binary, permanent?: boolean}` after a failure is recorded;
    stale fencing tokens emit nothing. `error_class` is exactly the bounded
    class recorded on the ledger row, including host-provided classes from
    `{:error, :retry | :permanent, term}`. Valid binary classes are capped at
    255 UTF-8 bytes, atoms use their names, other terms become `unclassified`,
    and invalid UTF-8 becomes `[binary]`. Hosts must not put secrets or payload
    data in this class; it is not restricted to the package's fixed vocabulary
  * `[:ash_hooks, :dispatch, :enqueue_failed]`: `%{endpoint_id,
    event_uuid, reason}` (classified, contents-free)
  * `[:ash_hooks, :delivery, :attempt]`: `%{endpoint_id, event_uuid,
    attempts}`
  * `[:ash_hooks, :delivery, :sign]`: measurement `%{duration: native_time}`;
    metadata `%{outcome: :ok | :skip | :retry | :terminal | :invalid_result |
    :callback_failed}`. Contains no callback terms or key material.
  * `[:ash_hooks, :delivery, :result]`: `%{endpoint_id, event_uuid,
    status: :succeeded | :failed_retryable | :dead_letter,
    response_status: integer | nil, reason: binary | nil}`
  * `[:ash_hooks, :delivery, :backoff]`: `%{endpoint_id, event_uuid,
    attempts, delay_seconds}`
  * `[:ash_hooks, :delivery, :dead_letter]`: `%{endpoint_id,
    event_uuid, reason, response_status}`
  * `[:ash_hooks, :delivery, :disable]`: `%{endpoint_id, reason:
    :gone_410}`
  * `[:ash_hooks, :worker, :invalid_runtime_config]`: `%{reason:
    binary}` (the fixed validation vocabulary: `callback_failed`,
    `unknown_key`, `not_positive_integer`, `backoff_inversion`,
    `envelope_exceeded`, `oban_ceiling_exceeded`); the job failed before
    any delivery work and the delivery row is untouched
  * `[:ash_hooks, :attempt, :record_failed]`: `%{endpoint_id,
    event_uuid, reason}` (classified): an attempt-history row could not
    be written; the delivery's result transition completed, but storing its
    attempt-history row failed
  * `[:ash_hooks, :delivery, :resend]`: `%{endpoint_id, event_uuid,
    requested_by}`: a terminal delivery was re-armed, or event-log replay created its first delivery
  * `[:ash_hooks, :delivery, :test]`: `%{endpoint_id, type}`: a signed
    synthetic test event is about to send (outside subscriptions; the
    payload marks itself when synthesized)
  * `[:ash_hooks, :endpoint, :roll]`: `%{endpoint_id}`: an endpoint's
    signing secret reference was rolled (the overlap window began)
  * `[:ash_hooks, :event, :record_failed]`: `%{event_uuid, reason}`
    (classified): the event log could not record a dispatched event;
    the fanout was unaffected
  * `[:ash_hooks, :endpoint, :disable_warning]`: `%{endpoint_id,
    failure_share, attempts}`: the sustained-failure policy sees an
    endpoint failing at the warning thresholds; notify before the
    breaker opens
  * `[:ash_hooks, :endpoint, :disable]`: `%{endpoint_id, reason}`:
    confirmed sustained-failure disables (`:sustained_failure`), emitted only
    after the write succeeds. HTTP 410 disablement uses
    `[:ash_hooks, :delivery, :disable]`

  * `[:ash_hooks, :endpoint_health, :read_failed]`: measurement `%{count: 1}`;
    metadata `%{endpoint_id, reason}`: attempt history could not be read.
    The sweep increments `unread` and preserves this endpoint's warning marker.
  * `[:ash_hooks, :key_registry, :destroy_failed]`: measurement `%{count: 1}`;
    metadata `%{registry: module, ref: reference, reason: reason}`, where
    `reason` is `:tenant_mismatch` or `:unclassified`. The reference's
    destruction could not complete and requires operator repair and rearming.

`:telemetry.execute/3` matches exact event names, so consume the
whole surface with one `attach_many`:

<!-- not-run: This integration requires the host metrics callback to forward the supplied event data. -->

    :telemetry.attach_many(
      "my-ash-hooks",
      [
        [:ash_hooks, :ingress, :verify],
        [:ash_hooks, :ingress, :dedup],
        [:ash_hooks, :ingress, :claim],
        [:ash_hooks, :ingress, :failure],
        [:ash_hooks, :dispatch, :enqueue_failed],
        [:ash_hooks, :delivery, :attempt],
        [:ash_hooks, :delivery, :result],
        [:ash_hooks, :delivery, :backoff],
        [:ash_hooks, :delivery, :dead_letter],
        [:ash_hooks, :delivery, :disable],
        [:ash_hooks, :worker, :invalid_runtime_config],
        [:ash_hooks, :attempt, :record_failed],
        [:ash_hooks, :delivery, :resend],
        [:ash_hooks, :delivery, :test],
        [:ash_hooks, :endpoint, :roll],
        [:ash_hooks, :endpoint, :disable_warning],
        [:ash_hooks, :endpoint, :disable],
        [:ash_hooks, :endpoint_health, :read_failed],
        [:ash_hooks, :event, :record_failed],
        [:ash_hooks, :key_registry, :destroy_failed]
      ],
      fn event, measurements, metadata, _ ->
        nil
        # Forward these measurements and identifiers to your metrics system.
      end,
      nil
    )

# `classify_token`

```elixir
@spec classify_token(term()) :: binary()
```

Classifies reasons using the recognized reason vocabulary and valid HTTP
status tokens. Recognized strings and atoms pass through regardless of origin.
Other values become `unclassified`. This function does not distinguish
package-generated tokens from caller-supplied values.

# `fingerprint`

```elixir
@spec fingerprint(binary()) :: String.t()
```

Returns the first eight hexadecimal characters of a secret's SHA-256 hash
for correlation. Collisions are possible; do not use this fingerprint as a
unique identifier or authentication credential.

This correlation-only hash has a different domain from display key
fingerprints. It does not protect a weak or predictable secret from
offline guessing; show fingerprints only for securely generated keys.

---

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