From e60f67f102d812e002eeb23ea64104d1826f92af Mon Sep 17 00:00:00 2001 From: Andrzej Stencel Date: Sat, 11 Nov 2023 14:02:51 -0600 Subject: [PATCH] [chore][exporter/debug] add description of verbosity levels (#8841) This improves the documentation of the `debug` exporter by adding descriptions of the available verbosity levels of the component. Hopefully this update also brings to light the fact that the verbosity levels need some work. For starters, it makes sense for the `normal` verbosity to have different output from the `basic` verbosity. --- exporter/debugexporter/README.md | 72 +++++++++++++++++++++++++++++++- 1 file changed, 70 insertions(+), 2 deletions(-) diff --git a/exporter/debugexporter/README.md b/exporter/debugexporter/README.md index dd246772af7..d2172c453fc 100644 --- a/exporter/debugexporter/README.md +++ b/exporter/debugexporter/README.md @@ -8,7 +8,11 @@ Exports data to the console via zap.Logger. -Supported pipeline types: traces, metrics, logs +Supported pipeline types: traces, metrics, logs. + +See also the [Troubleshooting][troubleshooting_docs] document for examples on using this exporter. + +[troubleshooting_docs]: ../../docs/troubleshooting.md ## Getting Started @@ -24,7 +28,7 @@ The following settings are optional: docs](https://godoc.org/go.uber.org/zap/zapcore#NewSampler) for more details. on how sampling parameters impact number of messages. -Example: +Example configuration: ```yaml exporters: @@ -34,6 +38,70 @@ exporters: sampling_thereafter: 200 ``` +## Verbosity levels + +The following subsections describe the output from the exporter depending on the configured verbosity level - `basic`, `normal` and `detailed`. +The default verbosity level is `normal`. + +### Basic verbosity + +With `verbosity: basic`, the exporter's behavior is currently the same as with `verbosity: normal`. +See below for more details. + +### Normal verbosity + +With `verbosity: normal`, the exporter outputs a single-line summary of received data with a total count of telemetry records for every batch of received logs, metrics or traces. + +Here's an example output: + +```console +2023-11-10T22:49:03.510-0600 info TracesExporter {"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 2} +``` + +### Detailed verbosity + +With `verbosity: detailed`, the exporter outputs all details of every telemetry record, typically writing multiple lines for every telemetry record. + +Here's an example output: + +```console +2023-11-10T22:49:03.510-0600 info TracesExporter {"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 2} +2023-11-10T22:49:03.510-0600 info ResourceSpans #0 +Resource SchemaURL: https://opentelemetry.io/schemas/1.4.0 +Resource attributes: + -> service.name: Str(telemetrygen) +ScopeSpans #0 +ScopeSpans SchemaURL: +InstrumentationScope telemetrygen +Span #0 + Trace ID : 3bde5d3ee82303571bba6e1136781fe4 + Parent ID : 5e9dcf9bac4acc1f + ID : 2cf3ef2899aba35c + Name : okey-dokey + Kind : Server + Start time : 2023-11-11 04:49:03.509369393 +0000 UTC + End time : 2023-11-11 04:49:03.50949377 +0000 UTC + Status code : Unset + Status message : +Attributes: + -> net.peer.ip: Str(1.2.3.4) + -> peer.service: Str(telemetrygen-client) +Span #1 + Trace ID : 3bde5d3ee82303571bba6e1136781fe4 + Parent ID : + ID : 5e9dcf9bac4acc1f + Name : lets-go + Kind : Client + Start time : 2023-11-11 04:49:03.50935117 +0000 UTC + End time : 2023-11-11 04:49:03.50949377 +0000 UTC + Status code : Unset + Status message : +Attributes: + -> net.peer.ip: Str(1.2.3.4) + -> peer.service: Str(telemetrygen-server) + {"kind": "exporter", "data_type": "traces", "name": "debug"} +``` + [contrib]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib [core]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol [Development]: https://github.com/open-telemetry/opentelemetry-collector#in-development