Skip to content

Commit 0653b31

Browse files
presztakpresztak
committed
doc: Documentation for new logging mechanism
Signed-off-by: Piotr Resztak <[email protected]>
1 parent a4099c7 commit 0653b31

File tree

5 files changed

+240
-9
lines changed

5 files changed

+240
-9
lines changed

‎doc/config_options.txt

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2470,6 +2470,103 @@ Specify the number of days after which the unused cached image expires.
24702470
```
24712471

24722472
<!-- config group server-images end -->
2473+
<!-- config group server-logging start -->
2474+
```{config:option} logging.NAME.lifecycle.projects server-logging
2475+
:scope: "global"
2476+
:shortdesc: "Comma separate list of projects, empty means all"
2477+
:type: "string"
2478+
2479+
```
2480+
2481+
```{config:option} logging.NAME.lifecycle.types server-logging
2482+
:scope: "global"
2483+
:shortdesc: "E.g., `instance`, comma separate, empty means all"
2484+
:type: "string"
2485+
2486+
```
2487+
2488+
```{config:option} logging.NAME.logging.level server-logging
2489+
:defaultdesc: "`info`"
2490+
:scope: "global"
2491+
:shortdesc: "Minimum log level to send to the logger"
2492+
:type: "string"
2493+
2494+
```
2495+
2496+
```{config:option} logging.NAME.target.address server-logging
2497+
:scope: "global"
2498+
:shortdesc: "Address of the logger"
2499+
:type: "string"
2500+
Specify the protocol, name or IP and port. For example `tcp://syslog01.int.example.net:514`.
2501+
```
2502+
2503+
```{config:option} logging.NAME.target.ca_cert server-logging
2504+
:scope: "global"
2505+
:shortdesc: "CA certificate for the server"
2506+
:type: "string"
2507+
2508+
```
2509+
2510+
```{config:option} logging.NAME.target.facility server-logging
2511+
:scope: "global"
2512+
:shortdesc: "The syslog facility defines the category of the log message"
2513+
:type: "string"
2514+
2515+
```
2516+
2517+
```{config:option} logging.NAME.target.instance server-logging
2518+
:defaultdesc: "Local server host name or cluster member name"
2519+
:scope: "global"
2520+
:shortdesc: "Name to use as the instance field in Loki events."
2521+
:type: "string"
2522+
This allows replacing the default instance value (server host name) by a more relevant value like a cluster identifier.
2523+
```
2524+
2525+
```{config:option} logging.NAME.target.labels server-logging
2526+
:scope: "global"
2527+
:shortdesc: "Labels for a Loki log entry"
2528+
:type: "string"
2529+
Specify a comma-separated list of values that should be used as labels for a Loki log entry.
2530+
```
2531+
2532+
```{config:option} logging.NAME.target.password server-logging
2533+
:scope: "global"
2534+
:shortdesc: "Password used for authentication"
2535+
:type: "string"
2536+
2537+
```
2538+
2539+
```{config:option} logging.NAME.target.retry server-logging
2540+
:scope: "global"
2541+
:shortdesc: "number of delivery retries, default 3"
2542+
:type: "integer"
2543+
2544+
```
2545+
2546+
```{config:option} logging.NAME.target.type server-logging
2547+
:scope: "global"
2548+
:shortdesc: "The type of the logger, e.g., syslog"
2549+
:type: "string"
2550+
2551+
```
2552+
2553+
```{config:option} logging.NAME.target.username server-logging
2554+
:scope: "global"
2555+
:shortdesc: "User name used for authentication"
2556+
:type: "string"
2557+
2558+
```
2559+
2560+
```{config:option} logging.NAME.types server-logging
2561+
:defaultdesc: "`lifecycle,logging`"
2562+
:scope: "global"
2563+
:shortdesc: "Events to send to the logger"
2564+
:type: "string"
2565+
Specify a comma-separated list of events to send to the logger.
2566+
The events can be any combination of `lifecycle`, `logging`, and `network-acl`.
2567+
```
2568+
2569+
<!-- config group server-logging end -->
24732570
<!-- config group server-loki start -->
24742571
```{config:option} loki.api.ca_cert server-loki
24752572
:scope: "global"

‎doc/howto/network_ovn_setup.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -198,9 +198,9 @@ You can now use [`incus monitor`](incus_monitor.md) to see logged network ACL tr
198198
incus monitor --type=network-acls
199199
200200
You can also send the logs to Loki.
201-
To do so, add the `network-acl` value to the {config:option}`server-loki:loki.types` configuration key, for example:
201+
To do so, add the `network-acl` value to the {config:option}`server-logging:logging.NAME.types` configuration key, for example:
202202
203-
incus config set loki.types=network-acl
203+
incus config set logging.NAME.types=network-acl
204204
205205
```{tip}
206206
You can include logs for OVN `northd`, OVN north-bound `ovsdb-server`, and OVN south-bound `ovsdb-server` as well.

‎doc/metrics.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -312,5 +312,5 @@ At the bottom of the page, you can see data for each instance.
312312

313313
```{note}
314314
For proper operation of the Loki part of the dashboard, you need to ensure that the `instance` field matches the Prometheus job name.
315-
You can change the `instance` field through the `loki.instance` configuration key.
315+
You can change the `instance` field through the `logging.*.target.instance` configuration key.
316316
```

‎doc/server_config.md

Lines changed: 29 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ The following options are available:
1010
- {ref}`server-options-acme`
1111
- {ref}`server-options-cluster`
1212
- {ref}`server-options-images`
13-
- {ref}`server-options-loki`
13+
- {ref}`server-options-logging`
1414
- {ref}`server-options-misc`
1515
- {ref}`server-options-oidc`
1616
- {ref}`server-options-openfga`
@@ -88,15 +88,38 @@ The following server options configure how to handle {ref}`images`:
8888
:end-before: <!-- config group server-images end -->
8989
```
9090

