Merge remote-tracking branch 'upstream/main' into complex-event-attri…

…butes

.lychee.toml

@@ -0,0 +1,13 @@
+include-fragments = true
+
+accept = ["200..=299", "403"]
+
+exclude  = [
+    # excluding links to pull requests and issues is done for performance
+    "^https://github.com/open-telemetry/opentelemetry-specification/(issue|pull)/\\d+$",
+    # TODO (trask) look into this
+    "^https://docs.google.com/document/d/1d0afxe3J6bQT-I6UbRXeIYNcTIyBQv4axfjKF4yvAPA/edit"
+]
+
+# better to be safe and avoid failures
+max-retries = 6

CHANGELOG.md

@@ -9,6 +9,39 @@ release.
 
 ### Context
 
+### Traces
+
+### Metrics
+
+### Logs
+
+### Events
+
+- Support complex attributes in the Event API
+  ([#4334](https://github.com/open-telemetry/opentelemetry-specification/pull/4334))
+
+### Baggage
+
+### Resource
+
+### Profiles
+
+### OpenTelemetry Protocol
+
+### Compatibility
+
+### SDK Configuration
+
+### Common
+
+### Supplementary Guidelines
+
+### OTEPs
+
+## v1.40.0 (2024-12-12)
+
+### Context
+
 - Adds optional `GetAll` method to `Getter` in Propagation API, allowing for the retrieval of multiple values for the same key.
   [#4295](https://github.com/open-telemetry/opentelemetry-specification/pull/4295)
 
@@ -36,25 +69,13 @@ release.
   ([#4301](https://github.com/open-telemetry/opentelemetry-specification/pull/4301))
 - Change `event.name` attribute into top-level event name field.
   ([#4320](https://github.com/open-telemetry/opentelemetry-specification/pull/4320))
-- Support complex attributes in the Event API
-  ([#4334](https://github.com/open-telemetry/opentelemetry-specification/pull/4334))
 
 ### Events
 
 - Deprecate Events API and SDK in favor of having Events support in the Logs API and SDK.
   ([#4319](https://github.com/open-telemetry/opentelemetry-specification/pull/4319))
-
-### Baggage
-
-### Resource
-
-### Profiles
-
-### OpenTelemetry Protocol
-
-### Compatibility
-
-### SDK Configuration
+- Change `event.name` attribute into top-level event name field.
+  ([#4320](https://github.com/open-telemetry/opentelemetry-specification/pull/4320))
 
 ### Common
 
@@ -66,6 +87,12 @@ release.
 - Add core principles for evaluating specification changes.
   ([#4286](https://github.com/open-telemetry/opentelemetry-specification/pull/4286))
 
+## OTEPs
+
+- The [open-telemetry/oteps](https://github.com/open-telemetry/oteps) repository was
+  merged into the specification repository.
+ ([#4288](https://github.com/open-telemetry/opentelemetry-specification/pull/4288))
+
 ## v1.39.0 (2024-11-06)
 
 ### Logs

CONTRIBUTING.md

@@ -289,34 +289,15 @@ Release Procedure:
 
 1. Prepare a [draft release here](https://github.com/open-telemetry/opentelemetry-specification/releases).
    Don't publish it yet.
-2. Create a PR with updated [CHANGELOG.md](CHANGELOG.md). The CHANGELOG.md must have a
+2. Run [opentelemetry.io workflow](https://github.com/open-telemetry/opentelemetry.io/actions/workflows/build-dev.yml)
+   against `opentelemetry-specification` submodule as a smoke-test for docs. Fix broken links, if any.
+3. Create a PR with updated [CHANGELOG.md](CHANGELOG.md). The CHANGELOG.md must have a
    heading with the new version number. Ensure that no CHANGELOG entries are missing or
    ended up in the wrong section (e.g., in the last released version rather than Unreleased).
-   The PR will fail the `schemas-check` Github action (all other actions must pass).
-   This is expected and will be fixed in the next steps. Have this PR reviewed and approved
-   and ready to be merged. While it is being reviewed you can work on step 3-4 in parallel.
-3. Prepare the schema file for the upcoming release. The schema file should be placed
-   in the `schemas` directory. If no changes to semantic conventions happened
-   since the last release which require a corresponding section in the schema file then
-   simply copy the previous schema file, rename it to the new version and add a section
-   with the new version number to the file. See for example the schema file for [1.9.0](
-   https://github.com/open-telemetry/opentelemetry-specification/blob/main/schemas/1.9.0)
-   that has no changes from 1.8.0.
-   The schema file may already exist if there were changes done to semantic conventions
-   and the schema file was created with corresponding changes.
-4. Create and merge the PR with the new schema file. Note the commit hash after merging.
-   If the schema file for the new release version previously existed then no new PR is
-   necessary, just note that latest commit hash of this repository.
-5. Once CHANGELOG.md PR is approved and ready to be merged we are ready to make the release.
-   Update the [opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io)
-   repository: the [opentelemetry-specification](
-   https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules)
-   submodule points to this repository. Create a PR and update the submodule to point to
-   the commit hash from step 4. Merge this PR. This should update the
-   [https://opentelemetry.io/](https://opentelemetry.io/) website and the new schema file
-   should be downloadable at `https://opentelemetry.io/schemas/<version>`.
-6. Re-trigger the `schema-checks` Github action on the PR that updates the CHANGELOG.md.
-   The action should pass now. Merge the PR.
-7. Add the changelog entries from `CHANGELOG.md` to the description of the previously
+4. Once CHANGELOG.md PR is approved and ready to be merged we are ready to make the release.
+5. Add the changelog entries from `CHANGELOG.md` to the description of the previously
    created [draft release here](
    https://github.com/open-telemetry/opentelemetry-specification/releases) and publish it.
+
+New release is then auto-discovered by [opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) pipelines which
+(via bot-generated PR) will eventually publish new version of the specification.

Makefile

@@ -27,11 +27,13 @@ misspell-correction:	$(MISSPELL)
 
 .PHONY: markdown-link-check
 markdown-link-check:
-	@if ! npm ls markdown-link-check; then npm install; fi
-	@for f in $(ALL_DOCS); do \
-		npx --no -- markdown-link-check --quiet --config .markdown_link_check_config.json $$f \
-			|| exit 1; \
-	done
+	docker run --rm \
+		--mount 'type=bind,source=$(PWD),target=/home/repo' \
+		lycheeverse/lychee \
+		--config home/repo/.lychee.toml \
+		--root-dir /home/repo \
+		-v \
+		home/repo
 
 # This target runs markdown-toc on all files that contain
 # a comment <!-- tocstop -->.

oteps/0202-events-and-logs-api.md

@@ -20,7 +20,7 @@ Here are a few situations that require recording of Events, there will be more.
   - Standalone events that occur when there is no span in progress, such as errors, user interaction events and web vitals.
 - Recording kubernetes events
 - Collector Entity events [link](https://docs.google.com/document/d/1Tg18sIck3Nakxtd3TFFcIjrmRO_0GLMdHXylVqBQmJA/edit)
-- Few other event systems described in [example mappings](../specification/logs/data-model.md#appendix-a-example-mappings) in the data model.
+- Few other event systems described in [example mappings](../specification/logs/data-model-appendix.md#appendix-a-example-mappings) in the data model.
 
 ### Can the current Log API interfaces be used for events?
 

oteps/logs/0097-log-data-model.md

@@ -426,7 +426,7 @@ field, which is fixed for a particular source, `Attributes` can vary for each
 occurrence of the event coming from the same source. Can contain information
 about the request context (other than TraceId/SpanId). SHOULD follow
 OpenTelemetry
-[semantic conventions for Attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-naming.md).
+[semantic conventions for Attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/naming.md#attributes).
 This field is optional.
 
 ## Example Log Records

oteps/metrics/0088-metric-instrument-optional-refinements.md

@@ -52,9 +52,9 @@ have three calling patterns (_Bound_, _Unbound_, and _Batch_) to
 capture measurements.  Asynchronous instruments (Observer and its
 refinements) use callbacks to capture measurements.
 
-All measurement APIs produce metric events consisting of [timestamp,
+All measurement APIs produce metric events consisting of timestamp,
 instrument descriptor, label set, and numerical
-value](../../specification/metrics/api.md#metric-event-format).  Synchronous instrument
+value.  Synchronous instrument
 events additionally have [Context](../../specification/context/README.md), describing
 properties of the associated trace and distributed correlation values.
 
@@ -107,8 +107,8 @@ without referring to the collection interval and without ambiguity.
 ### Last-value and Measure instruments
 
 Measure instruments do not define a Last Value relationship.  One
-reason is that [synchronous events can happen
-simultaneously](../../specification/metrics/api.md#time).
+reason is that synchronous events can happen
+simultaneously.
 
 For Measure instruments, it is possible to compute an aggregation that
 computes the last-captured value in a collection interval, but it is

oteps/metrics/0146-metrics-prototype-scenarios.md

@@ -3,7 +3,7 @@
 With the stable release of the tracing specification, the OpenTelemetry
 community is willing to spend more energy on metrics API/SDK. The goal is to get
 the metrics API/SDK specification to
-[`Experimental`](../../specification/versioning-and-stability.md#experimental)
+[`Experimental`](../../specification/versioning-and-stability.md#development)
 state by end of 5/2021, and make it
 [`Stable`](../../specification/versioning-and-stability.md#stable)
 before end of 2021:

oteps/trace/0173-messaging-semantic-conventions.md

@@ -3,7 +3,7 @@
 This document aims to capture scenarios and a road map, both of which will
 serve as a basis for [stabilizing](../../specification/versioning-and-stability.md#stable)
 the [existing semantic conventions for messaging](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/messaging),
-which are currently in an [experimental](../../specification/versioning-and-stability.md#experimental)
+which are currently in an [experimental](../../specification/versioning-and-stability.md#development)
 state. The goal is to declare messaging semantic conventions stable before the
 end of 2021.
 
@@ -19,14 +19,14 @@ and Service Bus, Amazon SQS, SNS, and Kinesis.
 
 Bringing the existing experimental semantic conventions for messaging to a
 stable state is a crucial step for users and instrumentation authors, as it
-allows them to rely on [stability guarantees](../../specification/versioning-and-stability.md#not-defined-semantic-conventions-stability),
+allows them to rely on [stability guarantees](../../specification/versioning-and-stability.md#semantic-conventions-stability),
 and thus to ship and use stable instrumentation.
 
 ## Roadmap
 
 1. This OTEP, consisting of scenarios and a proposed roadmap, is approved and
    merged.
-2. [Stability guarantees](../../specification/versioning-and-stability.md#not-defined-semantic-conventions-stability)
+2. [Stability guarantees](../../specification/versioning-and-stability.md#semantic-conventions-stability)
    for semantic conventions are approved and merged. This is not strictly related
    to semantic conventions for messaging but is a prerequisite for stabilizing any
    semantic conventions.

oteps/trace/0174-http-semantic-conventions.md

@@ -3,7 +3,7 @@
 This document aims to capture scenarios/open questions and a road map, both of
 which will serve as a basis for [stabilizing](../../specification/versioning-and-stability.md#stable)
 the [existing semantic conventions for HTTP](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/http),
-which are currently in an [experimental](../../specification/versioning-and-stability.md#experimental)
+which are currently in an [experimental](../../specification/versioning-and-stability.md#development)
 state. The goal is to declare HTTP semantic conventions stable before the
 end of Q1 2022.
 
@@ -16,7 +16,7 @@ and guidelines for instrumenting HTTP communication.
 
 Bringing the existing experimental semantic conventions for HTTP to a
 stable state is a crucial step for users and instrumentation authors, as it
-allows them to rely on [stability guarantees](../../specification/versioning-and-stability.md#not-defined-semantic-conventions-stability),
+allows them to rely on [stability guarantees](../../specification/versioning-and-stability.md#semantic-conventions-stability),
 and thus to ship and use stable instrumentation.
 
 > NOTE. This OTEP captures a scope for changes should be done to existing
@@ -26,7 +26,7 @@ experimental semantic conventions for HTTP, but does not propose solutions.
 
 1. This OTEP, consisting of scenarios/open questions and a proposed roadmap, is
    approved and merged.
-2. [Stability guarantees](../../specification/versioning-and-stability.md#not-defined-semantic-conventions-stability)
+2. [Stability guarantees](../../specification/versioning-and-stability.md#semantic-conventions-stability)
    for semantic conventions are approved and merged. This is not strictly related
    to semantic conventions for HTTP but is a prerequisite for stabilizing any
    semantic conventions.

specification/common/README.md

@@ -61,7 +61,7 @@ both containing an array of strings to represent a mapping
 
 Attributes are equal when their keys and values are equal.
 
-See [Attribute Naming](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-naming.md) for naming guidelines.
+See [Attribute Naming](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/naming.md#attributes) for naming guidelines.
 
 See [Requirement Level](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-requirement-level.md) for requirement levels guidelines.