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_signatureor: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_classis 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 becomeunclassified, 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 incrementsunreadand preserves this endpoint's warning marker.[:ash_hooks, :key_registry, :destroy_failed]: measurement%{count: 1}; metadata%{registry: module, ref: reference, reason: reason}, wherereasonis:tenant_mismatchor: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:
: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
)
Summary
Functions
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.
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.
Functions
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.
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.