Merge branch 'main' into issue-433-extract-multi-value

CHANGELOG.md

@@ -14,10 +14,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
@@ -34,8 +43,14 @@ release.
 
 ### Common
 
+- Lay out core principles for Specification changes.
+  ([#4286](https://github.com/open-telemetry/opentelemetry-specification/pull/4286))
+
 ### Supplementary Guidelines
 
+- Add core principles for evaluating specification changes.
+  ([#4286](https://github.com/open-telemetry/opentelemetry-specification/pull/4286))
+
 ## v1.39.0 (2024-11-06)
 
 ### Logs

CONTRIBUTING.md

@@ -70,6 +70,9 @@ imperatives:
 It is important to build a specification that is clear and useful, not
 one that is needlessly restrictive and complex.
 
+Please see [Specification Principles](specification/specification-principles.md)
+for more information.
+
 ### Consistency Checks
 
 The Specification has a number of tools it uses to check things like style,

issue-management.md

@@ -68,3 +68,18 @@ Many SIGs track work in the specification repo that is outside of the triage pro
 These issues, which may be created by a SIG or just assigned to them, should be added to the SIG's project board and given the label `sig-issue`.
 If an issue is labeled as a `sig-issue`, it is the responsibility of the SIG to prioritize
 the issue appropriately, and ensure it is completed or closed as won't fix.
+
+## Issues blocking implementation
+
+SIGs that implement and document the specification in their respective language may run into issues with the specification,
+that block their implementation, or they may want to request a specification change related to an implementation change. To
+highlight issues of that kind SIG maintainers can request a `maintainer-request` label being added
+to an issue, if the following conditions are met:
+
+* the issue description or a comment by the maintainer points to at least one issue in an implementation repo, of which they are a maintainer.
+* the maintainer summarizes in the issue description or in a comment to an existing issue, what is blocking them and/or what is required from their point of view to make progress.
+* the maintainer tags all other maintainers of the implementation repo in the issue description or their comment (@open-telemetry/<sig>-maintainers). No action from the other maintainers is expected, except they disagree with
+  the request of this issue being tagged as `maintainer-request`.
+* they will share the issue with all other SIGs either via the [Maintainer Meeting](https://github.com/open-telemetry/community?tab=readme-ov-file#cross-cutting-sigs) or via a message to [#otel-maintainers](https://cloud-native.slack.com/archives/C01NJ7V1KRC) on [CNCF slack](https://slack.cncf.io). This way maintainers of other implementation SIGs can comment if they have the same request.
+
+A triager will add the `maintainer-request` label to the issue if those conditions are met.

oteps/README.md

@@ -4,6 +4,10 @@
 
 OpenTelemetry uses an "OTEP" (similar to a RFC) process for proposing changes to the OpenTelemetry Specification.
 
+> [!NOTE]
+> OTEPs are documents of intent. They become requirements only after their contents have been
+> [integrated](#integrating-the-otep-into-the-spec) into the actual [Specification](../specification).
+
 ### Table of Contents
 
 - [OpenTelemetry Enhancement Proposal (OTEP)](#opentelemetry-enhancement-proposal-otep)

specification/README.md

@@ -18,10 +18,13 @@ path_base_for_github_subdir:
 
 - [Overview](overview.md)
 - [Glossary](glossary.md)
-- [Versioning and stability for OpenTelemetry clients](versioning-and-stability.md)
-- [Library Guidelines](library-guidelines.md)
-  - [Package/Library Layout](library-layout.md)
-  - [General error handling guidelines](error-handling.md)
+- Principles and Guidelines
+  - [Core Principles](specification-principles.md)
+  - [Versioning and stability for OpenTelemetry clients](versioning-and-stability.md)
+  - [Library Guidelines](library-guidelines.md)
+    - [Package/Library Layout](library-layout.md)
+    - [General error handling guidelines](error-handling.md)
+  - [Performance](performance.md)
 - API Specification
   - [Context](context/README.md)
     - [Propagators](context/api-propagators.md)

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

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.

specification/specification-principles.md

@@ -0,0 +1,111 @@
+# Specification Principles
+
+This document defines common principles that will help designers create and extend
+the OpenTelemetry specification to adapt to new use cases and fix issues.
+
+## OpenTelemetry Mission and Values
+
+It should be taken in context of the [overall values of OpenTelemetry](https://opentelemetry.io/community/mission/), which lays out the following core values:
+
+- [Telemetry should be easy](https://opentelemetry.io/community/mission/#telemetry-should-be-easy)
+- [Telemetry should be universal](https://opentelemetry.io/community/mission/#telemetry-should-be-universal)
+- [Telemetry should be vendor-neutral](https://opentelemetry.io/community/mission/#telemetry-should-be-vendor-neutral)
+- [Telemetry should be loosely-coupled](https://opentelemetry.io/community/mission/#telemetry-should-be-loosely-coupled)
+- [Telemetry should be built-in](https://opentelemetry.io/community/mission/#telemetry-should-be-built-in)
+
+Additionally, it lays out the following core Engineering Values:
+
+- [Compatibility](https://opentelemetry.io/community/mission/#we-value-_compatibility_)
+- [Stability](https://opentelemetry.io/community/mission/#we-value-_stability_)
+- [Resilience](https://opentelemetry.io/community/mission/#we-value-_resilience_)
+- [Performance](https://opentelemetry.io/community/mission/#we-value-_performance_)
+  - See [Specification Performance Principles](performance.md) for more details.
+
+In addition to these core values, there are a set of things we've learned about
+Specification work and drive how we write our Specification.
+
+## Specification Principles
+
+Here are the key principles of the OpenTelemetry Specification:
+
+- [Be User Driven](#be-user-driven)
+- [Be General](#be-general)
+- [Be Stable](#be-stable)
+- [Be Consistent](#be-consistent)
+- [Be Simple](#be-stable)
+
+Note that at times some of these principles are at odds with each other. For
+example, keeping things stable may put constraints on possible simplicity. These
+principles are a rubric to guide design, and form a spectrum through which we
+evaluate additions or changes to the Specification.
+
+Let's look at each in more detail.
+
+### Be User Driven
+
+The specification is useless without the ecosystem it enables. Changes should
+focus on real world use cases, and real user needs. Additionally, changes should
+be implementable across the entire OpenTelemetry ecosystem.
+
+This means proposals should think "end to end" not "add this one little thing".
+
+Projects and proposals should provide prototypes or implementations
+before changes are made to the Specification.
+
+We have a few simple rules of thumb regarding prototypes:
+
+- API/SDK changes should be prototyped in three languages. The goal is
+  coverage of possible API designs, not any specific language:
+  - One language should cover typed Object-Oriented ecosystems (Java, .NET, etc.)
+  - One language should cover dynamically typed ecosystems (Python, JavaScript)
+  - One language should cover structural ecosystems (Go, Rust)
+- Protocol changes should be prototyped both on the client and the server.
+- Prototypes can be unmerged Pull Requests, existing projects, etc. but must
+  demonstrate the feature with confidence that the Specification of it will
+  be successful.
+
+### Be General
+
+The specification needs to be implementable across a wide range of languages,
+frameworks, ecosystems and communities. The specification should allow
+OpenTelemetry components to provide idiomatic experiences to their users.
+
+The specification should focus on *what* not *how*. When describing how, use
+non-normative language or supplementary guidelines, like this document.
+
+### Be Stable
+
+Don't. Break. Users.
+
+Yes, this is a repeat of the overall OpenTelemetry mission of
+[Stability](https://opentelemetry.io/community/mission/#we-value-_stability_).
+That's how important stability is.
+
+To achieve OpenTelemetry's mission of "Telemetry should be built-in", we need to
+create a set of components that are safe for users to depend on. Instability
+breaks trust, and hurts the mission of being a solution which application
+and library authors are glad to integrate with their software out of the box.
+
+When things do change, the specification (and implementation) should do the
+heavy lifting to ensure seamless, smooth experience for the OpenTelemetry
+ecosystem.
+
+### Be Consistent
+
+Don't make users learn new concepts and behaviors for each feature they interact
+with in OpenTelemetry.  This has three sub-principles:
+
+- Favor simple, broadly applicable features.
+- Prefer similar concepts and behaviors between signals.
+- Reuse naming conventions between signals, components, where possible.
+
+### Be Simple
+
+Simple is better than complicated. Abstractions should pay for themselves.
+OpenTelemetry has a large scope and many components. Solving a complex problem
+with simple design and solution leads to a much lower maintenance burden and
+easier evolution in the future.
+
+Additionally, a Specification is read and interpreted by many individuals.
+Complex language, nuanced wording and unclear descriptions lead to confusion and
+often times poor user experience as sections are not interpreted as desired.