[exporter/debug] add option use_internal_logger (#10227)

#### Description

Adds a new configuration option `use_internal_logger` to the Debug
exporter, that makes it possible to prevent unwanted side effects of the
exporter using the collector's internal logger.

#### Link to tracking issue

Fixes
#10226

#### Testing

Updated unit tests to cover the new config option.

#### Documentation

Added documentation for the feature.

---------

Co-authored-by: Yang Song <songy23@users.noreply.github.com>

.chloggen/debug-exporter-use-internal-logger.yaml

@@ -0,0 +1,25 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: exporter/debug
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add option `use_internal_logger`
+
+# One or more tracking issues or pull requests related to the change
+issues: [10226]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
+
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: []

exporter/debugexporter/README.md

@@ -14,7 +14,7 @@
 [k8s]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-k8s
 <!-- end autogenerated section -->
 
-Exports data to the console (stderr) via `zap.Logger`.
+Outputs telemetry data to the console for debugging purposes.
 
 See also the [Troubleshooting][troubleshooting_docs] document for examples on using this exporter.
 
@@ -35,6 +35,7 @@ The following settings are optional:
   To enable sampling, change `sampling_thereafter` to a value higher than `1`.
   Refer to [Zap docs](https://godoc.org/go.uber.org/zap/zapcore#NewSampler) 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](#using-the-collectors-internal-logger) for description.
 
 Example configuration:
 
@@ -120,8 +121,21 @@ Attributes:
         {"kind": "exporter", "data_type": "traces", "name": "debug"}
 ```
 
+## Using the collector's internal logger
+
+When `use_internal_logger` is set to `true` (the default), the exporter uses the collector's [internal logger][internal_telemetry] 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][internal_logs_config] 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 `stdout`.
+
+[internal_telemetry]: https://opentelemetry.io/docs/collector/internal-telemetry/
+[internal_logs_config]: https://opentelemetry.io/docs/collector/internal-telemetry/#configure-internal-logs
+
 ## 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.
-
-[telemetrygen]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/cmd/telemetrygen

exporter/debugexporter/config.go

@@ -30,6 +30,9 @@ type Config struct {
 
 	// 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"`
 }
 
 var _ component.Config = (*Config)(nil)

exporter/debugexporter/exporter_test.go

@@ -21,39 +21,51 @@ import (
 )
 
 func TestTracesExporterNoErrors(t *testing.T) {
-	lte, err := createTracesExporter(context.Background(), exportertest.NewNopSettings(), createDefaultConfig())
-	require.NotNil(t, lte)
-	assert.NoError(t, err)
-
-	assert.NoError(t, lte.ConsumeTraces(context.Background(), ptrace.NewTraces()))
-	assert.NoError(t, lte.ConsumeTraces(context.Background(), testdata.GenerateTraces(10)))
-
-	assert.NoError(t, lte.Shutdown(context.Background()))
+	for _, tc := range createTestCases() {
+		t.Run(tc.name, func(t *testing.T) {
+			lte, err := createTracesExporter(context.Background(), exportertest.NewNopSettings(), tc.config)
+			require.NotNil(t, lte)
+			assert.NoError(t, err)
+
+			assert.NoError(t, lte.ConsumeTraces(context.Background(), ptrace.NewTraces()))
+			assert.NoError(t, lte.ConsumeTraces(context.Background(), testdata.GenerateTraces(10)))
+
+			assert.NoError(t, lte.Shutdown(context.Background()))
+		})
+	}
 }
 
 func TestMetricsExporterNoErrors(t *testing.T) {
-	lme, err := createMetricsExporter(context.Background(), exportertest.NewNopSettings(), createDefaultConfig())
-	require.NotNil(t, lme)
-	assert.NoError(t, err)
-
-	assert.NoError(t, lme.ConsumeMetrics(context.Background(), pmetric.NewMetrics()))
-	assert.NoError(t, lme.ConsumeMetrics(context.Background(), testdata.GenerateMetricsAllTypes()))
-	assert.NoError(t, lme.ConsumeMetrics(context.Background(), testdata.GenerateMetricsAllTypesEmpty()))
-	assert.NoError(t, lme.ConsumeMetrics(context.Background(), testdata.GenerateMetricsMetricTypeInvalid()))
-	assert.NoError(t, lme.ConsumeMetrics(context.Background(), testdata.GenerateMetrics(10)))
-
-	assert.NoError(t, lme.Shutdown(context.Background()))
+	for _, tc := range createTestCases() {
+		t.Run(tc.name, func(t *testing.T) {
+			lme, err := createMetricsExporter(context.Background(), exportertest.NewNopSettings(), tc.config)
+			require.NotNil(t, lme)
+			assert.NoError(t, err)
+
+			assert.NoError(t, lme.ConsumeMetrics(context.Background(), pmetric.NewMetrics()))
+			assert.NoError(t, lme.ConsumeMetrics(context.Background(), testdata.GenerateMetricsAllTypes()))
+			assert.NoError(t, lme.ConsumeMetrics(context.Background(), testdata.GenerateMetricsAllTypesEmpty()))
+			assert.NoError(t, lme.ConsumeMetrics(context.Background(), testdata.GenerateMetricsMetricTypeInvalid()))
+			assert.NoError(t, lme.ConsumeMetrics(context.Background(), testdata.GenerateMetrics(10)))
+
+			assert.NoError(t, lme.Shutdown(context.Background()))
+		})
+	}
 }
 
 func TestLogsExporterNoErrors(t *testing.T) {
-	lle, err := createLogsExporter(context.Background(), exportertest.NewNopSettings(), createDefaultConfig())
-	require.NotNil(t, lle)
-	assert.NoError(t, err)
-
-	assert.NoError(t, lle.ConsumeLogs(context.Background(), plog.NewLogs()))
-	assert.NoError(t, lle.ConsumeLogs(context.Background(), testdata.GenerateLogs(10)))
-
-	assert.NoError(t, lle.Shutdown(context.Background()))
+	for _, tc := range createTestCases() {
+		t.Run(tc.name, func(t *testing.T) {
+			lle, err := createLogsExporter(context.Background(), exportertest.NewNopSettings(), createDefaultConfig())
+			require.NotNil(t, lle)
+			assert.NoError(t, err)
+
+			assert.NoError(t, lle.ConsumeLogs(context.Background(), plog.NewLogs()))
+			assert.NoError(t, lle.ConsumeLogs(context.Background(), testdata.GenerateLogs(10)))
+
+			assert.NoError(t, lle.Shutdown(context.Background()))
+		})
+	}
 }
 
 func TestExporterErrors(t *testing.T) {
@@ -69,6 +81,30 @@ func TestExporterErrors(t *testing.T) {
 	assert.Equal(t, errWant, le.pushLogs(context.Background(), plog.NewLogs()))
 }
 
+type testCase struct {
+	name   string
+	config *Config
+}
+
+func createTestCases() []testCase {
+	return []testCase{
+		{
+			name: "default config",
+			config: func() *Config {
+				return createDefaultConfig().(*Config)
+			}(),
+		},
+		{
+			name: "don't use internal logger",
+			config: func() *Config {
+				cfg := createDefaultConfig().(*Config)
+				cfg.UseInternalLogger = false
+				return cfg
+			}(),
+		},
+	}
+}
+
 type errMarshaler struct {
 	err error
 }

exporter/debugexporter/factory.go

@@ -43,6 +43,7 @@ func createDefaultConfig() component.Config {
 		Verbosity:          configtelemetry.LevelBasic,
 		SamplingInitial:    defaultSamplingInitial,
 		SamplingThereafter: defaultSamplingThereafter,
+		UseInternalLogger:  true,
 	}
 }
 
@@ -83,12 +84,38 @@ func createLogsExporter(ctx context.Context, set exporter.Settings, config compo
 }
 
 func createLogger(cfg *Config, logger *zap.Logger) *zap.Logger {
-	core := zapcore.NewSamplerWithOptions(
-		logger.Core(),
-		1*time.Second,
-		cfg.SamplingInitial,
-		cfg.SamplingThereafter,
-	)
+	var exporterLogger *zap.Logger
+	if cfg.UseInternalLogger {
+		core := zapcore.NewSamplerWithOptions(
+			logger.Core(),
+			1*time.Second,
+			cfg.SamplingInitial,
+			cfg.SamplingThereafter,
+		)
+		exporterLogger = zap.New(core)
+	} else {
+		exporterLogger = createCustomLogger(cfg)
+	}
+	return exporterLogger
+}
 
-	return zap.New(core)
+func createCustomLogger(exporterConfig *Config) *zap.Logger {
+	encoderConfig := zap.NewDevelopmentEncoderConfig()
+	// Do not prefix the output with log level (`info`)
+	encoderConfig.LevelKey = ""
+	// Do not prefix the output with current timestamp.
+	encoderConfig.TimeKey = ""
+	zapConfig := zap.Config{
+		Level:         zap.NewAtomicLevelAt(zap.InfoLevel),
+		DisableCaller: true,
+		Sampling: &zap.SamplingConfig{
+			Initial:    exporterConfig.SamplingInitial,
+			Thereafter: exporterConfig.SamplingThereafter,
+		},
+		Encoding:      "console",
+		EncoderConfig: encoderConfig,
+		// Send exporter's output to stdout. This should be made configurable.
+		OutputPaths: []string{"stdout"},
+	}
+	return zap.Must(zapConfig.Build())
 }

exporter/debugexporter/testdata/config_verbosity.yaml

@@ -1,3 +1,4 @@
 verbosity: detailed
 sampling_initial: 10
 sampling_thereafter: 50
+use_internal_logger: false