diff --git a/text/0258-env-context-baggage-carriers.md b/text/0258-env-context-baggage-carriers.md index 73e69009f..abdf35e5b 100644 --- a/text/0258-env-context-baggage-carriers.md +++ b/text/0258-env-context-baggage-carriers.md @@ -1,7 +1,7 @@ # Environment Variable Specification for Context and Baggage Propagation This is a proposal to add Environment Variables to the OpenTelemetry -specification as a carrier for context and baggage propagation between +specification as carriers for context and baggage propagation between processes. ## Table of Contents @@ -25,20 +25,19 @@ processes. ## Motivation The motivation for defining the specification for context and baggage -propagation by using environment variables as carriers stems from a long open -issue on the OpenTelemetry Specification repository, [issue #740][issue-740]. -This issue has been open for such a long time that multiple groups have gone -forward in implementing their own solutions to the problem using `TRACEPARENT` -and `TRACESTATE` environment variables. +propagation by using environment variables as carriers stems from the long open +[issue #740][issue-740] on the OpenTelemetry Specification repository. This +issue has been open for such a long time that multiple implementations now +exist using `TRACE_PARENT` and `TRACESTATE` environment variables. -[Issue #740][issue-740] identifies several use cases of systems that do not -communicate across bounds by leveraging HTTP communications such as: +[Issue #740][issue-740] identifies several use cases in systems that do not +communicate across bounds by leveraging network communications such as: * ETL * Batch * CI/CD systems -Adding arbitrary Text Map Propagation through environment variable carries into +Adding arbitrary [Text Map propagation][tmp] through environment variable carries into the OpenTelemetry Specification will enable distributed tracing within the above listed systems. @@ -53,11 +52,12 @@ native tracing wtihin CI/CD systems. [cicd-wg]: https://github.com/open-telemetry/community/blob/main/projects/ci-cd.md [issue-740]: https://github.com/open-telemetry/opentelemetry-specification/issues/740#issue-665588273 +[tmp]: https://opentelemetry.io/docs/specs/otel/context/api-propagators/#textmap-propagator ## Design To propagate context and baggage between parent, sibling, and child processes -in systems where HTTP communication does not occur between processes, a +in systems where network communication does not occur between processes, a specification using key-vaulue pairs injected into the environment can be read and produced by an arbitrary TextMapPropagator. @@ -85,8 +85,12 @@ process spans to the parent span, forming an end-to-end trace. > Text Map Propagation with a potential set of well-known environment variable > names. -`traceparent` (lowercase), originates in the [W3C Specification][w3c-parent] -and includes the following fields: +Given the above example referencing the W3C Specification, the following is an +elaboration on the mapping to headers defined by W3C. + +The `traceparent` (lowercase) header originates in the [W3C +Trace-Context][w3c-parent] specification and includes the following valid +fields: * `version` * `trace-id` @@ -99,12 +103,12 @@ This could be set in the environment as follows: export TRACEPARENT=version=2HEXDIGLC,trace-id=32HEXDIGLC,parent-id=16HEXDIGLC,trace-flags=2HEXDIGLC ``` -`tracestate` (lowercase), originates in the [W3C Specification][w2c-state] and -can include any opaque value in a key-value pair structure. Its goal is to -provide additional vendor-specific trace information. +The `tracestate` (lowercase) header originates in [W3C +Trace-State][w3c-state] and can include any opaque value in a key-value pair +structure. Its goal is to provide additional vendor-specific trace information. -`baggage` (lowercase), also is defined in the [W3C Specification][w3c-bag] and -is a set of key-value pairs to propagate context between signals. In +The `baggage` (lowercase) header originates in [W3C Baggage][w3c-bag] +and is a set of key-value pairs to propagate context between signals. In OpenTelemetry, baggage is propagated through the [Baggage API][bag-api]. [w3c-parent]: https://www.w3.org/TR/trace-context-2/#traceparent-header-field-values @@ -132,7 +136,7 @@ Additionally, the `init` span is able to pass baggage to the `plan` and `apply` spans. One example of this is module version and repository information. This information is only determined and known during the `init` process. Subsequent processes only know about the module by name. With `BAGGAGE` the rest of the -proccesses are able to understand a key piece of information which allows +processes are able to understand a key piece of information which allows errors to be tied back to original module version and source code. Defining the specification for Environment Variables as carriers will have a @@ -142,6 +146,12 @@ of the normal HTTP microservice architecture. [w3c-bag]: https://www.w3.org/TR/baggage/#header-name [bag-api]: https://opentelemetry.io/docs/specs/otel/baggage/api/ +The above prototype example came from the resources mentioned in [this +comment][otcom] on the [OpenTofu Tracing RFC][otrfc]. + +[otcom]: https://github.com/opentofu/opentofu/pull/2028#issuecomment-2411588695 +[otrfc]: https://github.com/opentofu/opentofu/pull/2028 + ## Core Specification Changes The OpenTelemetry Specification should be updated with the definitions for @@ -188,15 +198,15 @@ UNIX system utilities use upper-case for environment variables and lower-case are reserved for applications. Using upper-case will prevent conflicts with internal application variables. -Environment variable names used by the utilities in the XCU specification -consist solely of upper-case letters, digits and the "_" (underscore) from the -characters defined in Portable Character Set. Other characters may be permitted -by an implementation; applications must tolerate the presence of such names. -Upper- and lower-case letters retain their unique identities and are not folded -together. The name space of environment variable names containing lower-case -letters is reserved for applications. Applications can define any environment -variables with names from this name space without modifying the behaviour of -the standard utilities. +Environment variable names used by the utilities in the Shell and Utilities +(XCU) specification consist solely of upper-case letters, digits and the "_" +(underscore) from the characters defined in Portable Character Set. Other +characters may be permitted by an implementation; applications must tolerate +the presence of such names. Upper- and lower-case letters retain their unique +identities and are not folded together. The name space of environment variable +names containing lower-case letters is reserved for applications. Applications +can define any environment variables with names from this name space without +modifying the behaviour of the standard utilities. Source: [The Open Group, The Single UNIX® Specification, Version 2, Environment Variables](https://pubs.opengroup.org/onlinepubs/7908799/xbd/envvar.html) @@ -291,4 +301,6 @@ The author has no open questions at this point. ## Future possibilities -1. Enabling distributed tracing in systems that do not communicate over HTTP. +1. Enabling distributed tracing in systems that do not communicate over network + protocols that allow trace context being propagated through headers, + metadata, or other means.