1# Logging Configuration
2
3Configure application and container log collection.
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.container_logs]
20enabled = true
21dir = "~/.gordon/logs/containers"
22max_size = 100
23max_backups = 3
24max_age = 28
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 file-based logging |
41| `file.path` | string | - | Path to main log file |
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 logs` read from the process log file. Keep
47`logging.file.enabled` set to `true` if you need process log streaming.
48
49### Container Logs
50
51| Option | Type | Default | Description |
52|--------|------|---------|-------------|
53| `container_logs.enabled` | bool | `true` | Collect container stdout/stderr |
54| `container_logs.dir` | string | `{data_dir}/logs/containers` | Directory for container logs |
55| `container_logs.max_size` | int | `100` | Max file size in MB |
56| `container_logs.max_backups` | int | `3` | Old files to keep |
57| `container_logs.max_age` | int | `28` | Days to keep files |
58
59## Log Levels
60
61| Level | Description |
62|-------|-------------|
63| `trace` | Very detailed debugging |
64| `debug` | Debug information |
65| `info` | General information (default) |
66| `warn` | Warnings |
67| `error` | Errors only |
68
69## Log Directory Structure
70
71```
72~/.gordon/logs/
73├── gordon.log              # Main application logs
74├── gordon.log.1            # Rotated log
75├── gordon.log.2.gz         # Compressed old log
76└── containers/
77    ├── app_mydomain_com.log  # Container logs by domain
78    └── api_mydomain_com.log
79```
80
81## Log Rotation
82
83Gordon uses automatic log rotation:
84
851. **Size-based**: Rotates when file exceeds `max_size` MB
862. **Age-based**: Removes files older than `max_age` days
873. **Count-based**: Keeps only `max_backups` old files
884. **Compression**: Old files are gzip compressed
89
90Example with defaults:
91- Log grows to 100MB → rotated to `gordon.log.1`
92- After 3 rotations → oldest is compressed
93- Files older than 28 days → deleted
94
95## Examples
96
97### Development
98
99```toml
100[logging]
101level = "debug"
102format = "console"
103
104[logging.file]
105enabled = true
106path = "./logs/gordon.log"
107max_size = 10
108max_backups = 2
109max_age = 7
110
111[logging.container_logs]
112enabled = true
113dir = "./logs/containers"
114max_size = 10
115max_backups = 2
116max_age = 7
117```
118
119### Production
120
121```toml
122[logging]
123level = "info"
124format = "json"
125
126[logging.file]
127enabled = true
128path = "~/.gordon/logs/gordon.log"
129max_size = 100
130max_backups = 10
131max_age = 90
132
133[logging.container_logs]
134enabled = true
135dir = "~/.gordon/logs/containers"
136max_size = 100
137max_backups = 10
138max_age = 90
139```
140
141### Minimal (Console Only)
142
143```toml
144[logging]
145level = "info"
146format = "console"
147
148[logging.file]
149enabled = false
150
151[logging.container_logs]
152enabled = true
153```
154
155## Viewing Logs
156
157### Gordon Logs
158
159```bash
160# Using gordon logs command
161gordon logs -f          # Follow logs
162gordon logs -n 100      # Last 100 lines
163
164# Direct file access
165tail -f ~/.gordon/logs/gordon.log
166
167# With journalctl (if using systemd)
168journalctl --user -u gordon -f
169```
170
171### Container Logs
172
173```bash
174# View container logs
175tail -f ~/.gordon/logs/containers/app_mydomain_com.log
176
177# All container logs
178ls ~/.gordon/logs/containers/
179```
180
181## Log Format
182
183### Console Format
184
185```
1862024-01-15T10:30:00Z INF container deployed domain=app.mydomain.com image=myapp:latest
1872024-01-15T10:30:01Z INF proxy routing updated route=app.mydomain.com
188```
189
190### JSON Format
191
192```json
193{"level":"info","time":"2024-01-15T10:30:00Z","message":"container deployed","domain":"app.mydomain.com","image":"myapp:latest"}
194{"level":"info","time":"2024-01-15T10:30:01Z","message":"proxy routing updated","route":"app.mydomain.com"}
195```
196
197## Security
198
199Log files are created with secure permissions:
200- Directories: `0700` (owner only)
201- Files: `0600` (owner only)
202
203Sensitive values (passwords, tokens) are automatically redacted.
204
205## Related
206
207- [Configuration Overview](./index.md)
208- [CLI Commands](../cli/index.md)
209- [Troubleshooting](../reference/troubleshooting.md)