Auditing & Logging
Relevant source files
The following files were used as context for generating this wiki page:
Auditing and logging in Kamal provide a structured mechanism for tracking deployment activities, operational commands, and system output across distributed servers. The system is designed to maintain a persistent audit trail on remote hosts and provide observability via local files and OpenTelemetry (OTel) integration.
The auditing system records high-level events (e.g., "Started app version X") to a dedicated log file on each server, while the logging system captures detailed command execution output, supporting various formats and backends including local disk and OTel collectors.
Sources: lib/kamal/commands/auditor.rb:11-14, lib/kamal/commander.rb:149-166, lib/kamal/cli/main.rb:174-179
Remote Auditing System
Kamal maintains a server-side audit log to track administrative actions performed on each host. This log is stored within the Kamal run directory on the remote server and can be retrieved via CLI commands.
Auditor Architecture
The Kamal::Commands::Auditor class generates the shell commands required to record events. It uses standard Linux utilities like echo and mkdir to manage log entries and directories. Audit lines are tagged with metadata but exclude specific versioning information for brevity in the log output.
This diagram illustrates the flow of recording an audit entry from the CLI to a remote server.
Sources: lib/kamal/commands/auditor.rb:5-37
Key Audit Functions
| Function | File Path | Purpose |
|---|---|---|
record(line) | lib/kamal/commands/auditor.rb | Combines directory creation and appends a tagged line to the audit log. |
reveal | lib/kamal/commands/auditor.rb | Returns the command to tail the last 50 lines of the audit log. |
audit | lib/kamal/cli/main.rb | CLI entry point that captures and prints the audit log from all hosts. |
Sources: lib/kamal/commands/auditor.rb:11-20, lib/kamal/cli/main.rb:174-179
Output Logging Backends
Kamal supports multiple logging backends to capture the verbose output of deployment processes. These are managed by Kamal::Commander via an ActiveSupport::BroadcastLogger.
File Logging
The FileLogger backend creates timestamped log files for specific commands and subcommands. Each deployment session generates a unique log file (e.g., _deploy.log or _app_boot.log), providing a historical record of all terminal output generated during that specific run.
Sources: test/output/file_logger_test.rb:17-57
OpenTelemetry (OTel) Logging
The OtelLogger integrates with OpenTelemetry to ship logs and events to a central collector. It handles command lifecycle events (start, complete, failed) and streams raw output lines with metadata.
Sequence diagram showing the interaction between Kamal's internal OTel logger and an external collector.
Sources: lib/kamal/output/otel_logger.rb:1-55, test/integration/main_test.rb:108-144
Configuration and Implementation
Logging and auditing behavior is determined by the deploy.yml configuration and the runtime state of the Kamal::Commander.
Logging Configuration Attributes
| Attribute | Source File | Description |
|---|---|---|
logging | lib/kamal/configuration.rb | Configures Docker logging options (e.g., max-size, max-file). |
output | lib/kamal/configuration.rb | Determines which loggers are active (File, OTel, etc.). |
hooks_output | lib/kamal/configuration.rb | Controls the verbosity of hook execution output (quiet vs verbose). |
Sources: lib/kamal/configuration.rb:71-75, lib/kamal/configuration.rb:251-259, lib/kamal/configuration.rb:300-307
Contextual Metadata
When logging, Kamal attaches thread-local context to log records to identify the specific host and stream (stdout/stderr) being processed. This is particularly critical when commands are executed in parallel across multiple servers.
# lib/kamal/output/otel_logger.rb:62-72
def <<(line)
kamal_shipper.append \
line,
host: Thread.current[:kamal_host],
iostream: Thread.current[:kamal_iostream],
severity: Thread.current[:kamal_severity]
end
Sources: lib/kamal/output/otel_logger.rb:62-72
Summary
Auditing and logging in Kamal serve as both a local debugging tool and a distributed observability system. By combining local file logging, OTel exports, and remote server-side audit trails, Kamal ensures that every deployment action is documented and attributable. This multi-layered approach allows developers to investigate failures using local logs while maintaining a persistent record of infrastructure changes on the servers themselves.
Sources: lib/kamal/commander.rb:149-166, lib/kamal/cli/auditor.rb:1-12