Relyra.Telemetry (relyra v1.1.0)

Copy Markdown View Source

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.