Logging Configuration
The logging section in harperdb-config.yaml controls standard log output. Many logging settings are applied dynamically without a restart (added in v4.6.0).
Main Logger
logging.level
Type: string
Default: warn
Controls the verbosity of logs. Levels from least to most severe: trace, debug, info, warn, error, fatal, notify. Setting a level includes that level and all more-severe levels.
logging:
level: warn
For example, level: warn results in warn, error, fatal, and notify logs.
logging.path
Type: string
Default: <ROOTPATH>/log/hdb.log
Full file path for the log file.
logging:
path: ~/hdb/log/hdb.log
logging.root
Type: string
Default: <ROOTPATH>/log
Directory path where log files are written. Use path to specify the full filename; use root to specify only the directory (Harper determines the filename).
logging:
root: ~/hdb/log
logging.file
Type: boolean
Default: true
Whether to write logs to a file. Disable if you want to use only standard streams.
logging:
file: true
logging.stdStreams
Type: boolean
Default: false
Log to stdout/stderr in addition to (or instead of) the log file.
When enabled, run Harper in the foreground (harper, not harper start).
logging:
stdStreams: true
logging.console
Type: boolean
Default: false
Controls whether console.log and other console.* calls (and anything writing to process.stdout/process.stderr from JS components) are captured to the log file.
logging:
console: true
logging.auditLog
Type: boolean
Default: false
Enables audit (table transaction) logging. When enabled, Harper records every insert, update, and delete to a corresponding audit table. Audit log data is accessed via the read_audit_log operation.
See Database / Transaction Logging for details on using audit logs.
logging:
auditLog: false
logging.auditRetention
Type: string | number
Default: 3d
How long audit log entries are retained before automatic eviction. Accepts duration strings (e.g., 3d, 12h) or milliseconds.
logging:
auditRetention: 3d
Log Rotation
Rotation provides systematic management of the hdb.log file — compressing, archiving, and replacing it on a schedule or size threshold. Rotation is triggered when either interval or maxSize is set.
intervalandmaxSizeare approximates only. The log file may exceed these values slightly before rotation occurs.
logging.rotation.enabled
Type: boolean
Default: true
Enables log rotation. Rotation only activates when interval or maxSize is also set.
logging.rotation.compress
Type: boolean
Default: false
Compress rotated log files with gzip.
logging.rotation.interval
Type: string
Default: null
Time between rotations. Accepted units: D (days), H (hours), M (minutes). Example: 1D, 12H.
logging.rotation.maxSize
Type: string
Default: null
Maximum log file size before rotation. Accepted units: K (kilobytes), M (megabytes), G (gigabytes). Example: 100M, 1G.
logging.rotation.path
Type: string
Default: <ROOTPATH>/log
Directory for storing rotated log files. Rotated files are named: HDB-YYYY-MM-DDT-HH-MM-SSSZ.log.
logging:
rotation:
enabled: true
compress: false
interval: 1D
maxSize: 100M
path: ~/hdb/log
Authentication Logging
logging.auditAuthEvents.logFailed
Added in: v4.2.0
Type: boolean
Default: false
Log all failed authentication attempts.
Example log entry:
[error] [auth-event]: {"username":"admin","status":"failure","type":"authentication","originating_ip":"127.0.0.1","request_method":"POST","path":"/","auth_strategy":"Basic"}
logging.auditAuthEvents.logSuccessful
Added in: v4.2.0
Type: boolean
Default: false
Log all successful authentication events.
Example log entry:
[notify] [auth-event]: {"username":"admin","status":"success","type":"authentication","originating_ip":"127.0.0.1","request_method":"POST","path":"/","auth_strategy":"Basic"}
logging:
auditAuthEvents:
logFailed: false
logSuccessful: false
Per-Component Logging
Added in: v4.6.0
Harper supports independent logging configurations for different components. Each component logger can have its own path, root, level, tag, and stdStreams settings. All components default to the main logging configuration unless overridden.
logging.external
Logging configuration for all external components that use the logger API.
logging:
external:
level: warn
path: ~/hdb/log/apps.log
http.logging
HTTP request logging. Disabled by default — defining this section enables it.
http:
logging:
level: info # info = all requests, warn = 4xx+, error = 5xx
path: ~/hdb/log/http.log
timing: true # log request duration
headers: false # log request headers (verbose)
id: true # assign and log a unique request ID per request
See HTTP Configuration for full details.
mqtt.logging
MQTT logging configuration. Accepts standard logging options.
mqtt:
logging:
level: warn
path: ~/hdb/log/mqtt.log
stdStreams: false
authentication.logging
Authentication subsystem logging. Accepts standard logging options.
authentication:
logging:
level: warn
path: ~/hdb/log/auth.log
replication.logging
Replication subsystem logging. Accepts standard logging options.
replication:
logging:
level: warn
path: ~/hdb/log/replication.log
tls.logging
TLS subsystem logging. Accepts standard logging options.
tls:
logging:
level: warn
path: ~/hdb/log/tls.log
storage.logging
Database storage subsystem logging. Accepts standard logging options.
storage:
logging:
level: warn
path: ~/hdb/log/storage.log
analytics.logging
Analytics subsystem logging. Accepts standard logging options.
analytics:
logging:
level: warn
path: ~/hdb/log/analytics.log
Clustering Log Level
Clustering has a separate log level due to its verbosity. Configure with clustering.logLevel.
Valid levels from least verbose: error, warn, info, debug, trace.
clustering:
logLevel: warn
Complete Example
logging:
level: warn
path: ~/hdb/log/hdb.log
file: true
stdStreams: false
console: false
auditLog: false
auditRetention: 3d
rotation:
enabled: true
compress: false
interval: 1D
maxSize: 100M
path: ~/hdb/log
auditAuthEvents:
logFailed: false
logSuccessful: false
external:
level: warn
path: ~/hdb/log/apps.log
http:
logging:
level: warn
path: ~/hdb/log/http.log
timing: true