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