AshHooks.Telemetry (AshHooks v2.0.2)

Copy Markdown View Source

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

Events carry identifiers, measurements, fixed atoms, and classified reasons. The package omits bodies, payloads, and resolved signing secrets. 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 five AshHooks.Errors.Invalid classes, or nil for unknown-class pre-verify failures)
  • [:ash_hooks, :ingress, :dedup] — %{source, outcome: :created | :duplicate}
  • [:ash_hooks, :ingress, :claim] — %{source, outcome: :claimed | :lease_held}
  • [: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, :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}

: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, :dispatch, :enqueue_failed],
  [:ash_hooks, :delivery, :attempt],
  [:ash_hooks, :delivery, :result],
  [:ash_hooks, :delivery, :backoff],
  [:ash_hooks, :delivery, :dead_letter],
  [:ash_hooks, :delivery, :disable]
], fn event, measurements, metadata, _ ->
  # Forward these measurements and identifiers to your metrics system.
end, nil)

Summary

Functions

The shared contents-free error classifier. Only the fixed internal vocabulary and HTTP status classifications survive. Caller-selected strings and atoms collapse to "unclassified", including strings that happen to have the same spelling pattern as an internal token.

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

classify_token(term)

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

The shared contents-free error classifier. Only the fixed internal vocabulary and HTTP status classifications survive. Caller-selected strings and atoms collapse to "unclassified", including strings that happen to have the same spelling pattern as an internal token.

fingerprint(secret)

@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.