From fe733e0516a4f585b455a7749b4449f1464ce3f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Joaqu=C3=ADn=20Atria?= Date: Thu, 5 Oct 2023 17:36:29 +0100 Subject: [PATCH 1/5] Fix description of OTEL_ATTRIBUTE_COUNT_LIMIT (#3714) --- specification/configuration/sdk-environment-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/configuration/sdk-environment-variables.md b/specification/configuration/sdk-environment-variables.md index 3edd66f0513..51803982d45 100644 --- a/specification/configuration/sdk-environment-variables.md +++ b/specification/configuration/sdk-environment-variables.md @@ -148,7 +148,7 @@ See the SDK [Attribute Limits](../common/README.md#attribute-limits) section for | Name | Description | Default | Notes | | --------------------------------- | ------------------------------------ | ------- | ----- | | OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit| | -| OTEL_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 128 | | +| OTEL_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute count | 128 | | ## Span Limits From 9df932ffbe2722afb16cc41c0bbfe76474d97558 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 6 Oct 2023 07:40:35 -0700 Subject: [PATCH 2/5] Update two apache access logs mappings (#3712) Co-authored-by: Armin Ruech --- CHANGELOG.md | 3 +++ specification/logs/data-model-appendix.md | 4 ++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7033d96f4c2..a3b9b66c78e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,9 @@ release. ### Logs +- Update two apache access logs mappings. + ([#3712](https://github.com/open-telemetry/opentelemetry-specification/pull/3712)) + ### Resource ### OpenTelemetry Protocol diff --git a/specification/logs/data-model-appendix.md b/specification/logs/data-model-appendix.md index b5808cf7706..3b5d20ae51d 100644 --- a/specification/logs/data-model-appendix.md +++ b/specification/logs/data-model-appendix.md @@ -387,7 +387,7 @@ When mapping from the unified model to HEC, we apply this additional mapping: %a string Client address - Attributes["client.address"] + Attributes["client.socket.address"] %A @@ -399,7 +399,7 @@ When mapping from the unified model to HEC, we apply this additional mapping: %h string Client hostname. - Attributes["server.address"] + Attributes["client.address"] %m From 3b028689f338e19b89432a4876cd4ddc11471b54 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 10 Oct 2023 07:56:34 -0700 Subject: [PATCH 3/5] Add upgrading and version management documentation (#3695) Long ago, we defined upgrading procedures for OpenTelemetry, in [OTEP 147](https://github.com/open-telemetry/oteps/blob/main/text/0147-upgrade-procedures.md). However, we never added this language to the specification. This pull request adds the OTEP to the specification, verbatim, except for an addition at the top which clearly spells out dependency management for application developers, library maintainers, and SDK implementors. It has been two years, so I am open to changes to this document. Both for clarity, and to conform to how we currently practice upgrading and dependency management. --- CHANGELOG.md | 3 + specification/upgrading.md | 164 +++++++++++++++++++++++++++++++++++++ 2 files changed, 167 insertions(+) create mode 100644 specification/upgrading.md diff --git a/CHANGELOG.md b/CHANGELOG.md index a3b9b66c78e..b8177d697ea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -34,6 +34,9 @@ release. ### Common +- Add upgrading and version management documentation + ([#3695](https://github.com/open-telemetry/opentelemetry-specification/pull/3695)) + ### Supplementary Guidelines ## v1.25.0 (2023-09-13) diff --git a/specification/upgrading.md b/specification/upgrading.md new file mode 100644 index 00000000000..1c17e1aa1fd --- /dev/null +++ b/specification/upgrading.md @@ -0,0 +1,164 @@ +# The OpenTelemetry approach to upgrading + +Managing widely distributed software at scale requires careful design related to +backwards compatibility, versioning, and upgrading. The OpenTelemetry approach is +described below. If you are planning on using OpenTelemetry, it can be helpful to +understand how we approach this problem. + +## Component Overview + +To facilitate smooth upgrading and long term support, OpenTelemetry clients are +factored into several components. We use the following terms in the rest of this +document. + +**Packages** is a generic term for units of code which reference each other via +some form of dependency management. Note that every programming language has a +different approach to dependency management, and may use a different term, such +as module or library, to represent this concept. + +**The API** refers to the set of software packages that contain all of the interfaces +and constants needed to write OpenTelemetry instrumentation. An implementation of +the API may be registered during application startup. If no other implementation +is registered, the API registers a no-op implementation by default. + +**The SDK** refers to a framework which implements the API, provided by the OpenTelemetry +project. While alternative API implementations may be written to handle special +cases, we expect most users to install the SDK when running OpenTelemetry. + +**Plugin Interfaces** refer to extension points provided by the SDK. These include +interfaces for controlling sampling, exporting data, and various other lifecycle +hooks. Note that these interfaces are not part of the API. They are part of the SDK. + +**Instrumentation** refers to any code which calls the API. This includes the instrumentation +provided by the OpenTelemetry project, third party instrumentation, plus application +code and libraries which instrument themselves natively. + +**Plugins** refer to any package which implements an SDK Plugin Interface. This +includes the plugins provided by the OpenTelemetry project, plus third party plugins. + +There is an important distinction between Plugins and Instrumentation. Plugins implement +the Plugin Interfaces. Instrumentation calls the API. This difference is relevant +to OpenTelemetry’s approach to upgrading. + +## Dependency Management + +It is very important that OpenTelemetry users and implementors stay up to date with +the latest version of the OpenTelemetry API. OpenTelemetry follows strict rules in +regards to backwards compatibility. It is always safe to upgrade to the latest minor +version of an OpenTelemetry package. + +### Application Developers + +Developers who plan to install the OpenTelemetry SDK in their application are advised +to are advised to accept all minor version upgrades. This will ensure that applications +will always be built with the latest optimizations and security patches. + +Likewise, application developers are encouraged to depend upon all future versions +of the current major version of the OpenTelemetry API. This will ensure that version +conflicts will not occur when instrumentation is upgraded to make use of new features +in future minor versions. + +### Library Maintainers + +Developers who maintain OSS libraries are encouraged to use the OpenTelemetry API +to add instrumentation directly into their library code. We refer to this approach +as "native instrumentation." + +When adding the OpenTelemetry API as a dependency to your library, it is very important +to depend upon to ***all future versions*** of the current major version. + +Depending on a specific minor version ***can lead to version conflicts*** with other +libraries that make use of API features added in later minor versions. Minor version +bumps of the API will never cause a compatibility issue with existing instrumentation. +It is completely safe to depend on future versions of the API. + +### SDK Implementors + +Maintainers of the official OpenTelemetry SDKs as well as maintainers of alternative +SDKs MUST keep their implementations up to date and compatible with the latest version +of the OpenTelemetry API. + +When new minor versions of the OpenTelemetry API are released, they will contain +new features. This includes new interfaces, as well as new methods on current interfaces. +SDK maintainers are expected to release new versions which implement these features +in a timely manner. + +If you do not believe you will be able to continue to maintain an implementation +in this manner, we strongly recommend that you do not implement an alternative SDK. +It is inevitable that OpenTelemetry will release new features, and that application +developers and library maintainers will make use of these features. + +## The OpenTelemetry upgrade path + +Before we get into the design requirements, here’s how upgrading actually works. +Note that all OpenTelemetry components (API, SDK, Plugins, Instrumentation) have +separate version numbers. + +### API changes + +When new functionality is added to the OpenTelemetry API, a new minor version of +the API is released. These API changes are always additive and backwards compatible +from the perspective of existing Instrumentation packages which import and call +prior versions. Instrumentation written against all prior minor versions of the +API continues to work, and may be composed together into the same application without +creating a dependency conflict. + +API implementations are expected to always target the latest version of the API. +When a new version of the API is released, a version of the SDK which supports the +API is released in tandem. Old versions of the SDK are not expected to support newer +versions of the API. + +### SDK changes + +Bugs fixes, security patches, and performance improvements are released as patch +versions of the SDK. Support for new versions of the API are released as minor versions. +New Plugin Interfaces are released as a minor version bump to the SDK. + +Breaking changes to Plugin Interfaces are handled through deprecation. Instead of +breaking a Plugin Interface, a new interface is created and the existing interface +is marked as deprecated. Plugins which target the deprecated interface continue +to work, and the SDK provides default implementations of any missing functionality. +After one year, the deprecated Plugin Interface may be removed in a major version +release of the SDK. + +## Design requirements and explanations + +This approach to upgrading solves two critical design requirements, while minimizing +the maintenance overhead associated with legacy code. + +* Callers of the API are never broken. +* Users of the SDK can easily upgrade to the latest version. + +Indefinite support for existing Instrumentation is a critical feature of OpenTelemetry. +Millions of lines of code are expected to be written against the API. This includes +shared libraries which ship with integrated OpenTelemetry instrumentation. These +libraries must be able to compose together into applications without OpenTelemetry +creating a dependency conflict. While some Instrumentation will be updated to the +latest version of the API, such as that provided by the OpenTelemetry project, other +Instrumentation will never be updated. + +Consuming new Instrumentation may require users to upgrade to the latest version +of the SDK. If it was not easy to perform this upgrade, the OpenTelemetry project +would be forced to support older versions of the SDK, as well as older versions +of the entire Instrumentation ecosystem. + +This would be an enormous maintenance effort at best. But, as the OpenTelemetry +project only controls a portion of that ecosystem, it is also unfeasible. OpenTelemetry +cannot require that libraries with native instrumentation support multiple versions +of the API. Ensuring that application owners and operators can upgrade to the latest +version of the SDK resolves this issue. + +The primary blocker to upgrading the SDK is out of date Plugins. If a new version +of the SDK were to break existing Plugin Interfaces, no user would be able to upgrade +their SDK until the Plugins they depend on have been upgraded. Users could be caught +between instrumentation they depend on requiring a version of the API which is not +compatible with the version of the SDK which supports their Plugins. + +By following a deprecation pattern with Plugin Interfaces, we create a one year +window in which the Plugin ecosystem can upgrade after the release of a new SDK. +We believe this is sufficient time for any Plugin which is actively maintained +to make an upgrade, and for defunct Plugins to be identified and replaced. + +By ensuring that the SDK can be easily upgraded, we also provide a path for application +owners and operators to rapidly consume critical bug fixes and security patches, +without the need to backport these patches across a large number of prior SDK versions. From c517f628cc667d2aba7d6cdaba5950dfc5223808 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 11 Oct 2023 01:04:48 +0200 Subject: [PATCH 4/5] Release 1.26.0 (#3715) October release. --- CHANGELOG.md | 40 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b8177d697ea..09f79356db7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,11 +11,37 @@ release. ### Traces +### Metrics + +### Logs + +### Resource + +### OpenTelemetry Protocol + +### Compatibility + +### SDK Configuration + +### Common + +### Supplementary Guidelines + +## v1.26.0 (2023-10-10) + +### Context + +- No changes. + +### Traces + - `ParentBased` sampler is a decorator (not a composite). ([#3706](https://github.com/open-telemetry/opentelemetry-specification/pull/3706)) ### Metrics +- Consistently use "advisory parameters" instead of "advice parameters". + ([#3693](https://github.com/open-telemetry/opentelemetry-specification/pull/3693)) - Stabilize `ExplicitBucketBoundaries` instrument advisory parameter. ([#3694](https://github.com/open-telemetry/opentelemetry-specification/pull/3694)) @@ -26,12 +52,22 @@ release. ### Resource +- No changes. + ### OpenTelemetry Protocol +- No changes. + ### Compatibility +- Prometheus exporters omit empty resources and scopes without attributes. + ([#3660](https://github.com/open-telemetry/opentelemetry-specification/pull/3660)) + ### SDK Configuration +- Fix description of OTEL_ATTRIBUTE_COUNT_LIMIT + ([#3714](https://github.com/open-telemetry/opentelemetry-specification/pull/3714)) + ### Common - Add upgrading and version management documentation @@ -39,6 +75,8 @@ release. ### Supplementary Guidelines +- No changes. + ## v1.25.0 (2023-09-13) ### Context @@ -95,8 +133,6 @@ release. ([#3471](https://github.com/open-telemetry/opentelemetry-specification/pull/3471)) - Prometheus: Allow changing metric names by default when translating from Prometheus to OpenTelemetry. ([#3679](https://github.com/open-telemetry/opentelemetry-specification/pull/3679)) -- Prometheus exporters omit empty resources and scopes without attributes. - ([#3660](https://github.com/open-telemetry/opentelemetry-specification/pull/3660)) ### SDK Configuration From 3a1dde966a4ce87cce5adf464359fe369741bbea Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 11 Oct 2023 01:15:24 +0200 Subject: [PATCH 5/5] Add a new AddLink() operation to Span. (#3678) Fixes #454 Related to #3337 As the Messaging SIG merged its last OTEP 222, we will be adding operations that require Links after Span creation, taking a direct route with `AddLink()`, albeit without any of the new members suggested in #3337, e.g. `timestamp` (to be discussed in a separate issue). ``` AddLink(spanContext, attributes /* optional */) ``` --- CHANGELOG.md | 3 + spec-compliance-matrix.md | 1 + specification/common/README.md | 2 +- specification/compatibility/opencensus.md | 2 +- specification/compatibility/opentracing.md | 2 +- specification/trace/api.md | 72 ++++++++++++++-------- 6 files changed, 55 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 09f79356db7..8de6d0fc0c6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,9 @@ release. ### Traces +- Add a new AddLink() operation to Span (experimental). + ([#3678](https://github.com/open-telemetry/opentelemetry-specification/pull/3678)) + ### Metrics ### Logs diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 2dca0bfe514..f557bf621a3 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -67,6 +67,7 @@ formats is required. Implementing more than one format is optional. | Unicode support for keys and string values | | + | + | + | + | + | + | + | + | + | + | + | | [Span linking](specification/trace/api.md#specifying-links) | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | | Links can be recorded on span creation | | + | + | | + | + | + | + | + | + | + | | +| Links can be recorded after span creation | | | | | | | | | | | | | | Links order is preserved | | + | + | | + | + | + | + | + | + | + | | | [Span events](specification/trace/api.md#add-events) | | | | | | | | | | | | | | AddEvent | | + | + | + | + | + | + | + | + | + | + | + | diff --git a/specification/common/README.md b/specification/common/README.md index 239bdf2014a..1f17536bb64 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -123,7 +123,7 @@ at this time, as discussed in [data points](../metrics/data-model.md#metric-points), [Spans](../trace/api.md#set-attributes), Span [Events](../trace/api.md#add-events), Span -[Links](../trace/api.md#specifying-links) and +[Links](../trace/api.md#link) and [Log Records](../logs/data-model.md) may contain a collection of attributes. The keys in each such collection are unique, i.e. there MUST NOT exist more than one key-value pair with the same key. The enforcement of uniqueness may be performed diff --git a/specification/compatibility/opencensus.md b/specification/compatibility/opencensus.md index 390935d427b..ea271517e93 100644 --- a/specification/compatibility/opencensus.md +++ b/specification/compatibility/opencensus.md @@ -180,7 +180,7 @@ using the OpenCensus <-> OpenTelemetry bridge. This leads to some issues with OpenCensus APIs that allowed flexible specification of parent spans post-initialization. 2. Links added to spans after the spans are created. This is [not supported in - OpenTelemetry](../trace/api.md#specifying-links), therefore OpenCensus spans + OpenTelemetry](../trace/api.md#link), therefore OpenCensus spans that have links added to them after creation will be mapped to OpenTelemetry spans without the links. 3. OpenTelemetry specifies that samplers are diff --git a/specification/compatibility/opentracing.md b/specification/compatibility/opentracing.md index b75547b8577..b76a5363cba 100644 --- a/specification/compatibility/opentracing.md +++ b/specification/compatibility/opentracing.md @@ -544,7 +544,7 @@ OpenTracing defines two types of references: OpenTelemetry does not define strict equivalent semantics for these references. These reference types must not be confused with the -[Link](../trace/api.md#specifying-links) functionality. This information +[Link](../trace/api.md#link) functionality. This information is however preserved as the `opentracing.ref_type` attribute. ## In process Propagation exceptions diff --git a/specification/trace/api.md b/specification/trace/api.md index 425eff9d822..7cc1901ae74 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -4,7 +4,7 @@ linkTitle: API # Tracing API -**Status**: [Stable, Feature-freeze](../document-status.md) +**Status**: [Stable, Feature-freeze](../document-status.md), except where otherwise specified
Table of Contents @@ -35,6 +35,7 @@ linkTitle: API + [IsRecording](#isrecording) + [Set Attributes](#set-attributes) + [Add Events](#add-events) + + [Add Link](#add-link) + [Set Status](#set-status) + [UpdateName](#updatename) + [End](#end) @@ -42,6 +43,7 @@ linkTitle: API * [Span lifetime](#span-lifetime) * [Wrapping a SpanContext in a Span](#wrapping-a-spancontext-in-a-span) - [SpanKind](#spankind) +- [Link](#link) - [Concurrency](#concurrency) - [Included Propagators](#included-propagators) - [Behavior of the API in the absence of an installed SDK](#behavior-of-the-api-in-the-absence-of-an-installed-sdk) @@ -300,7 +302,7 @@ the entire operation and, optionally, one or more sub-spans for its sub-operatio - A start timestamp - An end timestamp - [`Attributes`](../common/README.md#attribute) -- A list of [`Link`s](#specifying-links) to other `Span`s +- A list of [`Link`s](#link) to other `Span`s - A list of timestamped [`Event`s](#add-events) - A [`Status`](#set-status). @@ -386,7 +388,7 @@ The API MUST accept the following parameters: to calling `SetAttribute` later, as samplers can only consider information already present during span creation. -- `Link`s - an ordered sequence of Links, see API definition [here](#specifying-links). +- `Link`s - an ordered sequence of Links, see [API definition](#link). - `Start timestamp`, default to current time. This argument SHOULD only be set when span creation time has already passed. If API is called at a moment of a Span logical start, API user MUST NOT explicitly set this argument. @@ -423,27 +425,10 @@ For example, a `Propagator` performing context extraction may need this. #### Specifying links -During `Span` creation, a user MUST have the ability to record links to other -`Span`s. Linked `Span`s can be from the same or a different trace -- see [Links -between spans](../overview.md#links-between-spans). `Link`s cannot be added after -Span creation. - -A `Link` is structurally defined by the following properties: - -- `SpanContext` of the `Span` to link to. -- Zero or more [`Attributes`](../common/README.md#attribute) further describing - the link. - -The Span creation API MUST provide: - -- An API to record a single `Link` where the `Link` properties are passed as - arguments. This MAY be called `AddLink`. This API takes the `SpanContext` of - the `Span` to link to and optional `Attributes`, either as individual - parameters or as an immutable object encapsulating them, whichever is most - appropriate for the language. Implementations MAY ignore links with an - [invalid](#isvalid) `SpanContext`. - -Links SHOULD preserve the order in which they're set. +During `Span` creation, a user MUST have the ability to record links to other `Span`s. +Linked `Span`s can be from the same or a different trace -- see [links](#link). +`Link`s added at `Span` creation may be considered by [Samplers](sdk.md#sampler) +to make a sampling decision. ### Span operations @@ -556,6 +541,13 @@ keys"](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/REA Note that [`RecordException`](#record-exception) is a specialized variant of `AddEvent` for recording exception events. +#### Add Link + +**Status**: [Experimental](../document-status.md) + +A `Span` MUST have the ability to add `Link`s associated with it after its creation - see [Links](#link). +`Link`s added after `Span` creation may not be considered by [Samplers](sdk.md#sampler). + #### Set Status Sets the `Status` of the `Span`. If used, this will override the default `Span` @@ -797,6 +789,38 @@ To summarize the interpretation of these kinds: | `CONSUMER` | | yes | maybe | | | `INTERNAL` | | | | | +## Link + +A user MUST have the ability to record links to other `SpanContext`s. +Linked `SpanContext`s can be from the same or a different trace -- see [Links +between spans](../overview.md#links-between-spans). + +A `Link` is structurally defined by the following properties: + +- `SpanContext` of the `Span` to link to. +- Zero or more [`Attributes`](../common/README.md#attribute) further describing + the link. + +The API MUST provide: + +- An API to record a single `Link` where the `Link` properties are passed as + arguments. This MAY be called `AddLink`. This API takes the `SpanContext` of + the `Span` to link to and optional `Attributes`, either as individual + parameters or as an immutable object encapsulating them, whichever is most + appropriate for the language. Implementations MAY ignore links with an + [invalid](#isvalid) `SpanContext`. + +The Span interface MAY provide: + +- An API to add multiple `Link`s at once, where the `Link`s are passed in a + single method call. + +Span SHOULD preserve the order in which `Link`s are set. + +The API documentation MUST state that adding links at span creation is preferred +to calling `AddLink` later, for contexts that are available during span creation, +because head sampling decisions can only consider information present during span creation. + ## Concurrency For languages which support concurrent execution the Tracing APIs provide