Skip to main content

Logging

Set the log level and destinations, keep per-session protocol logs for troubleshooting, and bound the audit log. Metrics and traces are covered in Monitoring.

KeyTypeAllowed valuesNotes
LOG_LEVELstringtrace, debug, info, warn, error, fatalApplication log level [optional] (default: warn when NODE_ENV is production (as in the container image), otherwise debug)
LOG_ENABLE_HTTP_LOGGERboolean-Enable HTTP request logging [optional] (default: false)
LOG_HTTP_RESPONSE_BODYboolean-Capture and log HTTP response bodies (buffered up to LOG_HTTP_RESPONSE_BODY_MAX_LENGTH bytes). Disabled by default because response bodies may contain access tokens, credentials, or other sensitive data. [optional] (default: false)
LOG_HTTP_RESPONSE_BODY_MAX_LENGTHnumber-Maximum number of bytes to capture for HTTP response bodies. Set to 0 to disable truncation. [optional] (default: 4096)
LOG_REDACT_SENSITIVE_DATAboolean-Redact sensitive request/response fields from logs. Disable only for debugging. [optional] (default: true)
LOG_OID4VP_DECRYPTED_RESPONSEboolean-Log decrypted OID4VP authorization responses. Disable by default because responses may contain personal data and credentials. [optional] (default: false)
LOG_ENABLE_SESSION_LOGGERboolean-Enable session flow logging [optional] (default: false)
LOG_SESSION_STOREstringoff, errors, all, verboseControls whether session log entries are persisted to the database. 'off' disables storage, 'errors' stores only warn/error entries, 'all' stores everything, 'verbose' stores everything including full request/response bodies and error stacks. [optional] (default: off)
LOG_TO_FILEboolean-Enable logging to file in addition to console [optional] (default: false)
LOG_FILE_PATHstring-File path for log output when LOG_TO_FILE is enabled [optional] (default: ./logs/session.log)
AUDIT_LOG_RETENTION_DAYSnumber-Delete tenant activity audit log entries older than N days. Set to 0 to disable time-based pruning. [optional] (default: 0)
OTEL_SDK_DISABLEDboolean-Disable OpenTelemetry SDK (and OTel log forwarding) [optional] (default: false)
AUDIT_LOG_MAX_ENTRIES_PER_TENANTnumber-Keep only the newest N tenant activity audit log entries per tenant. Set to 0 to disable count-based pruning. [optional] (default: 0)

Log level and destinations​

LOG_LEVEL accepts trace, debug, info, warn, error and fatal. Its default is debug, but warn when NODE_ENV=production, which the container image sets. Set LOG_LEVEL=info to see startup and flow messages in a container.

The backend writes logs to up to three destinations at the same level:

DestinationFormatEnabled by
Console (stdout)Human-readable (pino-pretty)always
FileJSON, one object per lineLOG_TO_FILE=true, path LOG_FILE_PATH
OpenTelemetry (Loki)OTLP log records with trace IDsalways, unless OTEL_SDK_DISABLED=true (Monitoring)

For structured logs in a log platform, use the OpenTelemetry export or the JSON file. The file is not rotated; use logrotate or similar.

HTTP request logs​

LOG_ENABLE_HTTP_LOGGER=true logs requests and responses of the wallet-facing endpoints. Management API calls (/api/...) and /health are never logged this way. With LOG_REDACT_SENSITIVE_DATA=true (default), these values are replaced by [redacted]: the Authorization, Cookie, DPoP, OAuth-Client-Attestation and OAuth-Client-Attestation-PoP request headers, Set-Cookie, and the response fields access_token, refresh_token, id_token, c_nonce, credential, credentials and attestation_challenge.

LOG_HTTP_RESPONSE_BODY=true adds response bodies (up to LOG_HTTP_RESPONSE_BODY_MAX_LENGTH bytes). Bodies can contain credentials and personal data; enable it only while debugging.

To inspect decrypted wallet responses during local debugging, set both LOG_LEVEL=trace and LOG_OID4VP_DECRYPTED_RESPONSE=true. These logs contain personal data; never enable this in shared or production environments.

Session logs​

Session logs record the protocol steps of one issuance or presentation session, for example authorization, token exchange, credential issuance or presentation verification, with errors. Enable them and choose what is stored in the database:

LOG_ENABLE_SESSION_LOGGER=true
LOG_SESSION_STORE=errors
LOG_SESSION_STOREStored
off (default)Nothing; events go only to the log destinations
errorsWarnings and errors
allAll events
verboseAll events with full request and response bodies and error stacks

