Merge branch 'main' into system_semconv_non_normative

.chloggen/1655.yaml

@@ -0,0 +1,24 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: genai
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: |
+  Adds OpenAI API compatible `gen_ai.system` attribute values: `az.ai.openai`, `deepseek`, `gemini`, `groq`,
+  `perplexity` and `xai`. Elaborates that `openai` can be ambiguous due to API emulation.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1655]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:

.chloggen/1715.yaml

@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: breaking
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: gen_ai
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Rename `gen_ai.openai.request.seed` to `gen_ai.request.seed` and use it on general GenAI conventions.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1715]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:

.chloggen/1719.yaml

@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: genai
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Adds `mistral_ai` as a `gen_ai.system` attribute value.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1719]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:

.chloggen/add_k8s_jobs.yaml

@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: k8s
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add k8s metrics for job and cronjob
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1660]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:

.chloggen/code-rename.yaml

@@ -0,0 +1,26 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: breaking
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: code
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: rename `code.function`, `code.lineno`, `code.column` and `code.filepath`
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [ 1377, 1599 ]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  `code.function` renamed to `code.function.name`
+  `code.lineno` renamed to `code.line.number`
+  `code.column` renamed to `code.column.number`
+  `code.filepath` renamed to `code.file.path`

.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]

.github/CODEOWNERS

@@ -111,8 +111,8 @@
 /model/feature-flags/              @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-feature-flag-approvers
 
 # Tooling
-/policies/                              @open-telemetry/specs-semconv-approvers @open-telemetry/weaver-maintainers
-/policies_test/                         @open-telemetry/specs-semconv-approvers @open-telemetry/weaver-maintainers
-/templates/                             @open-telemetry/specs-semconv-approvers @open-telemetry/weaver-maintainers
-/internal/                              @open-telemetry/specs-semconv-approvers @open-telemetry/weaver-maintainers
-/docs/non-normative/code-generation.md  @open-telemetry/specs-semconv-approvers @open-telemetry/weaver-maintainers
+/policies/                              @open-telemetry/specs-semconv-approvers @open-telemetry/weaver-approvers
+/policies_test/                         @open-telemetry/specs-semconv-approvers @open-telemetry/weaver-approvers
+/templates/                             @open-telemetry/specs-semconv-approvers @open-telemetry/weaver-approvers
+/internal/                              @open-telemetry/specs-semconv-approvers @open-telemetry/weaver-approvers
+/docs/non-normative/code-generation.md  @open-telemetry/specs-semconv-approvers @open-telemetry/weaver-approvers

.github/workflows/changelog.yml

@@ -75,9 +75,7 @@ jobs:
             || { echo "New ./.chloggen/*.yaml file failed validation."; exit 1; }
 
       # In order to validate any links in the yaml file, render the config to markdown
-      - name: Render .chloggen changelog entries
+      - name: Run markdown-link-check on the changelog
         run: |
-          make chlog-preview 2> changelog_preview.md
-          cat changelog_preview.md
-      - name: Run markdown-link-check
-        run: make markdown-link-check-changelog-preview
+          make chlog-preview &> changelog_preview.md
+          make markdown-link-check-changelog-preview

.github/workflows/checks.yml

@@ -18,7 +18,7 @@ jobs:
       run: make check-file-and-folder-names-in-docs
 
     - name: run markdownlint
-      run: npx gulp lint-md
+      run: make markdownlint
 
   yamllint:
     runs-on: ubuntu-latest

.lychee.toml

@@ -0,0 +1,16 @@
+include_fragments = true
+
+accept = ["200..=299", "403"]
+
+exclude = [
+    "^https://www.foo.bar",
+    # excluding links to pull requests and issues is done for performance
+    "^https://github.com/open-telemetry/semantic-conventions/(pull|issues)/\\d+$",
+    "^https://github.com/open-telemetry/opentelemetry-specification/(pull|issues)/\\d+$"
+]
+
+# better to be safe and avoid failures
+max_retries = 6
+
+# insecure is currently needed for https://osi-model.com
+insecure = true

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,13 +162,30 @@ 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.
 
 ### 2. Update the markdown files
 
 After updating the YAML file(s), you need to update
-the respective markdown files. For this, run the following commands:
+the respective markdown files.
+If you want to update existing tables, just run the following commands:
+
+```bash
+make table-generation attribute-registry-generation
+```
+
+When defining new telemetry signals (spans, metrics, events, resources) in YAML,
+make sure to add a new markdown section describing them. Add the following
+code-snippet into the markdown file:
+
+```
+<!-- semconv new-group-id -->
+<!-- endsemconv -->
+```
+
+Then run markdown generation commands:
 
 ```bash
 make table-generation attribute-registry-generation
@@ -167,7 +209,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 +234,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 +397,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.