Merge branch 'main' into lychee

.chloggen/1694.yaml

@@ -0,0 +1,8 @@
+change_type: enhancement
+component: docs
+note: Update attribute, events, and metrics naming guidance to include new best practices.
+subtext: |
+  - Use namespaces (with `.` delimiter) whenever possible.
+  - Use precise, descriptive, unambiguous names that leave room for expansion.
+
+issues: [1694]

.chloggen/genai-request-seed.yaml

@@ -0,0 +1,5 @@
+change_type: 'enhancement'
+component: gen_ai
+note: Introduce gen_ai.request.seed and deprecated gen_ai.openai.request.seed
+
+issues: [1710]

CONTRIBUTING.md

@@ -13,14 +13,16 @@ requirements and recommendations.
 
 - [Sign the CLA](#sign-the-cla)
 - [How to Contribute](#how-to-contribute)
+  - [Which semantic conventions belong in this repo](#which-semantic-conventions-belong-in-this-repo)
   - [Prerequisites](#prerequisites)
   - [1. Modify the YAML model](#1-modify-the-yaml-model)
     - [Code structure](#code-structure)
     - [Schema files](#schema-files)
   - [2. Update the markdown files](#2-update-the-markdown-files)
     - [Hugo frontmatter](#hugo-frontmatter)
-  - [3. Verify the changes before committing](#3-verify-the-changes-before-committing)
-  - [4. Changelog](#4-changelog)
+  - [3. Check new convention](#3-check-new-convention)
+  - [4. Verify the changes before committing](#4-verify-the-changes-before-committing)
+  - [5. Changelog](#5-changelog)
     - [When to add a Changelog Entry](#when-to-add-a-changelog-entry)
       - [Examples](#examples)
     - [Adding a Changelog Entry](#adding-a-changelog-entry)
@@ -31,7 +33,6 @@ requirements and recommendations.
   - [Markdown style](#markdown-style)
   - [Misspell check](#misspell-check)
   - [Markdown link check](#markdown-link-check)
-  - [Version compatibility check](#version-compatibility-check)
 - [Updating the referenced specification version](#updating-the-referenced-specification-version)
 - [Making a Release](#making-a-release)
 - [Merging existing ECS conventions](#merging-existing-ecs-conventions)
@@ -62,6 +63,25 @@ key, but non-obvious, aspects:
 
 Please make sure all Pull Requests are compliant with these rules!
 
+### Which semantic conventions belong in this repo
+
+This repo contains semantic conventions supported by the OpenTelemetry ecosystem
+including, but not limited to, components hosted in OpenTelemetry.
+
+Instrumentations hosted in OpenTelemetry SHOULD contribute their semantic
+conventions to this repo with the following exceptions:
+
+- Instrumentations that follow external schema not fully compatible with OpenTelemetry such as
+  [Kafka client JMX metrics](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/v2.10.0/instrumentation/kafka/kafka-clients/kafka-clients-2.6/library/README.md)
+  or [RabbitMQ Collector Receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.116.0/receiver/rabbitmqreceiver)
+  SHOULD document such conventions in their own repository.
+
+Having all OTel conventions in this repo allows to reuse common attributes, enforce naming and compatibility policies,
+and helps to keep conventions consistent and backward compatible.
+
+Want to define your own conventions outside this repo while building on OTel’s?
+Come help us [decentralize semantic conventions](https://github.com/open-telemetry/weaver/issues/215).
+
 ### Prerequisites
 
 The Specification uses several tools to check things like style,
@@ -106,6 +126,8 @@ The YAML (model definition) and Markdown (documentation) files are organized in
 │   │   ├── ....md
 ├── model
 │   ├── {root-namespace}
+│   │   ├── deprecated
+│   │   |   ├── registry-deprecated.yaml
 │   │   ├── events.yaml
 │   │   ├── metrics.yaml
 │   │   ├── registry.yaml
@@ -126,6 +148,9 @@ HTTP spans are defined in `model/http/spans.yaml`.
 YAML definitions could be broken down into multiple files. For example, AWS spans
 are defined in `/model/aws/lambda-spans.yaml` and `/model/aws/sdk-spans.yaml` files.
 
+Deprecated conventions should be placed under `/model/{root-namespace}/deprecated`
+folder.
+
 #### Schema files
 
 When making changes to existing semantic conventions (attributes, metrics, etc)
@@ -137,6 +162,7 @@ For details, please read
 You can also take examples from past changes inside the `schemas` folder.
 
 > [!WARNING]
+>
 > DO NOT add your changes to files inside the `schemas` folder. Always add your
 > changes to the `schema-next.yaml` file.
 
@@ -167,7 +193,21 @@ When creating new markdown files, you should provide the `linkTitle` attribute.
 This is used to generate the navigation bar on the website,
 and will be listed relative to the "parent" document.
 
-### 3. Verify the changes before committing
+### 3. Check new convention
+
+Semantic conventions are validated for name formatting and backward compatibility with last released versions.
+Here's [the full list of compatibility checks](./policies/compatibility.rego).
+
+Removing attributes, metrics, or enum members is not allowed, they should be deprecated instead.
+It applies to stable and experimental conventions and prevents semantic conventions auto-generated libraries from introducing breaking changes.
+
+You can run backward compatibility check (along with other policies) in all yaml files with the following command:
+
+```bash
+make check-policies
+```
+
+### 4. Verify the changes before committing
 
 Before sending a PR with your changes, make sure to run the automated checks:
 
@@ -178,7 +218,7 @@ make check
 Alternatively, you can run each check individually.
 Refer to the [Automation](#automation) section for more details.
 
-### 4. Changelog
+### 5. Changelog
 
 #### When to add a Changelog Entry
 
@@ -341,18 +381,6 @@ To check the validity of links in all markdown files, run the following command:
 make markdown-link-check
 ```
 
-### Version compatibility check
-
-Semantic conventions are validated for backward compatibility with last released versions. Here's [the full list of compatibility checks](./policies/compatibility.rego).
-Removing attributes, metrics, or enum members is not allowed, they should be deprecated instead.
-It applies to stable and experimental conventions and prevents semantic conventions auto-generated libraries from introducing breaking changes.
-
-You can run backward compatibility check (along with other policies) in all yaml files with the following command:
-
-```bash
-make check-policies
-```
-
 ## Updating the referenced specification version
 
 1. Open the `./internal/tools/update_specification_version.sh` script.
@@ -399,7 +427,7 @@ exists in some form in ECS, consider the following guidelines:
     data, user issue reports, feature requests, examples of prior work on a
     different standard or comparable evidence about the alternatives.
   - When no suitable alternatives are provided, altering an ECS name solely
-    for the purpose of complying with [Name Pluralization guidelines](docs/general/attribute-naming.md#name-pluralization-guidelines)
+    for the purpose of complying with [Name Pluralization guidelines](docs/general/naming.md#attribute-name-pluralization-guidelines)
     MAY BE avoided.
 - Do not use an existing ECS name as a namespace. If the name must differ, use a
   different namespace name to avoid clashes or avoid using the namespace

Makefile

@@ -185,7 +185,7 @@ fix-format:
 # Run all checks in order of speed / likely failure.
 # As a last thing, run attribute registry generation and git-diff for differences.
 .PHONY: check
-check: misspell markdownlint check-format markdown-toc compatibility-check markdown-link-check check-policies attribute-registry-generation
+check: misspell markdownlint check-format markdown-toc markdown-link-check check-policies attribute-registry-generation
 	git diff --exit-code ':*.md' || (echo 'Generated markdown Table of Contents is out of date, please run "make markdown-toc" and commit the changes in this PR.' && exit 1)
 	@echo "All checks complete"
 

docs/attributes-registry/README.md

@@ -16,15 +16,16 @@ The attributes registry is the place where attributes are defined. An attribute
 - a `brief` description of the attribute and optionally a longer `note`
 - example values
 
-Attributes defined in the registry can be used in different semantic conventions. Attributes should be included in this registry before they are used in semantic conventions. Semantic conventions may override all the properties of an attribute except for the `id` and `type` in case it's required for a particular context. In addition, semantic conventions specify the requirement level of an attribute in the corresponding context.
+Attributes defined in the registry can be used in different semantic conventions. Attributes should be included in this registry before they are used in semantic conventions. Semantic conventions may override all the properties of an attribute except for the `id`, `type` and `stability` in case it's required for a particular context. In addition, semantic conventions specify the requirement level of an attribute in the corresponding context.
 
 A definition of an attribute in the registry doesn't necessarily imply that the attribute is used in any of the semantic conventions.
 
 If applicable, application developers are encouraged to use existing attributes from this registry. See also [these recommendations][developers recommendations] regarding attribute selection and attribute naming for custom use cases.
 
 All registered attributes are listed by namespace in this registry.
 
-> **Warning**
+> [!WARNING]
+>
 > The following registry overview is a work in progress.
 >
 > Further attribute namespaces are currently being migrated and will appear in this registry soon.
@@ -45,12 +46,12 @@ Currently, the following namespaces exist:
 - [Code](code.md)
 - [Container](container.md)
 - [CPU](cpu.md)
-- [Db](db.md)
+- [DB](db.md)
 - [Deployment](deployment.md)
 - [Destination](destination.md)
 - [Device](device.md)
 - [Disk](disk.md)
-- [Dns](dns.md)
+- [DNS](dns.md)
 - [Dotnet](dotnet.md)
 - [Enduser](enduser.md)
 - [Error](error.md)
@@ -102,4 +103,4 @@ Currently, the following namespaces exist:
 - [VCS](vcs.md)
 - [Webengine](webengine.md)
 
-[developers recommendations]: ../general/attribute-naming.md#recommendations-for-application-developers
+[developers recommendations]: ../general/naming.md#recommendations-for-application-developers

docs/attributes-registry/aws.md

@@ -21,7 +21,7 @@ This document defines generic attributes for AWS services.
 | Attribute | Type | Description | Examples | Stability |
 |---|---|---|---|---|
 | <a id="aws-extended-request-id" href="#aws-extended-request-id">`aws.extended_request_id`</a> | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| <a id="aws-request-id" href="#aws-request-id">`aws.request_id`</a> | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| <a id="aws-request-id" href="#aws-request-id">`aws.request_id`</a> | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 ## Amazon DynamoDB Attributes