Logging Configuration¶

The EUDIPLO Service provides flexible logging configuration to help with debugging, monitoring, and auditing.

Configuration¶

Key	Type	Notes
`LOG_LEVEL`	`string`	Application log level (default: `debug`)
`LOG_ENABLE_HTTP_LOGGER`	`boolean`	Enable HTTP request logging (default: `false`)
`LOG_ENABLE_SESSION_LOGGER`	`boolean`	Enable session flow logging (default: `false`)
`LOG_SESSION_STORE`	`string`	Controls 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. (default: `off`)
`LOG_DEBUG_MODE`	`boolean`	Enable verbose debug logs (default: `false`)
`LOG_FORMAT`	`string`	Log output format (default: `pretty`)
`LOG_TO_FILE`	`boolean`	Enable logging to file in addition to console (default: `false`)
`LOG_FILE_PATH`	`string`	File path for log output when LOG_TO_FILE is enabled (default: `./logs/session.log`)

Basic Log Level Configuration¶

Control the overall log level using the LOG_LEVEL environment variable:

# Show all logs (debug, info, warn, error)
LOG_LEVEL=debug

# Show only info, warn, error (default)
LOG_LEVEL=info

# Show only warnings and errors
LOG_LEVEL=warn

# Show only errors
LOG_LEVEL=error

Logging Destinations¶

Console Logging¶

Console logging is always enabled with formatting determined by the LOG_FORMAT configuration:

# Pretty formatting for human readability (default in development)
LOG_FORMAT=pretty

# JSON formatting for machine parsing (default in production)
LOG_FORMAT=json

File Logging¶

The application supports logging to both console and file simultaneously, which is useful for debugging, auditing, and persisting logs for later analysis.

File logging is controlled via environment variables:

Variable	Description	Default
`LOG_TO_FILE`	Enable logging to file	`false`
`LOG_FILE_PATH`	Path to the log file	`./logs/session.log`

When LOG_TO_FILE is set to true, the system will:

Write all logs to the console with pretty formatting as usual
Write the same logs to the specified file in LOG_FILE_PATH in JSON format
Use synchronous file writes to ensure message order is maintained

Message Order Synchronization¶

The file logging is configured with sync: true to ensure that log messages are written in the exact order they are generated. This is especially important for session logging where the sequence of events matters.

Usage Example¶

To enable file logging, add the following to your .env file or environment variables:

LOG_TO_FILE=true
LOG_FILE_PATH=./logs/sessions.log

Log File Format¶

The log files are written in JSON format for easy parsing and analysis by external tools. Each log entry is a complete JSON object on a new line.

Log Rotation¶

The current implementation does not include built-in log rotation. For production environments, it is recommended to use external log rotation tools like logrotate to manage log file size and retention.

Session Log Persistence¶

In addition to Pino console/file logging, session flow events can be persisted to the database so they are available per-session via the API and the Web Client.

# Disable persistence (default)
LOG_SESSION_STORE=off

# Store only warn/error entries
LOG_SESSION_STORE=errors

# Store all session log entries
LOG_SESSION_STORE=all

# Store all entries with full request/response bodies and error stacks
LOG_SESSION_STORE=verbose

When enabled, log entries are written to the session_log_entry table and can be retrieved via GET /api/session/{id}/logs. The Web Client shows them in the Logs tab on the session detail page.

Warning

verbose mode captures full HTTP response bodies and error stack traces. This can generate large amounts of data and may include sensitive information. Use it only for debugging and disable it in production.

Note

LOG_SESSION_STORE requires LOG_ENABLE_SESSION_LOGGER=true to have any effect, since the session logger is the source of the persisted events.

Disabling Specific Logger Services¶

HTTP Request/Response Logging¶

To disable automatic HTTP request and response logging from Pino (useful during development when you want to reduce log noise):

# Disable HTTP request/response logging
LOG_ENABLE_HTTP_LOGGER=false

# Enable HTTP request/response logging
LOG_ENABLE_HTTP_LOGGER=true

Note: This controls the built-in HTTP logging from the Pino HTTP logger. Session-specific logging is controlled separately.

Audit Logging (AuditLogService)¶

To disable all audit logging (useful during debugging when you want to focus on other components):

# Disable AuditLogService logs
LOG_ENABLE_SESSION_LOGGER=false

# Enable AuditLogService logs
LOG_ENABLE_SESSION_LOGGER=true

Note: AuditLogService persists compliance events (flow_start, flow_complete, flow_error, credential_issuance, credential_verification) to the database only. For observability, logs are sent to Loki via the OpenTelemetry transport.

Development Scenarios¶

Debugging Authentication Issues¶

LOG_LEVEL=debug
LOG_ENABLE_SESSION_LOGGER=true
LOG_ENABLE_HTTP_LOGGER=false

This will show detailed debug logs but hide HTTP request noise.

Monitoring Session Flows¶

LOG_LEVEL=info
LOG_ENABLE_SESSION_LOGGER=true
LOG_ENABLE_HTTP_LOGGER=false

This will show all session flow events for monitoring credential issuance and verification, but without HTTP request logs.

Full Development Logging¶

LOG_LEVEL=debug
LOG_ENABLE_SESSION_LOGGER=true
LOG_ENABLE_HTTP_LOGGER=true

This will show everything including HTTP requests, responses, and session flows.

Production Monitoring¶

LOG_LEVEL=warn
LOG_ENABLE_SESSION_LOGGER=true
LOG_ENABLE_HTTP_LOGGER=false
LOG_TO_FILE=true
LOG_FILE_PATH=/var/log/eudiplo/session.log

This will only show warnings, errors, and important session events without HTTP noise, and write all logs to a file for later analysis.

Log Structure¶

Audit logs are persisted to the database with structured data. Debug/observability logs are exported to Loki via OpenTelemetry and include trace correlation:

{
    "level": "info",
    "time": "2025-07-20T10:30:45.123Z",
    "context": "AuditLogService",
    "sessionId": "session_123",
    "tenantId": "tenant_456",
    "flowType": "OID4VCI",
    "event": "flow_start",
    "stage": "initialization",
    "msg": "[OID4VCI] Flow started for session session_123 in tenant tenant_456"
}

Environment Configuration¶

Add these to your .env file:

# Basic logging
LOG_LEVEL=info
LOG_FORMAT=pretty

# Logging destinations
LOG_TO_FILE=false
LOG_FILE_PATH=./logs/session.log

# HTTP request/response logging control
LOG_ENABLE_HTTP_LOGGER=false

# Session logger control
LOG_ENABLE_SESSION_LOGGER=true

# Persist session logs to the database (off | errors | all)
LOG_SESSION_STORE=off

Runtime Control¶

You can control logging at runtime by restarting the service with different environment variables, or by implementing log level changes via API endpoints if needed.