1# Logging Configuration
2
3Configure Gordon process and HTTP access logging. Workload logs are read directly from the container runtime.
4
5## Configuration
6
7```toml
8[logging]
9level = "info"
10format = "console"
11
12[logging.file]
13enabled = true
14path = "~/.gordon/logs/gordon.log"
15max_size = 100
16max_backups = 3
17max_age = 28
18
19[logging.access_log]
20enabled = false
21format = "json"
22output = "stdout"
23exclude_health_checks = true
24syslog_identifier = "gordon-access"
25```
26
27## Options
28
29### General Logging
30
31| Option | Type | Default | Description |
32|--------|------|---------|-------------|
33| `level` | string | `"info"` | Log level: trace, debug, info, warn, error |
34| `format` | string | `"console"` | Output format: console or json |
35
36### File Logging
37
38| Option | Type | Default | Description |
39|--------|------|---------|-------------|
40| `file.enabled` | bool | `false` | Enable process file logging |
41| `file.path` | string | `{data_dir}/logs/gordon.log` | Process log path |
42| `file.max_size` | int | `100` | Max file size in MB before rotation |
43| `file.max_backups` | int | `3` | Number of old files to keep |
44| `file.max_age` | int | `28` | Days to keep old files |
45
46The Admin API and `gordon daemon logs` read from the process log file. Keep `logging.file.enabled` set to `true` if you need process log streaming.
47
48### Workload Logs
49
50`gordon apps logs APP --service SERVICE` reads stdout and stderr directly from the container runtime. Gordon does not persist workload logs to files; configure retention in the container runtime's logging driver.
51
52The accepted `logging.container_logs` configuration fields are currently not connected to a production log sink and do not create files.
53
54### Access Log
55
56| Option | Type | Default | Description |
57|--------|------|---------|-------------|
58| `access_log.enabled` | bool | `false` | Enable a dedicated HTTP access log |
59| `access_log.format` | string | `"json"` | Access log format: `json`, `clf`, `combined` |
60| `access_log.output` | string | `"stdout"` | Output sink: `stdout`, `file`, `journald` |
61| `access_log.file_path` | string | - | File path when `output = "file"` |
62| `access_log.max_size` | int | `100` | Max file size in MB for file output |
63| `access_log.max_backups` | int | `3` | Old files to keep for file output |
64| `access_log.max_age` | int | `28` | Days to keep file output |
65| `access_log.exclude_health_checks` | bool | `true` | Skip health and readiness checks |
66| `access_log.syslog_identifier` | string | `"gordon-access"` | Journald identifier |
67
68Use the access log for reverse-proxy traffic analysis, CrowdSec/fail2ban ingestion, or request auditing without mixing entries into the main process log.
69
70## Log Levels
71
72| Level | Description |
73|-------|-------------|
74| `trace` | Very detailed debugging |
75| `debug` | Debug information |
76| `info` | General information (default) |
77| `warn` | Warnings |
78| `error` | Errors only |
79
80## Log Rotation
81
82Process file logs and file-based access logs rotate by size and retain files by count and age. Old files are compressed.
83
84## Examples
85
86### Development
87
88```toml
89[logging]
90level = "debug"
91format = "console"
92
93[logging.file]
94enabled = true
95path = "./logs/gordon.log"
96max_size = 10
97max_backups = 2
98max_age = 7
99
100[logging.access_log]
101enabled = true
102format = "json"
103output = "file"
104file_path = "./logs/access.log"
105exclude_health_checks = true
106```
107
108### Production
109
110```toml
111[logging]
112level = "info"
113format = "json"
114
115[logging.file]
116enabled = true
117path = "~/.gordon/logs/gordon.log"
118max_size = 100
119max_backups = 10
120max_age = 90
121
122[logging.access_log]
123enabled = true
124format = "json"
125output = "journald"
126syslog_identifier = "gordon-access"
127```
128
129### Minimal (Console Only)
130
131```toml
132[logging]
133level = "info"
134format = "console"
135
136[logging.file]
137enabled = false
138```
139
140## Viewing Logs
141
142### Gordon Process Logs
143
144```bash
145gordon daemon logs -f
146gordon daemon logs -n 100
147tail -f ~/.gordon/logs/gordon.log
148journalctl --user -u gordon -f
149```
150
151### Workload Logs
152
153```bash
154gordon apps logs blog --service web
155gordon apps logs blog --service web --follow
156```
157
158These commands stream from the container runtime; they do not read Gordon-managed workload log files.
159
160## Security
161
162Process and access log files are created with owner-only permissions. Gordon redacts common credential patterns when serving logs, but application output may still contain sensitive data. Restrict process-log, journal, runtime, and `admin:logs:read` access.
163
164## Related
165
166- [Configuration Overview](./index.md)
167- [CLI Commands](../cli/index.md)
168- [Troubleshooting](../reference/troubleshooting.md)