debugexporter

README

Debug Exporter

Status
Stability	alpha: traces, metrics, logs, profiles
Distributions	core, contrib, k8s
Warnings	Unstable Output Format
Issues
Code Owners	@andrzej-stencel

Outputs telemetry data to the console for debugging purposes.

See also the Troubleshooting document for examples on using this exporter.

Getting Started

The following settings are optional:

• verbosity (default = basic): the verbosity of the debug exporter: basic, normal or detailed. See Verbosity levels below for more information.
• sampling_initial (default = 2): number of messages initially logged each second.
• sampling_thereafter (default = 1): sampling rate after the initial messages are logged (every Mth message is logged). The default value of 1 means that sampling is disabled. To enable sampling, change sampling_thereafter to a value higher than 1. Refer to Zap docs for more details on how sampling parameters impact number of messages.
• use_internal_logger (default = true): uses the collector's internal logger for output. See below for description.
• output_paths (default = ["stdout"]): a list of file paths to write output to. This option can only be used when use_internal_logger is false. Special strings "stdout" and "stderr" are interpreted as standard output and standard error respectively. All other values are treated as file paths. Setting output_paths when use_internal_logger is true results in a configuration error.
• sending_queue (disabled by default): see Sending Queue for the full set of available options.

Example configuration:

exporters:
  debug:
    verbosity: detailed
    sampling_initial: 5
    sampling_thereafter: 200

Example configuration with custom output path:

exporters:
  debug:
    use_internal_logger: false
    output_paths:
      - stderr

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 basic.

To understand how the below example output was generated, see Generating example output.

Basic verbosity

With verbosity: basic, 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:

2025-04-17T10:40:44.559+0200    info    Traces  {"otelcol.component.id": "debug/basic", "otelcol.component.kind": "Exporter", "otelcol.signal": "traces", "resource spans": 1, "spans": 2}

Normal verbosity

With verbosity: normal, the exporter outputs about one line for each telemetry record. The "one line per telemetry record" is not a strict rule. For example, logs with multiline body will be output as multiple lines.

Here's an example output:

2025-05-09T19:57:16.332+0200    info    Traces  {"resource": {}, "otelcol.component.id": "debug/normal", "otelcol.component.kind": "exporter", "otelcol.signal": "traces", "resource spans": 1, "spans": 2}
2025-05-09T19:57:16.332+0200    info    ResourceTraces #0 [https://opentelemetry.io/schemas/1.25.0] service.name=telemetrygen
ScopeTraces #0 telemetrygen
okey-dokey-0 ab1030bd4ee554af936542b01d7b4807 1d8c93663d043aa8 net.sock.peer.addr=1.2.3.4 peer.service=telemetrygen-client
lets-go ab1030bd4ee554af936542b01d7b4807 0d238e8a2f97733f net.sock.peer.addr=1.2.3.4 peer.service=telemetrygen-server
        {"resource": {}, "otelcol.component.id": "debug/normal", "otelcol.component.kind": "exporter", "otelcol.signal": "traces"}

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:

2025-04-17T10:40:44.560+0200    info    Traces  {"otelcol.component.id": "debug/detailed", "otelcol.component.kind": "Exporter", "otelcol.signal": "traces", "resource spans": 1, "spans": 2}
2025-04-17T10:40:44.560+0200    info    ResourceSpans #0
Resource SchemaURL: https://opentelemetry.io/schemas/1.25.0
Resource attributes:
     -> service.name: Str(telemetrygen)
ScopeSpans #0
ScopeSpans SchemaURL: 
InstrumentationScope telemetrygen 
Span #0
    Trace ID       : fafdac970271dd2ce89de2442c0518c7
    Parent ID      : d98de4cb8e2a0ad6
    ID             : 3875f436d989d0e5
    Name           : okey-dokey-0
    Kind           : Server
    Start time     : 2025-04-17 08:40:44.555461596 +0000 UTC
    End time       : 2025-04-17 08:40:44.555584596 +0000 UTC
    Status code    : Unset
    Status message : 
Attributes:
     -> net.sock.peer.addr: Str(1.2.3.4)
     -> peer.service: Str(telemetrygen-client)
Span #1
    Trace ID       : fafdac970271dd2ce89de2442c0518c7
    Parent ID      : 
    ID             : d98de4cb8e2a0ad6
    Name           : lets-go
    Kind           : Client
    Start time     : 2025-04-17 08:40:44.555461596 +0000 UTC
    End time       : 2025-04-17 08:40:44.555584596 +0000 UTC
    Status code    : Unset
    Status message : 
Attributes:
     -> net.sock.peer.addr: Str(1.2.3.4)
     -> peer.service: Str(telemetrygen-server)
        {"otelcol.component.id": "debug/detailed", "otelcol.component.kind": "Exporter", "otelcol.signal": "traces"}

Using the collector's internal logger

When use_internal_logger is set to true (the default), the exporter uses the collector's internal logger for output. This comes with the following consequences:

• The output from the exporter may be annotated by additional output from the collector's logger.
• The output from the exporter is affected by the collector's logging configuration specified in service::telemetry::logs.

When use_internal_logger is set to false, the exporter does not use the collector's internal logger. Changing the values in service::telemetry::logs has no effect on the exporter's output. The exporter's output is sent to the paths specified in output_paths (default: ["stdout"]). You can configure output_paths to send output to stderr, a file, or multiple destinations.

Warnings

• Unstable Output Format: The output formats for all verbosity levels is not guaranteed and may be changed at any time without a breaking change.

Documentation

Overview

Package debugexporter exports data to console as logs.

Index

• func NewFactory() exporter.Factory
• type Config
  • func (cfg *Config) Validate() error

Functions

func NewFactory

func NewFactory() exporter.Factory

NewFactory creates and returns a new factory for the Debug exporter.

Types

type Config

type Config struct {
	// Verbosity defines the debug exporter verbosity.
	Verbosity configtelemetry.Level `mapstructure:"verbosity,omitempty"`

	// SamplingInitial defines how many samples are initially logged during each second.
	SamplingInitial int `mapstructure:"sampling_initial"`

	// SamplingThereafter defines the sampling rate after the initial samples are logged.
	SamplingThereafter int `mapstructure:"sampling_thereafter"`

	// UseInternalLogger defines whether the exporter sends the output to the collector's internal logger.
	UseInternalLogger bool `mapstructure:"use_internal_logger"`

	// OutputPaths is a list of file paths to write logging output to.
	// This option can only be used when use_internal_logger is false.
	// Special strings "stdout" and "stderr" are interpreted as os.Stdout and os.Stderr respectively.
	// All other values are treated as file paths.
	// If not set, defaults to ["stdout"].
	OutputPaths []string `mapstructure:"output_paths"`

	QueueConfig configoptional.Optional[exporterhelper.QueueBatchConfig] `mapstructure:"sending_queue"`
	// contains filtered or unexported fields
}

Config defines configuration for debug exporter.

func (*Config) Validate

func (cfg *Config) Validate() error

Validate checks if the exporter configuration is valid