91-
(server-options-loki)=
92-
## Loki configuration
91+
(server-options-logging)=
92+
## Logging configuration
9393

94-
The following server options configure the external log aggregation system:
94+
The logging system now supports multiple configurable targets, each identified by a unique name (e.g., `loki01`, `syslog01`).
95+
Each target can be independently configured and assigned specific log types.
96+
97+
### Supported Targets
98+
99+
- `loki` - For sending logs to a Grafana Loki server
100+
- `syslog` - For sending logs to remote syslog endpoint
101+
102+
### Example configuration
103+
104+
```
105+
logging.loki01.target.type: loki
106+
logging.loki01.target.address: https://loki01.int.example.net
107+
logging.loki01.target.username: foo
108+
logging.loki01.target.password: bar
109+
logging.loki01.types: lifecycle,network-acl
110+
logging.loki01.lifecycle.types: instance
111+
112+
logging.syslog01.target.type: syslog
113+
logging.syslog01.target.address: syslog01.int.example.net
114+
logging.syslog01.target.facility: security
115+
logging.syslog01.types: logging
116+
logging.syslog01.logging.level: warning
117+
```
95118

96119
% Include content from [config_options.txt](config_options.txt)
97120
```{include} config_options.txt
98-
:start-after: <!-- config group server-loki start -->
99-
:end-before: <!-- config group server-loki end -->
121+
:start-after: <!-- config group server-logging start -->
122+
:end-before: <!-- config group server-logging end -->
100123
```
101124

102125
(server-options-misc)=

‎internal/server/metadata/configuration.json

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2738,6 +2738,117 @@
27382738
}
27392739
]
27402740
},
2741+
"logging": {
2742+
"keys": [
2743+
{
2744+
"logging.NAME.lifecycle.projects": {
2745+
"longdesc": "",
2746+
"scope": "global",
2747+
"shortdesc": "Comma separate list of projects, empty means all",
2748+
"type": "string"
2749+
}
2750+
},
2751+
{
2752+
"logging.NAME.lifecycle.types": {
2753+
"longdesc": "",
2754+
"scope": "global",
2755+
"shortdesc": "E.g., `instance`, comma separate, empty means all",
2756+
"type": "string"
2757+
}
2758+
},
2759+
{
2760+
"logging.NAME.logging.level": {
2761+
"defaultdesc": "`info`",
2762+
"longdesc": "",
2763+
"scope": "global",
2764+
"shortdesc": "Minimum log level to send to the logger",
2765+
"type": "string"
2766+
}
2767+
},
2768+
{
2769+
"logging.NAME.target.address": {
2770+
"longdesc": "Specify the protocol, name or IP and port. For example `tcp://syslog01.int.example.net:514`.",
2771+
"scope": "global",
2772+
"shortdesc": "Address of the logger",
2773+
"type": "string"
2774+
}
2775+
},
2776+
{
2777+
"logging.NAME.target.ca_cert": {
2778+
"longdesc": "",
2779+
"scope": "global",
2780+
"shortdesc": "CA certificate for the server",
2781+
"type": "string"
2782+
}
2783+
},
2784+
{
2785+
"logging.NAME.target.facility": {
2786+
"longdesc": "",
2787+
"scope": "global",
2788+
"shortdesc": "The syslog facility defines the category of the log message",
2789+
"type": "string"
2790+
}
2791+
},
2792+
{
2793+
"logging.NAME.target.instance": {
2794+
"defaultdesc": "Local server host name or cluster member name",
2795+
"longdesc": "This allows replacing the default instance value (server host name) by a more relevant value like a cluster identifier.",
2796+
"scope": "global",
2797+
"shortdesc": "Name to use as the instance field in Loki events.",
2798+
"type": "string"
2799+
}
2800+
},
2801+
{
2802+
"logging.NAME.target.labels": {
2803+
"longdesc": "Specify a comma-separated list of values that should be used as labels for a Loki log entry.",
2804+
"scope": "global",
2805+
"shortdesc": "Labels for a Loki log entry",
2806+
"type": "string"
2807+
}
2808+
},
2809+
{
2810+
"logging.NAME.target.password": {
2811+
"longdesc": "",
2812+
"scope": "global",
2813+
"shortdesc": "Password used for authentication",
2814+
"type": "string"
2815+
}
2816+
},
2817+
{
2818+
"logging.NAME.target.retry": {
2819+
"longdesc": "",
2820+
"scope": "global",
2821+
"shortdesc": "number of delivery retries, default 3",
2822+
"type": "integer"
2823+
}
2824+
},
2825+
{
2826+
"logging.NAME.target.type": {
2827+
"longdesc": "",
2828+
"scope": "global",
2829+
"shortdesc": "The type of the logger, e.g., syslog",
2830+
"type": "string"
2831+
}
2832+
},
2833+
{
2834+
"logging.NAME.target.username": {
2835+
"longdesc": "",
2836+
"scope": "global",
2837+
"shortdesc": "User name used for authentication",
2838+
"type": "string"
2839+
}
2840+
},
2841+
{
2842+
"logging.NAME.types": {
2843+
"defaultdesc": "`lifecycle,logging`",
2844+
"longdesc": "Specify a comma-separated list of events to send to the logger.\nThe events can be any combination of `lifecycle`, `logging`, and `network-acl`.",
2845+
"scope": "global",
2846+
"shortdesc": "Events to send to the logger",
2847+
"type": "string"
2848+
}
2849+
}
2850+
]
2851+
},
27412852
"loki": {
27422853
"keys": [
27432854
{

0 commit comments

Comments
 (0)