Telemetry integration for Sigra authentication events.
Sigra emits telemetry events for all authentication operations, enabling observability, monitoring, and custom instrumentation. Attach handlers to these events to integrate with your preferred monitoring solution.
Event Catalog
Authentication
[:sigra, :auth, :login, :start | :stop | :exception]- User login attempts[:sigra, :auth, :logout, :start | :stop | :exception]- User logout operations[:sigra, :auth, :register, :start | :stop | :exception]- User registration
Token Operations
[:sigra, :token, :generate, :start | :stop | :exception]- Token generation[:sigra, :token, :verify, :start | :stop | :exception]- Token verification
Email Delivery
[:sigra, :email, :deliver, :start | :stop | :exception]- Email delivery attempts
Confirmation
[:sigra, :confirmation, :verify, :start | :stop | :exception]- Confirmation verification
Session Lifecycle (span events — :start/:stop/:exception)
[:sigra, :session, :create, :start | :stop | :exception]- Session creation[:sigra, :session, :delete, :start | :stop | :exception]- Session deletion[:sigra, :session, :sudo, :start | :stop | :exception]- Sudo mode confirmation
Session Signals (one-shot events)
[:sigra, :session, :revoke_all, :stop]- All sessions revoked for a user
OAuth (span events)
[:sigra, :oauth, :authorize, :start | :stop | :exception]- OAuth authorize URL generation[:sigra, :oauth, :callback, :start | :stop | :exception]- OAuth callback processing
OAuth Signals (one-shot events)
[:sigra, :oauth, :link, :stop]- OAuth provider linked to account[:sigra, :oauth, :unlink, :stop]- OAuth provider unlinked from account[:sigra, :oauth, :refresh, :stop]- OAuth token refreshed[:sigra, :oauth, :register, :stop]- New user registered via OAuth[:sigra, :oauth, :login, :stop]- Existing user logged in via OAuth
MFA (span events -- :start/:stop/:exception)
[:sigra, :mfa, :enroll, :start | :stop | :exception]- TOTP enrollment. Metadata:%{user_id: id}. On stop:%{user_id: id, result: :success | :failure}.`[:sigra, :mfa, :verify, :start :stop :exception]` - MFA verification. Metadata: `%{user_id: id, method: :totp :backup_code} . On stop:%{user_id: id, method: atom, result: :success:failure, attempts_remaining: integer}`. [:sigra, :mfa, :disable, :start | :stop | :exception]- MFA disable. Metadata:%{user_id: id}. On stop:%{user_id: id, admin: boolean}.[:sigra, :mfa, :backup_codes, :regenerate, :start | :stop | :exception]- Backup code regeneration. Metadata:%{user_id: id}.
MFA Signals (one-shot events)
[:sigra, :mfa, :lockout]- MFA lockout triggered. Metadata:%{user_id: id, ip: string}. Log level::warning.[:sigra, :mfa, :pending_expired]- mfa_pending session expired. Metadata:%{user_id: id, ip: string}. Log level::warning.[:sigra, :mfa, :trust, :granted]- Trust cookie granted. Metadata:%{user_id: id}.[:sigra, :mfa, :trust, :revoked_all]- All trust revoked. Metadata:%{user_id: id}.
Security Signals (one-shot events)
[:sigra, :security, :rate_limited]- Rate limit exceeded[:sigra, :security, :lockout]- Account locked after failed attempts[:sigra, :security, :suspicious_login]- Login from new IP/device detected[:sigra, :security, :invalid_credentials]- Invalid credential submission[:sigra, :confirmation, :sent]- Confirmation email dispatched[:sigra, :reset, :requested]- Password reset requested[:sigra, :reset, :completed]- Password reset completed[:sigra, :token, :expired]- Token expired during verification
Metadata Policy
NEVER included: passwords, hashes, TOTP codes, bearer tokens, OAuth secrets. ALWAYS included: user_id (not email), boolean outcome, operation context.
Default Logger
Call attach_default_logger/1 to attach a handler that logs all Sigra events
at a configurable level (default :info). This follows the Oban pattern for
instant structured logging.
Sigra.Telemetry.attach_default_logger()
Sigra.Telemetry.attach_default_logger(level: :warning)Summary
Functions
Returns the list of account lifecycle telemetry event names.
Returns the list of API token-specific telemetry event names.
Attach the default Sigra logger handler.
Emit a one-shot telemetry event.
Returns the list of hook-related telemetry event names.
Returns the list of JWT-specific telemetry event names.
Returns the list of MFA-specific telemetry event names.
Returns the list of OAuth-specific telemetry event names.
Execute a function within a telemetry span.
Functions
@spec account_events() :: [[atom()]]
Returns the list of account lifecycle telemetry event names.
Includes email change, password change, and account deletion events. Useful for attaching custom handlers to all account lifecycle events.
@spec api_token_events() :: [[atom()]]
Returns the list of API token-specific telemetry event names.
Useful for attaching custom handlers to all API token events.
@spec attach_default_logger(keyword()) :: :ok | {:error, :already_exists}
Attach the default Sigra logger handler.
Attaches a telemetry handler named "sigra-default-logger" that logs all
Sigra :stop events and one-shot security events using Elixir's Logger.
Options
:level- The log level to use. Defaults to:info.:filter- A list of category atoms to filter events (e.g.,[:auth, :security]). When not provided, all events are logged.
Examples
:ok = Sigra.Telemetry.attach_default_logger()
{:error, :already_exists} = Sigra.Telemetry.attach_default_logger()
:ok = Sigra.Telemetry.attach_default_logger(level: :warning)Emit a one-shot telemetry event.
Wraps :telemetry.execute/3 for security signal events and other non-span
occurrences.
Examples
Sigra.Telemetry.event([:sigra, :security, :rate_limited], %{count: 1}, %{key: "ip:1.2.3.4"})@spec hook_events() :: [[atom()]]
Returns the list of hook-related telemetry event names.
Useful for monitoring hook execution failures.
@spec jwt_events() :: [[atom()]]
Returns the list of JWT-specific telemetry event names.
Useful for attaching custom handlers to all JWT events.
@spec mfa_events() :: [[atom()]]
Returns the list of MFA-specific telemetry event names.
Useful for attaching custom handlers to all MFA events.
@spec oauth_events() :: [[atom()]]
Returns the list of OAuth-specific telemetry event names.
Useful for attaching custom handlers to all OAuth events.
Execute a function within a telemetry span.
Wraps :telemetry.span/3 to emit :start, :stop, and :exception events
for the given event_prefix.
Examples
Sigra.Telemetry.span([:sigra, :auth, :login], %{user_id: 1}, fn ->
{:ok, user}
end)