# `Relyra.Telemetry`
[🔗](https://github.com/szTheory/relyra/blob/v1.1.0/lib/relyra/telemetry.ex#L1)

Telemetry catalog for Relyra SAML events.

Relyra emits events using the `[:relyra, :saml, event_name, stage]` namespace.
Each event follows the `:start`, `:stop`, and `:exception` triplet pattern and
reports durations in `duration_ms`.

## Events

### login
Emitted when an SP-initiated login flow starts.
- Namespace: `[:relyra, :saml, :login]`
- Measurements: `[:duration_ms]`
- Metadata: `[:connection_id, :organization_id, :provider_preset, :flow, :binding, :outcome, :error_code]`

### authn_request
Emitted when a SAML AuthnRequest is generated.
- Namespace: `[:relyra, :saml, :authn_request]`
- Measurements: `[:duration_ms, :xml_bytes, :base64_bytes, :request_store_latency_ms]`
- Metadata: `[:connection_id, :organization_id, :provider_preset, :flow, :binding, :outcome, :error_code]`

### response.decode
Emitted when an inbound SAMLResponse is base64-decoded and inflated.
- Namespace: `[:relyra, :saml, :response, :decode]`
- Measurements: `[:duration_ms, :base64_bytes, :xml_bytes]`
- Metadata: `[:connection_id, :binding, :flow, :outcome, :error_code]`

### response.validate
Emitted during the SAML protocol validation pipeline.
- Namespace: `[:relyra, :saml, :response, :validate]`
- Measurements: `[:duration_ms, :assertion_count]`
- Metadata: `[:connection_id, :flow, :outcome, :error_code]`

### signature.verify
Emitted when verifying XML signatures.
- Namespace: `[:relyra, :saml, :signature, :verify]`
- Measurements: `[:duration_ms]`
- Metadata: `[:connection_id, :outcome, :error_code, :signature_algorithm, :digest_algorithm]`

### replay.check
Emitted when checking for replayed assertions.
- Namespace: `[:relyra, :saml, :replay, :check]`
- Measurements: `[:duration_ms, :replay_store_latency_ms]`
- Metadata: `[:connection_id, :issuer, :assertion_id, :outcome, :error_code]`

### user.map
Emitted when mapping SAML principal to a host user.
- Namespace: `[:relyra, :saml, :user, :map]`
- Measurements: `[:duration_ms, :attribute_count]`
- Metadata: `[:connection_id, :flow, :outcome, :error_code]`

### session.establish
Emitted when handing off to the host session adapter.
- Namespace: `[:relyra, :saml, :session, :establish]`
- Measurements: `[:duration_ms]`
- Metadata: `[:connection_id, :flow, :outcome, :error_code]`

### metadata.refresh
Emitted when an operator-triggered metadata refresh starts or stops.
- Namespace: `[:relyra, :saml, :metadata, :refresh]`
- Measurements: `[:duration_ms]`
- Metadata: `[:connection_id, :metadata_source_id, :source_kind, :trigger, :outcome, :error_code, :certificate_count]`

### metadata.import
Emitted when an operator-triggered local XML import starts or stops.
- Namespace: `[:relyra, :saml, :metadata, :import]`
- Measurements: `[:duration_ms]`
- Metadata: `[:connection_id, :source_kind, :trigger, :outcome, :error_code, :certificate_count]`

### metadata.auto_refresh
Phase 21 scheduled metadata refresh. SEPARATE namespace from
`metadata.refresh` per D-23: adopters can attach the "page me" handler
only to the unattended channel.

- Namespace: `[:relyra, :saml, :metadata, :auto_refresh]`

Per-attempt span events (`Telemetry.span/3`):
- `[:relyra, :saml, :metadata, :auto_refresh, :start]`
- `[:relyra, :saml, :metadata, :auto_refresh, :stop]`
- `[:relyra, :saml, :metadata, :auto_refresh, :exception]`
  - Measurements: `[:duration_ms]`
  - Metadata: `[:connection_id, :metadata_source_id, :source_kind, :trigger, :correlation_id, :outcome, :error_code, :certificate_count, :transient?, :counts_toward_suspend?]`

State-transition events (one-shot, not span-bracketed):
- `[:relyra, :saml, :metadata, :auto_refresh, :degraded]` — first
  transient failure that increments `consecutive_failure_count` (D-24)
- `[:relyra, :saml, :metadata, :auto_refresh, :suspended]` — the
  attempt that crossed `consecutive_failure_count >= 5` and set
  `auto_suspended_until` (D-24, D-25)
- `[:relyra, :saml, :metadata, :auto_refresh, :recovered]` — successful
  probe after a suspended period; counters reset to 0 (D-24, Pitfall 6)
  - Measurements: `%{}`
  - Metadata: `[:connection_id, :metadata_source_id, :consecutive_failure_count, :auto_suspended_until, :auto_suspended_reason, :error_code]`

Validity warning event (at-most-once per validUntil window per source):
- `[:relyra, :saml, :metadata, :auto_refresh, :validity_warning]` (D-14)
  - Measurements: `%{}`
  - Metadata: `[:connection_id, :metadata_source_id, :valid_until, :refresh_interval_seconds]`

Empty-tick event:
- `[:relyra, :saml, :metadata, :auto_refresh, :skipped]` (D-07)
  - Measurements: `%{}`
  - Metadata: `[:correlation_id, :count]`

### certificate.expiring
Emitted when a SAML certificate is nearing expiration.
- Namespace: `[:relyra, :saml, :certificate, :expiring]`
- Measurements: `[:days_until_expiry]`
- Metadata: `[:connection_id, :certificate_id, :fingerprint_sha256, :not_after]`

Optional reference handler: `Relyra.Telemetry.Handlers.LogAlerts`
(D-30, NOT default-attached). Adopters call
`Relyra.Telemetry.Handlers.LogAlerts.attach/0` from their
`Application.start/2` to opt in.

---

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