You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/current/v25.4/configure-logs.md
+74-6Lines changed: 74 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -59,10 +59,12 @@ For clarity, this article uses the block format to describe the YAML payload, wh
59
59
file-defaults: ... # defaults inherited by file sinks
60
60
fluent-defaults: ... # defaults inherited by Fluentd sinks
61
61
http-defaults: ... # defaults inherited by HTTP sinks
62
+
otlp-defaults: ... # defaults inherited by OTLP sinks
62
63
sinks:
63
64
file-groups: ... # file sink definitions
64
65
fluent-servers: ... # Fluentd sink definitions
65
66
http-servers: ... # HTTP sink definitions
67
+
otlp-servers: ... # OTLP sink definitions
66
68
stderr: ... # stderr sink definitions
67
69
capture-stray-errors: ... # parameters for the stray error capture system
68
70
~~~
@@ -75,14 +77,21 @@ You can view the default settings by running `cockroach debug check-log-config`,
75
77
76
78
## Configure log sinks
77
79
78
-
Log *sinks* route events from specified [logging channels]({% link {{ page.version.version }}/logging-overview.md %}#logging-channels) to destinations outside CockroachDB. These destinations currently include [log files](#output-to-files), [Fluentd](https://www.fluentd.org/)-compatible [servers](#output-to-fluentd-compatible-network-collectors), [HTTP servers](#output-to-http-network-collectors), and the [standard error stream (`stderr`)](#output-to-stderr).
80
+
Log *sinks* route events from specified [logging channels]({% link {{ page.version.version }}/logging-overview.md %}#logging-channels) to destinations outside CockroachDB. These destinations include:
|`filter`| Minimum severity level at which logs enter the channels selected for the sink. Accepts one of the valid [severity levels]({% link {{ page.version.version }}/logging.md %}#logging-levels-severities) or `NONE`, which excludes all messages from the sink output. For details, see [Set logging levels](#set-logging-levels). |
111
-
|`format`| Log message format to use for file or network sinks. Accepts one of the valid [log formats]({% link {{ page.version.version }}/log-formats.md %}). For details, see [file logging format](#file-logging-format), [Fluentd logging format](#fluentd-logging-format), and [HTTP logging format](#http-logging-format). |
124
+
|`format`| Log message format to use for file or network sinks. Accepts one of the valid [log formats]({% link {{ page.version.version }}/log-formats.md %}). For details, see [file logging format](#file-logging-format), [Fluentd logging format](#fluentd-logging-format), [HTTP logging format](#http-logging-format), and [OTLP logging format](#otlp-logging-format). |
112
125
|`format-options`| Customization options for specified `format`. For available options for each format, see [Log formats]({% link {{ page.version.version }}/log-formats.md %}). For an example use case, see [Set timezone](#set-timezone). |
113
126
|`redact`| When `true`, enables automatic redaction of personally identifiable information (PII) from log messages. This ensures that sensitive data is not transmitted when collecting logs centrally or over a network. For details, see [Redact logs](#redact-logs). |
114
127
|`redactable`| When `true`, preserves redaction markers around fields that are considered sensitive in the log messages. The markers are recognized by [`cockroach debug zip`]({% link {{ page.version.version }}/cockroach-debug-zip.md %}) and [`cockroach debug merge-logs`]({% link {{ page.version.version }}/cockroach-debug-merge-logs.md %}) but may not be compatible with external log collectors. For details on how the markers appear in each format, see [Log formats]({% link {{ page.version.version }}/log-formats.md %}). |
115
128
|`exit-on-error`| When `true`, stops the Cockroach node if an error is encountered while writing to the sink. We recommend enabling this option on file sinks in order to avoid losing any log entries. When set to `false`, this can be used to mark certain sinks (such as `stderr`) as non-critical. |
116
129
|<a id="auditable"></a>`auditable`| If `true`, enables `exit-on-error` on the sink. Also disables `buffered-writes`if the sink is under `file-groups`. This guarantees [non-repudiability](https://wikipedia.org/wiki/Non-repudiation) forany logsin the sink, but can incur a performance overhead and higher disk IOPS consumption. This setting is typically enabled for [security-related logs]({% link {{ page.version.version }}/logging-use-cases.md %}#security-and-audit-monitoring).<br><br>File-based audit logging cannot coexist with the buffering configuration, so disable either [`buffering`](#file-buffering) or `auditable`. |
117
130
118
-
If not specified for a given sink, these parameter values are inherited from [`file-defaults`](#set-file-defaults) (for file sinks), [`fluent-defaults`](#set-fluentd-defaults) (for Fluentd sinks), and [`http-defaults`](#set-http-defaults) (for HTTP sinks).
131
+
If not specified for a given sink, these parameter values are inherited from [`file-defaults`](#set-file-defaults) (for file sinks), [`fluent-defaults`](#set-fluentd-defaults) (for Fluentd sinks), [`http-defaults`](#set-http-defaults) (for HTTP sinks), and [`otlp-defaults`](#set-otlp-defaults) (for OTLP sinks).
119
132
120
133
### Output to files
121
134
@@ -127,6 +140,7 @@ CockroachDB can write messages to one or more log files.
127
140
file-defaults: ...
128
141
fluent-defaults: ...
129
142
http-defaults: ...
143
+
otlp-defaults: ...
130
144
sinks:
131
145
file-groups:
132
146
default:
@@ -197,6 +211,7 @@ CockroachDB can send logs over the network to a [Fluentd](https://www.fluentd.or
197
211
file-defaults: ...
198
212
fluent-defaults: ...
199
213
http-defaults: ...
214
+
otlp-defaults: ...
200
215
sinks:
201
216
fluent-servers:
202
217
health:
@@ -228,6 +243,7 @@ For an example network logging configuration, see [Logging use cases]({% link {{
228
243
file-defaults: ...
229
244
fluent-defaults: ...
230
245
http-defaults: ...
246
+
otlp-defaults: ...
231
247
sinks:
232
248
http-servers:
233
249
health:
@@ -261,6 +277,38 @@ Along with the [common sink parameters](#common-sink-parameters), each HTTP serv
261
277
262
278
For an example network logging configuration, see [Logging use cases]({% link {{ page.version.version }}/logging-use-cases.md %}#network-logging). For an example that uses `compression`, `headers`, `file-based-headers`, and `buffering` parameters, see [Configure an HTTP network collector for Datadog]({% link {{ page.version.version }}/log-sql-activity-to-datadog.md %}#step-2-configure-an-http-network-collector-for-datadog).
263
279
280
+
### Output to OTLP-compatible network collectors
281
+
282
+
CockroachDB can send logs to an [OpenTelemetry](https://opentelemetry.io/)-compatible server using the OTLP protocol. Define `otlp-servers` to select channels and configure connection and protocol details. For example:
283
+
284
+
~~~ yaml
285
+
file-defaults: ...
286
+
fluent-defaults: ...
287
+
http-defaults: ...
288
+
otlp-defaults: ...
289
+
sinks:
290
+
otlp-servers:
291
+
health:
292
+
channels: [HEALTH]
293
+
address: 127.0.0.1:4317
294
+
mode: grpc
295
+
compression: gzip
296
+
...
297
+
~~~
298
+
299
+
Along with the [common sink parameters](#common-sink-parameters), each OTLP server accepts the following additional parameters:
300
+
301
+
| Parameter | Description |
302
+
|-----------|-------------|
303
+
| `channels` | List of channels that output to this sink. Use a YAML array or string of [channel names]({% link {{ page.version.version }}/logging-overview.md %}#logging-channels), `ALL`, or `ALL EXCEPT {channels}`. See [Logging channel selection](#logging-channel-selection) for syntax. |
304
+
| `address` | Network address of the OTLP collector endpoint for log ingestion, formatted as `{host}:{port}`. |
305
+
| `mode` | Protocol used to export logs. Valid values `grpc` or `http`.<br><br>**Default:**`grpc` |
306
+
| `headers` | Map of key-value string pairs which will be appended to every request as custom gRPC or HTTP headers depending on the `mode` selected. For example, `"x-api-key": "YOUR_API_KEY_HERE"`. |
307
+
| `compression` | Compression for requests. Valid values `gzip` or `none`.<br><br>**Default:**`gzip` |
308
+
| `buffering` | Configures buffering of log messages for the sink, with the following sub-parameters:<ul><li>`max-staleness`: The maximum time a log message will wait in the buffer before a flush is triggered. Set to `0` to disable flushing based on elapsed time. Default: `5s`</li><li>`flush-trigger-size`: The number of bytes that will trigger the buffer to flush. Set to `0` to disable flushing based on accumulated size. Default: `1MiB`</li><li>`max-buffer-size`: The maximum size of the buffer: new log messages received when the buffer is full cause older messages to be dropped. Default: `50MiB`</li></ul>When `max-staleness` and `flush-trigger-size` are used together, whichever is reached first will trigger the flush. `buffering` is enabled by default for OTLP log sinks. To explicitly disable log buffering, specify `buffering: NONE` instead. This setting is typically disabled for [security-related logs]({% link {{ page.version.version }}/logging-use-cases.md %}#security-and-audit-monitoring). See [Log buffering](#log-buffering-for-network-sinks) for more details and usage.|
309
+
310
+
For an example network logging configuration, see [Logging use cases]({% link {{ page.version.version }}/logging-use-cases.md %}#network-logging).
311
+
264
312
### Output to `stderr`
265
313
266
314
CockroachDB can output messages to the [standard error stream (`stderr`)](https://wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)), which prints them to the machine's terminal but does not store them. `stderr` specifies the channels that output to the stream. For example:
@@ -269,6 +317,7 @@ CockroachDB can output messages to the [standard error stream (`stderr`)](https:
When setting up a logging configuration, it's simplest to define shared parameters in `file-defaults`and `fluent-defaults` and override specific values as needed in [`file-groups`](#output-to-files), [`fluent-servers`](#output-to-fluentd-compatible-network-collectors), [`http-servers`](#output-to-http-network-collectors), and [`stderr`](#output-to-stderr). For a complete example, see the [default configuration](#default-logging-configuration).
406
+
When setting up a logging configuration, it's simplest to define shared parameters in `file-defaults`, `fluent-defaults`, `http-defaults`, and `otlp-defaults` and override specific values as needed in [`file-groups`](#output-to-files), [`fluent-servers`](#output-to-fluentd-compatible-network-collectors), [`http-servers`](#output-to-http-network-collectors), [`otlp-servers`](#output-to-otlp-compatible-network-collectors) and [`stderr`](#output-to-stderr). For a complete example, see the [default configuration](#default-logging-configuration).
358
407
359
408
{{site.data.alerts.callout_success}}
360
409
You can view your current settings by running `cockroach debug check-log-config`, which returns the YAML definitions and a URL to a visualization of the current logging configuration.
@@ -428,7 +477,7 @@ fluent-defaults:
428
477
429
478
Defaults forHTTP sinks are setin`http-defaults`, which accepts all [common sink parameters](#common-sink-parameters).
430
479
431
-
Note that the [server parameters](#output-to-http-network-collectors) `address` and `method` are *not* specified in `fluent-defaults`:
480
+
Note that the [server parameters](#output-to-http-network-collectors) `address` and `method` are *not* specified in `http-defaults`:
432
481
433
482
- `address` must be specified for each sink under `http-servers`.
434
483
- `method` is not required and defaults to `POST`.
@@ -446,6 +495,25 @@ http-defaults:
446
495
`format` refers to the envelope of the log message. This is separate from the event payload, which is structured according to [event type]({% link {{ page.version.version }}/eventlog.md %}).
447
496
{{site.data.alerts.end}}
448
497
498
+
### Set OTLP defaults
499
+
500
+
Defaults forOTLP sinks are setin`otlp-defaults`, which accepts all [common sink parameters](#common-sink-parameters).
501
+
502
+
Note that the [server parameter](#output-to-otlp-compatible-network-collectors) `address`is *not* specified in `otlp-defaults`. The `address` must be specified for each sink under `otlp-servers`.
503
+
504
+
#### OTLP logging format
505
+
506
+
The default message format for OTLP output is [`json`]({% link {{ page.version.version }}/log-formats.md %}#format-json). Each log message is structured as a JSON payload that can be read programmatically. For details, see [Log formats]({% link {{ page.version.version }}/log-formats.md %}).
507
+
508
+
~~~ yaml
509
+
otlp-defaults:
510
+
format: json
511
+
~~~
512
+
513
+
{{site.data.alerts.callout_info}}
514
+
`format` refers to the envelope of the log message. This is separate from the event payload, which is structured according to [event type]({% link {{ page.version.version }}/eventlog.md %}).
515
+
{{site.data.alerts.end}}
516
+
449
517
### Set logging levels
450
518
451
519
Log messages are associated with a [severity level]({% link {{ page.version.version }}/logging.md %}#logging-levels-severities) when they are generated.
@@ -612,7 +680,7 @@ To ensure that you are protecting sensitive information, also [redact your logs]
612
680
613
681
## Log buffering for network sinks
614
682
615
-
Both [Fluentd-compatible](#output-to-fluentd-compatible-network-collectors) and [HTTP](#output-to-http-network-collectors) log sinks support the buffering of log messages by default. Previous to version v22.2, log buffering was only available for the [log file](#output-to-files) log sink.
683
+
The network ([Fluentd-compatible](#output-to-fluentd-compatible-network-collectors), [HTTP](#output-to-http-network-collectors), and [OTLP-compatible](#output-to-otlp-compatible-network-collectors)) log sinks support the buffering of log messages by default. Previous to version v22.2, log buffering was only available for the [log file](#output-to-files) log sink.
616
684
617
685
With log buffering configured, log messages are held in a buffer for a configurable time period or accumulated message size threshold before being written to the target log sink together as a batch. Log buffering helps to ensure consistent low-latency log message writes over the network even in high-traffic, high-contention scenarios.
0 commit comments