From 79380c6f901cc43a558618c9aa5bde76614fd468 Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Tue, 26 Nov 2024 19:16:27 +0100 Subject: [PATCH] Add OTLP stdout exporter (#4183) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Towards https://github.com/open-telemetry/opentelemetry-specification/issues/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 https://github.com/open-telemetry/opentelemetry-specification/issues/3817 ~* [ ] Related [OTEP(s)](https://github.com/open-telemetry/oteps) #~ * [x] Links to the prototypes: https://github.com/open-telemetry/opentelemetry-java/pull/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 https://github.com/open-telemetry/opentelemetry-java/pull/6632 --------- Co-authored-by: Robert Pająk Co-authored-by: Cyrille Le Clerc Co-authored-by: Cijo Thomas --- CHANGELOG.md | 9 +++++ .../sdk-environment-variables.md | 19 +++++++++++ specification/protocol/file-exporter.md | 33 +++++++++++++++++++ 3 files changed, 61 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index d663dcb1cbb..bc12136fc4e 100644 --- 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 index 0014d3357e8..8a428fa0deb 100644 --- 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 index c9b8d800bc8..a60cce1539f 100644 --- a/specification/protocol/file-exporter.md +++ b/specification/protocol/file-exporter.md @@ -13,6 +13,9 @@ 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) @@ -20,6 +23,36 @@ Currently, it only describes the serialization of OpenTelemetry data to the OTLP - [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.