LOG_SESSION_STORE has no effect without LOG_ENABLE_SESSION_LOGGER=true. Read the entries with GET /api/session/:id/logs (role issuance:offer for issuance sessions, presentation:request for presentation sessions, sessions:read for both) or in the Logs tab of a session in the web client. They are deleted with their session (session retention). verbose stores personal data and much more volume; use it for debugging only.

Correlate logs with sessions​

Once a request has resolved its session (by offer ID, walletNonce, issuer_state, code or access token), every following log line of that request, including the HTTP request log, carries sessionId and tenantId. This works with or without OpenTelemetry; with it, the request span and the span handling the session also get session.id.

  • Wallet-facing paths carry the session's walletNonce, with which anyone can fetch the credential offer or answer the presentation request. Logged URLs and the url.path span attribute replace it with [redacted] in /issuers/{tenant}/vci/credential-offers/{walletNonce}, /presentations/{walletNonce}/oid4vp/... and /presentations/{walletNonce}/iso-18013-7, and the auth_session in /issuers/{tenant}/authorize/interactive/complete-web-auth/{auth_session}. Since 10.0; 9.x logged the nonce in the URL and as req.walletNonce.
  • The values of the query parameters q (session and audit log search; a session search can contain a pre-authorized code), issuer_state, request_uri, code and response_code are always replaced by [redacted] in logged URLs and in the url.query span attribute.

To go from a log line or a pasted offer link to the session, search the session list with GET /api/session?q=... (Finding sessions).

Audit log​

Changes to a tenant and to its credential, issuance, presentation and status-list configurations, webhook endpoints, attribute providers, federation trust anchors and the clients of the OpenID Provider and their secrets are recorded with actor, time and changed fields, as are bundle imports, exports, exports of single resources as documents (config_resource_exported, with kind and ID), detach and reattach actions, generated client secrets and cancelled sessions (with the reason). Secrets are not recorded: the API keys of webhook endpoints and attribute providers and the upstream client secrets of chained authorization servers appear as [REDACTED], and a changed secret is still listed among the changed fields. Not audited: key chains, trust lists, API clients and users (including role changes and secret rotation), KMS provider configuration, and session retention settings.

Read the audit log under Administration → Activity Logs in the web client, or with role audit:read or clients:manage through the API:

EndpointReturns
GET /api/admin/audit-logs/searchOne page (page, pageSize up to 100) of the matching entries, newest first, with total
GET /api/admin/audit-logsThe newest matching entries as an array, at most limit (1–500, default 100)
GET /api/admin/audit-logs/retentionThe retention limits below, so a client can tell pruned entries from a quiet period

Both list endpoints take the same filters; all given filters must match. The search endpoint rejects unknown parameters, the list endpoint ignores them:

ParameterMatches
from, toRecorded at or after / at or before this time, ISO 8601 with offset
actionTypeOne of these actions, e.g. oidc_client_deleted; repeat the parameter for several
objectTypeAll actions on one kind of object, e.g. oidc_client (not its secrets, which are oidc_client_secret)
actorType, actorIduser, client or system; the id of the user or client
qText in the action (credential_config_created or Credential Config Created), in the actor's id or the client it used (actorId, actorDisplay), or in a changed field's name. Ignores case; on SQLite only for ASCII letters
requestIdThe X-Request-Id header of the call that caused the entry, to match it with your proxy or client logs. Recorded only when the caller or a reverse proxy sets the header
GET /api/admin/audit-logs/search?from=2026-11-17T14:00:00Z&to=2026-11-17T14:30:00Z&objectType=oidc_client

The web client keeps its filters in the URL, so a filtered view can be shared.

The audit log is kept forever unless the operator limits it. Tenants cannot delete entries; a daily job at 03:00 applies these limits to every tenant:

AUDIT_LOG_RETENTION_DAYS=365 # delete entries older than this, 0 = keep
AUDIT_LOG_MAX_ENTRIES_PER_TENANT=10000 # keep only the newest N per tenant, 0 = all

Each run writes one audit_log_pruned entry from the system actor for each tenant whose entries it deleted. after.deletedEntries is the number of deleted entries, and after names the limits that deleted them: retentionDays with olderThan, maxEntriesPerTenant, or both. With AUDIT_LOG_MAX_ENTRIES_PER_TENANT, that entry counts towards the limit. Earlier audit_log_pruned entries are deleted like any other entry but are not counted, and a run that deletes only those writes no new entry, so a tenant without other activity does not get a new entry every night.

Use session logs to answer "what happened in this flow?" and the audit log for "who changed the configuration, and when?".