Add OTLP stdout exporter (open-telemetry#4183)

Towards open-telemetry#3817 ## Changes Add OTLP Stdout exporter. For non-trivial changes, follow the [change proposal process](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CONTRIBUTING.md#proposing-a-change). * [x] Related issues open-telemetry#3817 ~* [ ] Related [OTEP(s)](https://github.com/open-telemetry/oteps) #~ * [x] Links to the prototypes: open-telemetry/opentelemetry-java#6632 * [x] [`CHANGELOG.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CHANGELOG.md) file updated for non-trivial changes ~* [ ] [`spec-compliance-matrix.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md) updated if necessary~ * [x] reference implementation open-telemetry/opentelemetry-java#6632 --------- Co-authored-by: Robert Pająk <[email protected]> Co-authored-by: Cyrille Le Clerc <[email protected]> Co-authored-by: Cijo Thomas <[email protected]>
pellared · Nov 26, 2024 · 79380c6 · 79380c6
1 parent 881f364
commit 79380c6
Show file tree

Hide file tree

Showing 3 changed files with 61 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,10 +11,19 @@ release.
 
 ### Traces
 
+- Add in-development support for `otlp/stdout` exporter via `OTEL_TRACES_EXPORTER`.
+  ([#4183](https://github.com/open-telemetry/opentelemetry-specification/pull/4183))
+
 ### Metrics
 
+- Add in-development support for `otlp/stdout` exporter via `OTEL_METRICS_EXPORTER`.
+  ([#4183](https://github.com/open-telemetry/opentelemetry-specification/pull/4183))
+
 ### Logs
 
+- Add in-development support for `otlp/stdout` exporter via `OTEL_LOGS_EXPORTER`.
+ ([#4183](https://github.com/open-telemetry/opentelemetry-specification/pull/4183))
+
 ### Events
 
 ### Baggage

diff --git a/specification/configuration/sdk-environment-variables.md b/specification/configuration/sdk-environment-variables.md
@@ -32,6 +32,7 @@ aliases:
 - [Zipkin Exporter](#zipkin-exporter)
 - [Prometheus Exporter](#prometheus-exporter)
 - [Exporter Selection](#exporter-selection)
+  * [In-development Exporter Selection](#in-development-exporter-selection)
 - [Metrics SDK Configuration](#metrics-sdk-configuration)
   * [Exemplar](#exemplar)
   * [Periodic exporting MetricReader](#periodic-exporting-metricreader)
@@ -270,6 +271,24 @@ Known values for `OTEL_LOGS_EXPORTER` are:
 NOT be supported by new implementations.
 - `"none"`: No automatically configured exporter for logs.
 
+### In-development Exporter Selection
+
+**Status**: [Development](../document-status.md)
+
+In addition to the above, the following environment variables are added for in-development exporter selection:
+
+Additional known values for `OTEL_TRACES_EXPORTER` are:
+
+- `"otlp/stdout"`: [OTLP File](../protocol/file-exporter.md) writing to standard output
+
+Additional known values for `OTEL_METRICS_EXPORTER` are:
+
+- `"otlp/stdout"`: [OTLP File](../protocol/file-exporter.md) writing to standard output
+
+Additional known values for `OTEL_LOGS_EXPORTER` are:
+
+- `"otlp/stdout"`: [OTLP File](../protocol/file-exporter.md) writing to standard output
+
 ## Metrics SDK Configuration
 
 ### Exemplar

diff --git a/specification/protocol/file-exporter.md b/specification/protocol/file-exporter.md
@@ -13,13 +13,46 @@ Currently, it only describes the serialization of OpenTelemetry data to the OTLP
 
 ## Table of Contents
 
+- [Use Cases](#use-cases)
+- [Exporter configuration](#exporter-configuration)
+  - [Programmatic configuration](#programmatic-configuration)
 - [JSON File serialization](#json-file-serialization)
   - [File storage requirements](#file-storage-requirements)
     - [JSON lines file](#json-lines-file)
     - [Streaming appending](#streaming-appending)
   - [Telemetry data requirements](#telemetry-data-requirements)
   - [Examples](#examples)
 
+## Use Cases
+
+Why do we need a file exporter - why not just use the OTLP exporter?
+
+- *Faas*: In a FaaS environment, the OTLP exporter may not be able to send data to a collector.
+- *Consistent log scraping from pods*: In a Kubernetes environment, logs are often scraped from the stdout pod file.
+  This exporter can be used to write logs to stdout - which makes it easier to integrate with existing log scraping tools.
+  Existing solutions add metadata, such as the trace ID, to the log line,
+  which needs manual configuration and is error-prone.
+- *Reliability*: Some prefer writing logs to a file rather than sending data over the network for reliability reasons.
+
+## Exporter configuration
+
+The metric exporter MUST support the environment variables defined in the
+[OTLP Exporter](../metrics/sdk_exporters/otlp.md#additional-environment-variable-configuration)
+specification.
+
+If a language provides a mechanism to automatically configure a
+span or logs processor to pair with the associated
+exporter (e.g., using the [`OTEL_TRACES_EXPORTER` environment
+variable](../configuration/sdk-environment-variables.md#exporter-selection)), by
+default the OpenTelemetry Protocol File Exporter SHOULD be paired with a batching
+processor.
+
+### Programmatic configuration
+
+| Requirement | Name                       | Description                                                                                            | Default |
+|-------------|----------------------------|--------------------------------------------------------------------------------------------------------|---------|
+| MUST        | output stream (or similar) | Configure output stream. This SHOULD include the possibility to configure the output stream to a file. | stdout  |
+
 ## JSON File serialization
 
 This document describes the serialization of OpenTelemetry data as JSON objects that can be stored in files.