From 4f25eb5e5423edb065f3d24023b7f34617457b33 Mon Sep 17 00:00:00 2001
From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Date: Tue, 19 Mar 2024 11:21:40 +0100
Subject: [PATCH 01/18] Add Issue templates and automation scripts (#777)

---
 .github/ISSUE_TEMPLATE/bug_report.yaml        | 77 +++++++++++++++++++
 .github/ISSUE_TEMPLATE/change_proposal.yaml   | 64 +++++++++++++++
 .github/ISSUE_TEMPLATE/new-conventions.yaml   | 73 ++++++++++++++++++
 .github/workflows/checks.yml                  |  9 +++
 .../generate-registry-area-labels.yml         | 24 ++++++
 .github/workflows/prepare-new-issue.yml       | 22 ++++++
 .../scripts/generate-registry-area-labels.sh  | 34 ++++++++
 .../workflows/scripts/get-registry-areas.sh   | 16 ++++
 .../workflows/scripts/prepare-new-issue.sh    | 62 +++++++++++++++
 .yamllint                                     |  5 ++
 Makefile                                      |  6 ++
 .../scripts/update-issue-template-areas.sh    | 43 +++++++++++
 12 files changed, 435 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yaml
 create mode 100644 .github/ISSUE_TEMPLATE/change_proposal.yaml
 create mode 100644 .github/ISSUE_TEMPLATE/new-conventions.yaml
 create mode 100644 .github/workflows/generate-registry-area-labels.yml
 create mode 100644 .github/workflows/prepare-new-issue.yml
 create mode 100755 .github/workflows/scripts/generate-registry-area-labels.sh
 create mode 100755 .github/workflows/scripts/get-registry-areas.sh
 create mode 100755 .github/workflows/scripts/prepare-new-issue.sh
 create mode 100755 internal/tools/scripts/update-issue-template-areas.sh

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml
new file mode 100644
index 0000000000..08dca47531
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yaml
@@ -0,0 +1,77 @@
+name: Bug report
+description: Create a report to help us improve
+labels: ["bug", "triage:needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report! Please make sure to fill out the entire form below, providing as much context as you can in order to help us triage and track down your bug as quickly as possible.
+
+        Before filing a bug, please be sure you have searched through [existing bugs](https://github.com/open-telemetry/semantic-conventions/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Abug) to see if an existing issue covers your bug.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area(s)
+      description: Which area(s) does your bug report concern? If none fits, please select `area:other`
+      multiple: true
+      options:
+        - area:other
+        # NOTE: The list below is autogenerated using `make generate-gh-issue-templates`
+        # DO NOT manually edit it.
+        # Start semconv area list
+        - area:android
+        - area:browser
+        - area:client
+        - area:cloud
+        - area:code
+        - area:container
+        - area:db
+        - area:destination
+        - area:device
+        - area:disk
+        - area:dns
+        - area:error
+        - area:exception
+        - area:faas
+        - area:host
+        - area:http
+        - area:k8s
+        - area:messaging
+        - area:network
+        - area:oci
+        - area:os
+        - area:process
+        - area:rpc
+        - area:server
+        - area:source
+        - area:thread
+        - area:tls
+        - area:url
+        - area:user-agent
+        # End semconv area list
+  - type: textarea
+    attributes:
+      label: What happened?
+      description: Please provide as much detail as you reasonably can.
+      value: |
+        ## Description
+
+        ## Steps to Reproduce (if any)
+
+        ## Expected Result
+
+        ## Actual Result
+    validations:
+      required: true
+
+  - type: input
+    attributes:
+      label: Semantic convention version
+      description: What version did you use? (e.g., `v1.24.0`, `1eb551b`, etc)
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Additional context
+      description: Any additional information you think may be relevant to this issue.
diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml
new file mode 100644
index 0000000000..edaa3a4a75
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml
@@ -0,0 +1,64 @@
+name: Propose changes to existing conventions
+description: Propose changes you'd like to be added to existing conventions
+labels: ["enhancement", "triage:needs-triage"]
+body:
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area(s)
+      description: Which area(s) does your change request concern?
+      multiple: true
+      options:
+        # NOTE: The list below is autogenerated using `make generate-gh-issue-templates`
+        # DO NOT manually edit it.
+        # Start semconv area list
+        - area:android
+        - area:browser
+        - area:client
+        - area:cloud
+        - area:code
+        - area:container
+        - area:db
+        - area:destination
+        - area:device
+        - area:disk
+        - area:dns
+        - area:error
+        - area:exception
+        - area:faas
+        - area:host
+        - area:http
+        - area:k8s
+        - area:messaging
+        - area:network
+        - area:oci
+        - area:os
+        - area:process
+        - area:rpc
+        - area:server
+        - area:source
+        - area:thread
+        - area:tls
+        - area:url
+        - area:user-agent
+        # End semconv area list
+  - type: textarea
+    attributes:
+      label: Is your change request related to a problem? Please describe.
+      description: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Describe the solution you'd like
+      description: A clear and concise description of what you want to happen.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Describe alternatives you've considered
+      description: A clear and concise description of any alternative solutions or features you've considered.
+  - type: textarea
+    attributes:
+      label: Additional context
+      description: Add any other context or screenshots about the feature request here.
diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml
new file mode 100644
index 0000000000..8a72b6bff2
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml
@@ -0,0 +1,73 @@
+name: Propose new semantic conventions
+description: Propose new conventions you'd like to be part of the OpenTelemetry project
+labels: ["enhancement", "triage:needs-triage", "experts needed"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please make sure to fill out the entire form below, providing as much context as you can in order to help us triage the proposal as quickly as possible.
+
+        Before filing the proposal, please be sure you have searched through [existing issues](https://github.com/open-telemetry/semantic-conventions/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aenhancement+label%3Aarea:new) to see if an existing issue covers your proposal.
+
+        Additionally, make sure to read and follow the guidelines on [Project Proposal](https://github.com/open-telemetry/community/blob/main/project-management.md#project-management), in case the proposal is for a new set of conventions/working group.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area(s)
+      description: Which area(s) does your new conventions concern? If none fits, please select `area:new`
+      multiple: true
+      options:
+        - area:new
+        # NOTE: The list below is autogenerated using `make generate-gh-issue-templates`
+        # DO NOT manually edit it.
+        # Start semconv area list
+        - area:android
+        - area:browser
+        - area:client
+        - area:cloud
+        - area:code
+        - area:container
+        - area:db
+        - area:destination
+        - area:device
+        - area:disk
+        - area:dns
+        - area:error
+        - area:exception
+        - area:faas
+        - area:host
+        - area:http
+        - area:k8s
+        - area:messaging
+        - area:network
+        - area:oci
+        - area:os
+        - area:process
+        - area:rpc
+        - area:server
+        - area:source
+        - area:thread
+        - area:tls
+        - area:url
+        - area:user-agent
+        # End semconv area list
+  - type: textarea
+    attributes:
+      label: Is your change request related to a problem? Please describe.
+      description: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Describe the solution you'd like
+      description: A clear and concise description of what you want to happen.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Describe alternatives you've considered
+      description: A clear and concise description of any alternative solutions or features you've considered.
+  - type: textarea
+    attributes:
+      label: Additional context
+      description: Add any other context or screenshots about the feature request here.
diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml
index a387a9db22..dd48bff2ce 100644
--- a/.github/workflows/checks.yml
+++ b/.github/workflows/checks.yml
@@ -97,3 +97,12 @@ jobs:
     - uses: actions/checkout@v1
     - name: verify schemas
       run: make schema-check
+
+  areas-dropdown-check:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v1
+    - name: Components dropdown in issue templates
+      run: |
+        make generate-gh-issue-templates
+        git diff --exit-code '.github/ISSUE_TEMPLATE' || (echo 'Dropdowns in issue templates is out of date, please run "make generate-gh-issue-templates" and commit the changes in this PR.' && exit 1)
diff --git a/.github/workflows/generate-registry-area-labels.yml b/.github/workflows/generate-registry-area-labels.yml
new file mode 100644
index 0000000000..58f3b62b3a
--- /dev/null
+++ b/.github/workflows/generate-registry-area-labels.yml
@@ -0,0 +1,24 @@
+name: 'Generate registry area labels'
+on:
+  push:
+    branches: [main]
+    paths:
+      - model/registry/**
+      - ./.github/workflows/generate-registry-area-labels.yml
+      - ./.github/workflows/scripts/generate-registry-area-labels.sh
+  workflow_dispatch:
+
+jobs:
+  generate-component-labels:
+    runs-on: ubuntu-latest
+    if: ${{ github.repository_owner == 'open-telemetry' }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run update permissions
+        run: chmod +x ./.github/workflows/scripts/generate-registry-area-labels.sh
+
+      - name: Generate registry area labels
+        run: ./.github/workflows/scripts/generate-registry-area-labels.sh
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/prepare-new-issue.yml b/.github/workflows/prepare-new-issue.yml
new file mode 100644
index 0000000000..345b7dcd1e
--- /dev/null
+++ b/.github/workflows/prepare-new-issue.yml
@@ -0,0 +1,22 @@
+name: 'Prepare new issue'
+on:
+  issues:
+    types: [opened]
+
+jobs:
+  prepare-new-issue:
+    runs-on: ubuntu-latest
+    if: ${{ github.repository_owner == 'open-telemetry' }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run update permissions
+        run: chmod +x ./.github/workflows/scripts/prepare-new-issue.sh
+
+      - name: Run prepare-new-issue.sh
+        run: ./.github/workflows/scripts/prepare-new-issue.sh
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ISSUE: ${{ github.event.issue.number }}
+          BODY: ${{ github.event.issue.body }}
+          OPENER: ${{ github.event.issue.user.login }}
diff --git a/.github/workflows/scripts/generate-registry-area-labels.sh b/.github/workflows/scripts/generate-registry-area-labels.sh
new file mode 100755
index 0000000000..bd45812bc5
--- /dev/null
+++ b/.github/workflows/scripts/generate-registry-area-labels.sh
@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+#
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+#
+# Create labels for all semantic convention areas that are in model/registry.
+# Existing labels are not affected.
+#
+# Note that there is a 50-character limit on labels, so some areas may
+# not have a corresponding label.
+
+set -euo pipefail
+
+CUR_DIRECTORY=$(dirname "$0")
+AREAS=$(sh "${CUR_DIRECTORY}/get-registry-areas.sh")
+
+echo -e "\nStarting to create area labels"
+echo -e "--------------------------------\n"
+
+for AREA in ${AREAS}; do
+    LABEL_NAME=$(basename "${AREA}" .yaml)
+
+    if (( "${#LABEL_NAME}" > 50 )); then
+        echo "'${LABEL_NAME}' exceeds GitHubs 50-character limit on labels, skipping"
+        continue
+    fi
+    echo "area:${LABEL_NAME}"
+
+    #  gh label create "area:${LABEL_NAME}" -c "#425cc7"
+done
+
+echo -e "\nLabels created successfully"
+echo -e "--------------------------------\n"
+
diff --git a/.github/workflows/scripts/get-registry-areas.sh b/.github/workflows/scripts/get-registry-areas.sh
new file mode 100755
index 0000000000..b4fd8b6e18
--- /dev/null
+++ b/.github/workflows/scripts/get-registry-areas.sh
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+#
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+#
+# Get a list of the semantic conventions areas from the registry.
+
+CUR_DIRECTORY=$(dirname "$0")
+REPO_DIR="$( cd "$CUR_DIRECTORY/../../../" && pwd )"
+REGISTRY_DIR="$( cd "$REPO_DIR/model/registry" && pwd )"
+
+
+for entry in $(ls $REGISTRY_DIR | egrep '\.yaml$' | sort)
+do
+  echo "$entry"
+done
diff --git a/.github/workflows/scripts/prepare-new-issue.sh b/.github/workflows/scripts/prepare-new-issue.sh
new file mode 100755
index 0000000000..c8af7d0b4a
--- /dev/null
+++ b/.github/workflows/scripts/prepare-new-issue.sh
@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+#
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+#
+#
+
+# This script extracts the "Area" from the issue body and adds it as a label
+# on newly created issues. The area from the issue body comes from
+# the "Area" drop-down field in the ISSUE_TEMPLATE, which is auto-generated
+# from the files inside model/registry.
+
+# TODO: This script can be later used to also auto-assign the correct code-owner
+# once that is implemented.
+
+set -euo pipefail
+
+if [[ -z "${ISSUE:-}" || -z "${BODY:-}" || -z "${OPENER:-}" ]]; then
+  echo "Missing one of ISSUE, BODY, or OPENER, please ensure all are set."
+  exit 0
+fi
+
+LABELS=""
+AREAS_SECTION_START=$( (echo "${BODY}" | grep -n '### Area(s)' | awk '{ print $1 }' | grep -oE '[0-9]+') || echo '-1' )
+BODY_AREAS=""
+
+if [[ "${AREAS_SECTION_START}" != '-1' ]]; then
+  BODY_AREAS=$(echo "${BODY}" | sed -n $((AREAS_SECTION_START+2))p)
+fi
+
+for AREA in ${BODY_AREAS}; do
+  # Areas are delimited by ', ' and the for loop separates on spaces, so remove the extra comma.
+  AREA=${AREA//,/}
+
+  if (( "${#AREA}" > 50 )); then
+    echo "'${AREA}' exceeds GitHub's 50-character limit on labels, skipping adding a label"
+    continue
+  fi
+
+  if [[ -n "${LABELS}" ]]; then
+      LABELS+=","
+  fi
+    LABELS+="${AREA}"
+done
+
+if [[ -v PINGED_AREAS[@] ]]; then
+  echo "The issue was associated with areas:" "${!PINGED_AREAS[@]}"
+else
+  echo "No related areas were given"
+fi
+
+if [[ -n "${LABELS}" ]]; then
+  # Notes on this call:
+  # 1. Labels will be deduplicated by the GitHub CLI.
+  # 2. The call to edit the issue will fail if any of the
+  #    labels doesn't exist. We can be reasonably sure that
+  #    all labels will exist since they come from a known set.
+  echo "Adding the following labels: ${LABELS//,/ /}"
+  gh issue edit "${ISSUE}" --add-label "${LABELS}" || true
+else
+  echo "No labels were found to add"
+fi
diff --git a/.yamllint b/.yamllint
index 70b17e868b..0e43f20a2a 100644
--- a/.yamllint
+++ b/.yamllint
@@ -3,6 +3,9 @@ extends: default
 ignore-from-file:
   - .gitignore
 
+ignore: |
+  node_modules/*
+
 rules:
   document-start: disable
   octal-values: enable
@@ -10,6 +13,8 @@ rules:
     allowed-values: ['true', 'false', 'on']  # 'on' for GH action trigger
   line-length:
     max: 200
+    ignore: |
+      .github/*
   indentation:
     check-multi-line-strings: false
     indent-sequences: consistent
diff --git a/Makefile b/Makefile
index 3ef76b3827..283402f5c0 100644
--- a/Makefile
+++ b/Makefile
@@ -150,3 +150,9 @@ chlog-preview: $(CHLOGGEN)
 .PHONY: chlog-update
 chlog-update: $(CHLOGGEN)
 	$(CHLOGGEN) update --config $(CHLOGGEN_CONFIG) --version $(VERSION)
+
+# Updates the areas (registry yaml file names) on all ISSUE_TEMPLATE
+# files that have the "area" dropdown field
+.PHONY: generate-gh-issue-templates
+generate-gh-issue-templates:
+	$(TOOLS_DIR)/scripts/update-issue-template-areas.sh
diff --git a/internal/tools/scripts/update-issue-template-areas.sh b/internal/tools/scripts/update-issue-template-areas.sh
new file mode 100755
index 0000000000..1e7c7cb276
--- /dev/null
+++ b/internal/tools/scripts/update-issue-template-areas.sh
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+#
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+#
+# Create labels for all semantic convention areas that are in model/registry.
+# Existing labels are not affected.
+#
+# Note that there is a 50-character limit on labels, so some areas may
+# not have a corresponding label.
+
+set -euo pipefail
+
+CUR_DIRECTORY=$(dirname "$0")
+REPO_DIR="$( cd "$CUR_DIRECTORY/../../../" && pwd )"
+GITHUB_DIR="$( cd "$REPO_DIR/.github/" && pwd )"
+TEMPLATES_DIR="$( cd "$GITHUB_DIR/ISSUE_TEMPLATE" && pwd )"
+
+AREAS=$(sh "${GITHUB_DIR}/workflows/scripts/get-registry-areas.sh")
+
+START_AREA_LIST="# Start semconv area list"
+END_AREA_LIST="# End semconv area list"
+
+replacement="        ${START_AREA_LIST}"
+
+for AREA in ${AREAS}; do
+    LABEL_NAME=$(basename "${AREA}" .yaml)
+   replacement="${replacement}\n        - area:${LABEL_NAME}"
+done
+
+echo -e "\nStarting to replace areas in ISSUE_TEMPLATES:"
+echo -e "---------------------------------------------\n"
+
+replacement="${replacement}\n        ${END_AREA_LIST}"
+
+echo -e "The replacement text will be:"
+echo -e "---------------------------------------------\n"
+echo -e $replacement
+
+find ${TEMPLATES_DIR} -type f -name '*.yaml' -exec sed -i "/$START_AREA_LIST/,/$END_AREA_LIST/c\\$replacement" {} \;
+
+echo -e "\nISSUE_TEMPLATES updated successfully"
+echo -e "---------------------------------------------"

From 80a2d1a8f70c96c51e541827c7548ba42bb77876 Mon Sep 17 00:00:00 2001
From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Date: Tue, 19 Mar 2024 16:09:49 +0100
Subject: [PATCH 02/18] [chore] Enable creating area labels on push to `main`
 (#824)

---
 .github/workflows/scripts/generate-registry-area-labels.sh | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/.github/workflows/scripts/generate-registry-area-labels.sh b/.github/workflows/scripts/generate-registry-area-labels.sh
index bd45812bc5..e06082e982 100755
--- a/.github/workflows/scripts/generate-registry-area-labels.sh
+++ b/.github/workflows/scripts/generate-registry-area-labels.sh
@@ -25,8 +25,7 @@ for AREA in ${AREAS}; do
         continue
     fi
     echo "area:${LABEL_NAME}"
-
-    #  gh label create "area:${LABEL_NAME}" -c "#425cc7"
+    gh label create "area:${LABEL_NAME}" -c "#425cc7"
 done
 
 echo -e "\nLabels created successfully"

From f94edec229a665ff99014f579d33f15b8cda10d7 Mon Sep 17 00:00:00 2001
From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Date: Fri, 22 Mar 2024 02:37:47 +0100
Subject: [PATCH 03/18] [chore] Move metric requirement levels doc from spec
 (#831)

Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>
---
 docs/database/database-metrics.md        |  4 +--
 docs/faas/faas-metrics.md                |  2 +-
 docs/general/metric-requirement-level.md | 43 ++++++++++++++++++++++++
 docs/messaging/messaging-metrics.md      |  6 ++--
 docs/rpc/rpc-metrics.md                  |  2 +-
 docs/runtime/jvm-metrics.md              |  4 +--
 docs/system/process-metrics.md           |  2 +-
 docs/system/system-metrics.md            |  4 +--
 model/README.md                          |  2 +-
 9 files changed, 56 insertions(+), 13 deletions(-)
 create mode 100644 docs/general/metric-requirement-level.md

diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md
index cd476652e0..f7bedea83d 100644
--- a/docs/database/database-metrics.md
+++ b/docs/database/database-metrics.md
@@ -191,5 +191,5 @@ This metric is [recommended][MetricRecommended].
 <!-- endsemconv -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
-[MetricRequired]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#required
-[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#recommended
+[MetricRequired]: /docs/general/metric-requirement-level.md#required
+[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
diff --git a/docs/faas/faas-metrics.md b/docs/faas/faas-metrics.md
index 22dbc92556..9ecf509df3 100644
--- a/docs/faas/faas-metrics.md
+++ b/docs/faas/faas-metrics.md
@@ -301,4 +301,4 @@ FaaS providers. This list is not exhaustive.
 * [OpenFaas Metrics](https://docs.openfaas.com/architecture/metrics/)
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
-[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#recommended
+[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
diff --git a/docs/general/metric-requirement-level.md b/docs/general/metric-requirement-level.md
new file mode 100644
index 0000000000..e9de297124
--- /dev/null
+++ b/docs/general/metric-requirement-level.md
@@ -0,0 +1,43 @@
+# Metric Requirement Levels
+
+**Status**: [Stable][DocumentStatus]
+
+<details>
+<summary>Table of Contents</summary>
+
+<!-- toc -->
+
+- [Required](#required)
+- [Recommended](#recommended)
+- [Opt-In](#opt-in)
+
+<!-- tocstop -->
+
+</details>
+
+The following metric requirement levels are specified:
+
+- [Required](#required)
+- [Recommended](#recommended)
+- [Opt-In](#opt-in)
+
+## Required
+
+All instrumentations MUST emit the metric.
+A semantic convention defining a Required metric expects that an absolute majority of instrumentation libraries and applications are able to efficiently emit it.
+
+## Recommended
+
+Instrumentations SHOULD emit the metric by default if it's readily available and can be efficiently emitted. Instrumentations MAY offer a configuration option to disable Recommended metrics.
+
+Instrumentations that decide not to emit `Recommended` metrics due to performance, security, privacy, or other consideration by default, SHOULD allow for opting in to emitting them as defined for the `Opt-In` requirement level if the metrics are logically applicable.
+
+## Opt-In
+
+Instrumentations SHOULD emit the metric if and only if the user configures the instrumentation to do so.
+Instrumentation that doesn't support configuration MUST NOT emit `Opt-In` metrics.
+
+This attribute requirement level is recommended for metrics that are particularly expensive to retrieve or might pose a security or privacy risk. These should therefore only be enabled deliberately by a user making an informed decision.
+
+[DocumentStatus]:
+  https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md
index f650cfd9bf..7f4cf40ddd 100644
--- a/docs/messaging/messaging-metrics.md
+++ b/docs/messaging/messaging-metrics.md
@@ -187,6 +187,6 @@ _Note: The need to report `messaging.process.messages` depends on the messaging
 <!-- endsemconv -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md
-[MetricRequired]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/metrics/metric-requirement-level.md#required
-[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/metrics/metric-requirement-level.md#recommended
-[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/metrics/metric-requirement-level.md#opt-in
+[MetricRequired]: /docs/general/metric-requirement-level.md#required
+[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
+[MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in
diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md
index 693653d92e..ff162640e3 100644
--- a/docs/rpc/rpc-metrics.md
+++ b/docs/rpc/rpc-metrics.md
@@ -289,4 +289,4 @@ More specific Semantic Conventions are defined for the following RPC technologie
 * [JSON-RPC](json-rpc.md): Semantic Conventions for *JSON-RPC*.
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
-[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#recommended
+[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md
index 3d27e0a24a..7d2d27d148 100644
--- a/docs/runtime/jvm-metrics.md
+++ b/docs/runtime/jvm-metrics.md
@@ -455,5 +455,5 @@ This metric is obtained from [`BufferPoolMXBean#getCount()`](https://docs.oracle
 <!-- endsemconv -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
-[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#opt-in
-[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#recommended
+[MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in
+[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md
index 31b1367200..3feb662a15 100644
--- a/docs/system/process-metrics.md
+++ b/docs/system/process-metrics.md
@@ -238,4 +238,4 @@ This metric is [recommended][MetricRecommended].
 <!-- endsemconv -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
-[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#recommended
+[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md
index ebb3bf3c3a..7bc0a81a2c 100644
--- a/docs/system/system-metrics.md
+++ b/docs/system/system-metrics.md
@@ -795,8 +795,8 @@ An instrument for load average over 1 minute on Linux could be named
 an `{os}` prefix to split this metric across OSes.
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
-[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#recommended
-[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.26.0/specification/metrics/metric-requirement-level.md#opt-in
+[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
+[MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in
 
 ### Metric: `system.linux.memory.available`
 
diff --git a/model/README.md b/model/README.md
index 2fc6f39b35..f5968affd5 100644
--- a/model/README.md
+++ b/model/README.md
@@ -12,7 +12,7 @@ the generated markdown output in the [docs](../docs/README.md) folder.
 Semantic conventions for the spec MUST adhere to the
 [attribute naming](../docs/general/attribute-naming.md),
 [attribute requirement level](../docs/general/attribute-requirement-level.md),
-and [metric requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md) conventions.
+and [metric requirement level](../docs/general/metric-requirement-level.md) conventions.
 
 Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.23.0/semantic-conventions/syntax.md)
 for how to write the YAML files for semantic conventions and what the YAML properties mean.

From 25b4932b923dadd618121f24bee8f87509fc3ad5 Mon Sep 17 00:00:00 2001
From: Liudmila Molkova <limolkova@microsoft.com>
Date: Fri, 22 Mar 2024 08:23:04 -0700
Subject: [PATCH 04/18] [chore] Mark dotnet-specific metrics and attributes
 stable in yaml to match markdown (#819)

Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
---
 docs/dotnet/dotnet-aspnetcore-metrics.md    | 26 ++++++++++-----------
 docs/dotnet/dotnet-kestrel-metrics.md       | 12 +++++-----
 docs/dotnet/dotnet-signalr-metrics.md       |  8 +++----
 model/metrics/dotnet/dotnet-aspnetcore.yaml | 14 +++++++++++
 model/metrics/dotnet/dotnet-kestrel.yaml    | 10 ++++++++
 model/metrics/dotnet/dotnet-signalr.yaml    |  4 ++++
 6 files changed, 51 insertions(+), 23 deletions(-)

diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md
index b09a34d8b8..54b8fc04a0 100644
--- a/docs/dotnet/dotnet-aspnetcore-metrics.md
+++ b/docs/dotnet/dotnet-aspnetcore-metrics.md
@@ -43,9 +43,9 @@ All routing metrics are reported by the `Microsoft.AspNetCore.Routing` meter.
 <!-- semconv metric.aspnetcore.routing.match_attempts(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `aspnetcore.routing.is_fallback` | boolean | A value that indicates whether the matched route is a fallback route. | `True` | Conditionally Required: if and only if a route was successfully matched. |
-| `aspnetcore.routing.match_status` | string | Match result - success or failure | `success`; `failure` | Required |
-| [`http.route`](../attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: if and only if a route was successfully matched. |
+| `aspnetcore.routing.is_fallback` | boolean | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>A value that indicates whether the matched route is a fallback route. | `True` | Conditionally Required: if and only if a route was successfully matched. |
+| `aspnetcore.routing.match_status` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Match result - success or failure | `success`; `failure` | Required |
+| [`http.route`](../attributes-registry/http.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>The matched route, that is, the path template in the format used by the respective server framework. [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: if and only if a route was successfully matched. |
 
 **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
 SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
@@ -75,9 +75,9 @@ Exceptions Metric is reported by the `Microsoft.AspNetCore.Diagnostics` meter.
 <!-- semconv metric.aspnetcore.diagnostics.exceptions(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `aspnetcore.diagnostics.exception.result` | string | ASP.NET Core exception middleware handling result | `handled`; `unhandled` | Required |
-| `aspnetcore.diagnostics.handler.type` | string | Full type name of the [`IExceptionHandler`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.diagnostics.iexceptionhandler) implementation that handled the exception. | `Contoso.MyHandler` | Conditionally Required: [1] |
-| [`error.type`](../attributes-registry/error.md) | string | The full name of exception type. [2] | `System.OperationCanceledException`; `Contoso.MyException` | Required |
+| `aspnetcore.diagnostics.exception.result` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>ASP.NET Core exception middleware handling result | `handled`; `unhandled` | Required |
+| `aspnetcore.diagnostics.handler.type` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Full type name of the [`IExceptionHandler`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.diagnostics.iexceptionhandler) implementation that handled the exception. | `Contoso.MyHandler` | Conditionally Required: [1] |
+| [`error.type`](../attributes-registry/error.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>The full name of exception type. [2] | `System.OperationCanceledException`; `Contoso.MyException` | Required |
 
 **[1]:** if and only if the exception was handled by this handler.
 
@@ -130,7 +130,7 @@ All rate-limiting metrics are reported by the `Microsoft.AspNetCore.RateLimiting
 <!-- semconv metric.aspnetcore.rate_limiting.active_request_leases(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | Conditionally Required: [1] |
+| `aspnetcore.rate_limiting.policy` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Rate limiting policy name. | `fixed`; `sliding`; `token` | Conditionally Required: [1] |
 
 **[1]:** if the matched endpoint for the request had a rate-limiting policy.
 <!-- endsemconv -->
@@ -152,7 +152,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
 <!-- semconv metric.aspnetcore.rate_limiting.request_lease.duration(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | Conditionally Required: [1] |
+| `aspnetcore.rate_limiting.policy` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Rate limiting policy name. | `fixed`; `sliding`; `token` | Conditionally Required: [1] |
 
 **[1]:** if the matched endpoint for the request had a rate-limiting policy.
 <!-- endsemconv -->
@@ -170,7 +170,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
 <!-- semconv metric.aspnetcore.rate_limiting.queued_requests(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | Conditionally Required: [1] |
+| `aspnetcore.rate_limiting.policy` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Rate limiting policy name. | `fixed`; `sliding`; `token` | Conditionally Required: [1] |
 
 **[1]:** if the matched endpoint for the request had a rate-limiting policy.
 <!-- endsemconv -->
@@ -192,8 +192,8 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
 <!-- semconv metric.aspnetcore.rate_limiting.request.time_in_queue(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | Conditionally Required: [1] |
-| `aspnetcore.rate_limiting.result` | string | Rate-limiting result, shows whether the lease was acquired or contains a rejection reason | `acquired`; `request_canceled` | Required |
+| `aspnetcore.rate_limiting.policy` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Rate limiting policy name. | `fixed`; `sliding`; `token` | Conditionally Required: [1] |
+| `aspnetcore.rate_limiting.result` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Rate-limiting result, shows whether the lease was acquired or contains a rejection reason | `acquired`; `request_canceled` | Required |
 
 **[1]:** if the matched endpoint for the request had a rate-limiting policy.
 
@@ -225,8 +225,8 @@ Meter name: `Microsoft.AspNetCore.RateLimiting`; Added in: ASP.NET Core 8.0
 <!-- semconv metric.aspnetcore.rate_limiting.requests(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | Conditionally Required: [1] |
-| `aspnetcore.rate_limiting.result` | string | Rate-limiting result, shows whether the lease was acquired or contains a rejection reason | `acquired`; `request_canceled` | Required |
+| `aspnetcore.rate_limiting.policy` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Rate limiting policy name. | `fixed`; `sliding`; `token` | Conditionally Required: [1] |
+| `aspnetcore.rate_limiting.result` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Rate-limiting result, shows whether the lease was acquired or contains a rejection reason | `acquired`; `request_canceled` | Required |
 
 **[1]:** if the matched endpoint for the request had a rate-limiting policy.
 
diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md
index 96f400ab19..81ea6e79a4 100644
--- a/docs/dotnet/dotnet-kestrel-metrics.md
+++ b/docs/dotnet/dotnet-kestrel-metrics.md
@@ -94,9 +94,9 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
 <!-- semconv metric.kestrel.connection.duration(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| [`error.type`](../attributes-registry/error.md) | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an error has occurred. |
-| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [2] | `http`; `web_sockets` | Recommended |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [3] | `1.1`; `2` | Recommended |
+| [`error.type`](../attributes-registry/error.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an error has occurred. |
+| [`network.protocol.name`](../attributes-registry/network.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [2] | `http`; `web_sockets` | Recommended |
+| [`network.protocol.version`](../attributes-registry/network.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Version of the protocol specified in `network.protocol.name`. [3] | `1.1`; `2` | Recommended |
 | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [4] | `tcp`; `unix` | Recommended |
 | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [5] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` |
 | [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended |
@@ -252,8 +252,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
 <!-- semconv metric.kestrel.queued_requests(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [1] | `http`; `web_sockets` | Recommended |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended |
+| [`network.protocol.name`](../attributes-registry/network.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [1] | `http`; `web_sockets` | Recommended |
+| [`network.protocol.version`](../attributes-registry/network.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended |
 | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `unix` | Recommended |
 | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` |
 | [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended |
@@ -358,7 +358,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
 <!-- semconv metric.kestrel.tls_handshake.duration(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| [`error.type`](../attributes-registry/error.md) | string | The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an error has occurred. |
+| [`error.type`](../attributes-registry/error.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an error has occurred. |
 | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [2] | `tcp`; `unix` | Recommended |
 | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [3] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` |
 | [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended |
diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md
index dc2b04ed06..931d5f4bf3 100644
--- a/docs/dotnet/dotnet-signalr-metrics.md
+++ b/docs/dotnet/dotnet-signalr-metrics.md
@@ -32,8 +32,8 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
 <!-- semconv metric.signalr.server.connection.duration(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `signalr.connection.status` | string | SignalR HTTP connection closure status. | `app_shutdown`; `timeout` | Recommended |
-| `signalr.transport` | string | [SignalR transport type](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md) | `web_sockets`; `long_polling` | Recommended |
+| `signalr.connection.status` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>SignalR HTTP connection closure status. | `app_shutdown`; `timeout` | Recommended |
+| `signalr.transport` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>[SignalR transport type](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md) | `web_sockets`; `long_polling` | Recommended |
 
 `signalr.connection.status` MUST be one of the following:
 
@@ -65,8 +65,8 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
 <!-- semconv metric.signalr.server.active_connections(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `signalr.connection.status` | string | SignalR HTTP connection closure status. | `app_shutdown`; `timeout` | Recommended |
-| `signalr.transport` | string | [SignalR transport type](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md) | `web_sockets`; `long_polling` | Recommended |
+| `signalr.connection.status` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>SignalR HTTP connection closure status. | `app_shutdown`; `timeout` | Recommended |
+| `signalr.transport` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>[SignalR transport type](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md) | `web_sockets`; `long_polling` | Recommended |
 
 `signalr.connection.status` MUST be one of the following:
 
diff --git a/model/metrics/dotnet/dotnet-aspnetcore.yaml b/model/metrics/dotnet/dotnet-aspnetcore.yaml
index 8369e068d5..89ce151d2d 100644
--- a/model/metrics/dotnet/dotnet-aspnetcore.yaml
+++ b/model/metrics/dotnet/dotnet-aspnetcore.yaml
@@ -7,6 +7,7 @@ groups:
       - id: rate_limiting.policy
         type: string
         brief: Rate limiting policy name.
+        stability: stable
         examples: ["fixed", "sliding", "token"]
         requirement_level:
           conditionally_required: if the matched endpoint for the request had a rate-limiting policy.
@@ -26,17 +27,20 @@ groups:
             - id: request_canceled
               value: 'request_canceled'
               brief: "Lease request was canceled"
+        stability: stable
         brief: Rate-limiting result, shows whether the lease was acquired or contains a rejection reason
         examples: ["acquired", "request_canceled"]
         requirement_level: required
       - id: routing.is_fallback
         type: boolean
+        stability: stable
         brief: A value that indicates whether the matched route is a fallback route.
         examples: [true]
         requirement_level:
           conditionally_required: If and only if a route was successfully matched.
       - id: diagnostics.handler.type
         type: string
+        stability: stable
         brief: Full type name of the [`IExceptionHandler`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.diagnostics.iexceptionhandler)
           implementation that handled the exception.
         examples: ["Contoso.MyHandler"]
@@ -44,6 +48,7 @@ groups:
           conditionally_required: if and only if the exception was handled by this handler.
       - id: request.is_unhandled
         type: boolean
+        stability: stable
         brief: Flag indicating if request was handled by the application pipeline.
         examples: [true]
         requirement_level:
@@ -53,6 +58,7 @@ groups:
   - id: metric.aspnetcore.routing.match_attempts
     type: metric
     metric_name: aspnetcore.routing.match_attempts
+    stability: stable
     brief: Number of requests that were attempted to be matched to an endpoint.
     instrument: counter
     unit: "{match_attempt}"
@@ -75,6 +81,7 @@ groups:
             - id: failure
               value: 'failure'
               brief: 'Match failed'
+        stability: stable
         requirement_level: required
         brief: Match result - success or failure
         examples: ["success", "failure"]
@@ -83,6 +90,7 @@ groups:
   - id: metric.aspnetcore.diagnostics.exceptions
     type: metric
     metric_name: aspnetcore.diagnostics.exceptions
+    stability: stable
     brief: Number of exceptions caught by exception handling middleware.
     instrument: counter
     unit: "{exception}"
@@ -109,6 +117,7 @@ groups:
             - id: aborted
               value: 'aborted'
               brief: "Exception handling didn't run because the request was aborted."
+        stability: stable
         requirement_level: required
         brief: ASP.NET Core exception middleware handling result
         examples: ["handled", "unhandled"]
@@ -117,6 +126,7 @@ groups:
   - id: metric.aspnetcore.rate_limiting.active_request_leases
     type: metric
     metric_name: aspnetcore.rate_limiting.active_request_leases
+    stability: stable
     brief: Number of requests that are currently active on the server that hold a rate limiting lease.
     instrument: updowncounter
     unit: "{request}"
@@ -128,6 +138,7 @@ groups:
   - id: metric.aspnetcore.rate_limiting.request_lease.duration
     type: metric
     metric_name: aspnetcore.rate_limiting.request_lease.duration
+    stability: stable
     brief: The duration of rate limiting lease held by requests on the server.
     instrument: histogram
     unit: "s"
@@ -139,6 +150,7 @@ groups:
   - id: metric.aspnetcore.rate_limiting.request.time_in_queue
     type: metric
     metric_name: aspnetcore.rate_limiting.request.time_in_queue
+    stability: stable
     brief: The time the request spent in a queue waiting to acquire a rate limiting lease.
     instrument: histogram
     unit: "s"
@@ -151,6 +163,7 @@ groups:
   - id: metric.aspnetcore.rate_limiting.queued_requests
     type: metric
     metric_name: aspnetcore.rate_limiting.queued_requests
+    stability: stable
     brief: Number of requests that are currently queued, waiting to acquire a rate limiting lease.
     instrument: updowncounter
     unit: "{request}"
@@ -162,6 +175,7 @@ groups:
   - id: metric.aspnetcore.rate_limiting.requests
     type: metric
     metric_name: aspnetcore.rate_limiting.requests
+    stability: stable
     brief: Number of requests that tried to acquire a rate limiting lease.
     instrument: counter
     unit: "{request}"
diff --git a/model/metrics/dotnet/dotnet-kestrel.yaml b/model/metrics/dotnet/dotnet-kestrel.yaml
index e04714a9b5..9a4a231f51 100644
--- a/model/metrics/dotnet/dotnet-kestrel.yaml
+++ b/model/metrics/dotnet/dotnet-kestrel.yaml
@@ -14,6 +14,7 @@ groups:
   - id: metric.kestrel.active_connections
     type: metric
     metric_name: kestrel.active_connections
+    stability: stable
     brief: Number of connections that are currently active on the server.
     instrument: updowncounter
     unit: "{connection}"
@@ -24,6 +25,7 @@ groups:
   - id: metric.kestrel.connection.duration
     type: metric
     metric_name: kestrel.connection.duration
+    stability: stable
     brief: The duration of connections on the server.
     instrument: histogram
     unit: "s"
@@ -36,6 +38,7 @@ groups:
       - ref: network.protocol.version
         examples: ["1.1", "2"]
       - ref: tls.protocol.version
+        stability: experimental
       - ref: error.type
         brief: The full name of exception type.
         requirement_level:
@@ -46,6 +49,7 @@ groups:
   - id: metric.kestrel.rejected_connections
     type: metric
     metric_name: kestrel.rejected_connections
+    stability: stable
     brief: Number of connections rejected by the server.
     instrument: counter
     unit: "{connection}"
@@ -57,6 +61,7 @@ groups:
   - id: metric.kestrel.queued_connections
     type: metric
     metric_name: kestrel.queued_connections
+    stability: stable
     brief: Number of connections that are currently queued and are waiting to start.
     instrument: updowncounter
     unit: "{connection}"
@@ -67,6 +72,7 @@ groups:
   - id: metric.kestrel.queued_requests
     type: metric
     metric_name: kestrel.queued_requests
+    stability: stable
     brief: Number of HTTP requests on multiplexed connections (HTTP/2 and HTTP/3) that are currently queued and are waiting to start.
     instrument: updowncounter
     unit: "{request}"
@@ -82,6 +88,7 @@ groups:
   - id: metric.kestrel.upgraded_connections
     type: metric
     metric_name: kestrel.upgraded_connections
+    stability: stable
     brief: Number of connections that are currently upgraded (WebSockets). .
     instrument: updowncounter
     unit: "{connection}"
@@ -94,6 +101,7 @@ groups:
   - id: metric.kestrel.tls_handshake.duration
     type: metric
     metric_name: kestrel.tls_handshake.duration
+    stability: stable
     brief: The duration of TLS handshakes on the server.
     instrument: histogram
     unit: "s"
@@ -102,6 +110,7 @@ groups:
     extends: common.kestrel.attributes
     attributes:
       - ref: tls.protocol.version
+        stability: experimental
       - ref: error.type
         brief: The full name of exception type.
         note: "Captures the exception type when a TLS handshake fails."
@@ -112,6 +121,7 @@ groups:
   - id: metric.kestrel.active_tls_handshakes
     type: metric
     metric_name: kestrel.active_tls_handshakes
+    stability: stable
     brief: Number of TLS handshakes that are currently in progress on the server.
     instrument: updowncounter
     unit: "{handshake}"
diff --git a/model/metrics/dotnet/dotnet-signalr.yaml b/model/metrics/dotnet/dotnet-signalr.yaml
index 3333669c57..b47ebf6908 100644
--- a/model/metrics/dotnet/dotnet-signalr.yaml
+++ b/model/metrics/dotnet/dotnet-signalr.yaml
@@ -16,6 +16,7 @@ groups:
             - id: app_shutdown
               value: 'app_shutdown'
               brief: "The connection was closed because the app is shutting down."
+        stability: stable
         brief: SignalR HTTP connection closure status.
         examples: ["app_shutdown", "timeout"]
       - id: transport
@@ -32,11 +33,13 @@ groups:
             - id: web_sockets
               value: 'web_sockets'
               brief: "WebSockets protocol"
+        stability: stable
         examples: ["web_sockets", "long_polling"]
 
   - id: metric.signalr.server.connection.duration
     type: metric
     metric_name: signalr.server.connection.duration
+    stability: stable
     brief: The duration of connections on the server.
     instrument: histogram
     unit: "s"
@@ -49,6 +52,7 @@ groups:
   - id: metric.signalr.server.active_connections
     type: metric
     metric_name: signalr.server.active_connections
+    stability: stable
     brief: Number of connections that are currently active on the server.
     instrument: updowncounter
     unit: "{connection}"

From e01cafdcbe4828407945dde718af94c664b69fec Mon Sep 17 00:00:00 2001
From: Liudmila Molkova <limolkova@microsoft.com>
Date: Mon, 25 Mar 2024 08:39:18 -0700
Subject: [PATCH 05/18] Messaging: clarify network attributes usage on common
 semconv  (#698)

Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
---
 .chloggen/698.yaml                  |  7 +++
 docs/messaging/gcp-pubsub.md        |  4 +-
 docs/messaging/kafka.md             |  2 +-
 docs/messaging/messaging-metrics.md | 16 ++-----
 docs/messaging/messaging-spans.md   | 58 ++++---------------------
 docs/messaging/rabbitmq.md          |  6 ++-
 docs/messaging/rocketmq.md          |  2 +-
 model/messaging-common.yaml         |  7 +--
 model/trace/messaging.yaml          | 67 +++++++++++++++++++----------
 9 files changed, 75 insertions(+), 94 deletions(-)
 create mode 100644 .chloggen/698.yaml

diff --git a/.chloggen/698.yaml b/.chloggen/698.yaml
new file mode 100644
index 0000000000..c12d9d9f2d
--- /dev/null
+++ b/.chloggen/698.yaml
@@ -0,0 +1,7 @@
+change_type: breaking
+
+component: messaging
+
+note: Remove `network.transport` and `network.type` attributes from messaging semantic conventions, clarify when `network.peer.address|port` should be populated.
+
+issues: [690, 698]
diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md
index 95acf97d64..17b74081a9 100644
--- a/docs/messaging/gcp-pubsub.md
+++ b/docs/messaging/gcp-pubsub.md
@@ -13,7 +13,7 @@ The Semantic Conventions for [Google Cloud Pub/Sub](https://cloud.google.com/pub
 ## Span attributes
 
 For Google Cloud Pub/Sub, the following additional attributes are defined:
-<!-- semconv messaging.gcp_pubsub(full,tag=tech-specific-gcp-pubsub) -->
+<!-- semconv messaging.gcp_pubsub(full,tag=tech-specific) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | [`messaging.gcp_pubsub.message.ordering_key`](../attributes-registry/messaging.md) | string | The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. | `ordering_key` | Conditionally Required: If the message type has an ordering key set. |
@@ -31,7 +31,7 @@ flowchart LR;
   direction LR
   CA[Span Create A]
   CB[Span Create B]
-  P[Span Publish A B] 
+  P[Span Publish A B]
   end
   CA-. link .-P;
   CB-. link .-P;
diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md
index 4f6866ed83..522c4c2a16 100644
--- a/docs/messaging/kafka.md
+++ b/docs/messaging/kafka.md
@@ -24,7 +24,7 @@ described on this page.
 
 For Apache Kafka, the following additional attributes are defined:
 
-<!-- semconv messaging.kafka(full,tag=tech-specific-kafka) -->
+<!-- semconv messaging.kafka(full,tag=tech-specific) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | [`messaging.destination.partition.id`](../attributes-registry/messaging.md) | string | "String representation of the partition id the message  (or batch) is sent to or received from."" | `1` | Recommended |
diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md
index 7f4cf40ddd..4f2678243c 100644
--- a/docs/messaging/messaging-metrics.md
+++ b/docs/messaging/messaging-metrics.md
@@ -36,10 +36,8 @@ All messaging metrics share the same set of attributes:
 | [`messaging.destination.name`](../attributes-registry/messaging.md) | string | The message destination name [3] | `MyQueue`; `MyTopic` | Conditionally Required: [4] |
 | [`messaging.destination.template`](../attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [5] | `/customers/{customerId}` | Conditionally Required: if available. |
 | [`messaging.system`](../attributes-registry/messaging.md) | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` | Required |
-| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [6] | `amqp`; `mqtt` | Conditionally Required: [7] |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [8] | `3.1.1` | Recommended |
-| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. |
-| [`server.port`](../attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | Recommended |
+| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. |
+| [`server.port`](../attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | Recommended |
 
 **[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality.
 Instrumentations SHOULD document the list of errors they report.
@@ -66,15 +64,9 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi
 
 **[5]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation.
 
-**[6]:** The value SHOULD be normalized to lowercase.
+**[6]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
 
-**[7]:** Only for messaging systems and frameworks that support more than one protocol.
-
-**[8]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
-
-**[9]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from.
-
-**[10]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[7]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
 
 `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
 
diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md
index 7cff828c2c..f78ad5993c 100644
--- a/docs/messaging/messaging-spans.md
+++ b/docs/messaging/messaging-spans.md
@@ -275,8 +275,6 @@ Messaging attributes are organized into the following namespaces:
 - `messaging.batch`: Contains attributes that describe batch operations.
 - `messaging.consumer`: Contains [consumer attributes](#consumer-attributes) that describe the application instance that consumes a message. See [consumer](#consumer) for more details.
 
-The communication with the intermediary is described with general [network attributes].
-
 Messaging system-specific attributes MUST be defined in the corresponding `messaging.{system}` namespace
 as described in [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems).
 
@@ -296,14 +294,10 @@ as described in [Attributes specific to certain messaging systems](#attributes-s
 | [`messaging.message.id`](../attributes-registry/messaging.md) | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended |
 | [`messaging.operation`](../attributes-registry/messaging.md) | string | A string identifying the kind of messaging operation. [13] | `publish` | Required |
 | [`messaging.system`](../attributes-registry/messaging.md) | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` | Required |
-| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended |
-| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. |
-| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [14] | `amqp`; `mqtt` | Conditionally Required: [15] |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [16] | `3.1.1` | Recommended |
-| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [17] | `tcp`; `udp` | Recommended |
-| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [18] | `ipv4`; `ipv6` | Recommended |
-| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [19] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. |
-| [`server.port`](../attributes-registry/server.md) | int | Server port number. [20] | `80`; `8080`; `443` | Recommended |
+| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the messaging intermediary node where the operation was performed. [14] | `10.1.2.80`; `/tmp/my.sock` | Recommended: If applicable for this messaging system. |
+| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port of the messaging intermediary node where the operation was performed. | `65123` | Recommended: if and only if `network.peer.address` is set. |
+| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. |
+| [`server.port`](../attributes-registry/server.md) | int | Server port number. [16] | `80`; `8080`; `443` | Recommended |
 
 **[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality.
 Instrumentations SHOULD document the list of errors they report.
@@ -348,23 +342,13 @@ size should be used.
 
 **[13]:** If a custom value is used, it MUST be of low cardinality.
 
-**[14]:** The value SHOULD be normalized to lowercase.
-
-**[15]:** Only for messaging systems and frameworks that support more than one protocol.
-
-**[16]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
-
-**[17]:** The value SHOULD be normalized to lowercase.
+**[14]:** Semantic conventions for individual messaging systems SHOULD document whether `network.peer.*` attributes are applicable.
+Network peer address and port are important when the application interacts with individual intermediary nodes directly,
+If a messaging operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
 
-Consider always setting the transport when setting a port number, since
-a port number is ambiguous without knowing the transport. For example
-different processes could be listening on TCP port 12345 and UDP port 12345.
+**[15]:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
 
-**[18]:** The value SHOULD be normalized to lowercase.
-
-**[19]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from.
-
-**[20]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[16]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
 
 `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
 
@@ -396,32 +380,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
 | `kafka` | Apache Kafka |
 | `rabbitmq` | RabbitMQ |
 | `rocketmq` | Apache RocketMQ |
-
-`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
-
-| Value  | Description |
-|---|---|
-| `tcp` | TCP |
-| `udp` | UDP |
-| `pipe` | Named or anonymous pipe. |
-| `unix` | Unix domain socket |
-
-`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
-
-| Value  | Description |
-|---|---|
-| `ipv4` | IPv4 |
-| `ipv6` | IPv6 |
 <!-- endsemconv -->
 
-Additionally `server.port` from the [network attributes][] is recommended.
-Furthermore, it is strongly recommended to add the [`network.transport`][] attribute and follow its guidelines, especially for in-process queueing systems (like [Hangfire][], for example).
-These attributes should be set to the broker to which the message is sent/from which it is received.
-
-[network attributes]: /docs/general/attributes.md#server-and-client-attributes
-[`network.transport`]: /docs/general/attributes.md#network-attributes
-[Hangfire]: https://www.hangfire.io/
-
 ### Consumer attributes
 
 The following additional attributes describe message consumer operations.
diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md
index 1c8f2ec8cc..7852546f4d 100644
--- a/docs/messaging/rabbitmq.md
+++ b/docs/messaging/rabbitmq.md
@@ -17,11 +17,15 @@ described on this page.
 In RabbitMQ, the destination is defined by an *exchange* and a *routing key*.
 `messaging.destination.name` MUST be set to the name of the exchange. This will be an empty string if the default exchange is used.
 
-<!-- semconv messaging.rabbitmq(full,tag=tech-specific-rabbitmq) -->
+<!-- semconv messaging.rabbitmq(full,tag=tech-specific) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | [`messaging.rabbitmq.destination.routing_key`](../attributes-registry/messaging.md) | string | RabbitMQ message routing key. | `myKey` | Conditionally Required: If not empty. |
 | [`messaging.rabbitmq.message.delivery_tag`](../attributes-registry/messaging.md) | int | RabbitMQ message delivery tag | `123` | Conditionally Required: When available. |
+| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the messaging intermediary node where the operation was performed. [1] | `10.1.2.80`; `/tmp/my.sock` | Recommended |
+| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port of the messaging intermediary node where the operation was performed. | `65123` | Recommended |
+
+**[1]:** If an operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
 <!-- endsemconv -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
diff --git a/docs/messaging/rocketmq.md b/docs/messaging/rocketmq.md
index 8f4bbca5fb..eb0d8b3d5d 100644
--- a/docs/messaging/rocketmq.md
+++ b/docs/messaging/rocketmq.md
@@ -16,7 +16,7 @@ described on this page.
 
 Specific attributes for Apache RocketMQ are defined below.
 
-<!-- semconv messaging.rocketmq(full,tag=tech-specific-rocketmq) -->
+<!-- semconv messaging.rocketmq(full,tag=tech-specific) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | [`messaging.rocketmq.client_group`](../attributes-registry/messaging.md) | string | Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. | `myConsumerGroup` | Required |
diff --git a/model/messaging-common.yaml b/model/messaging-common.yaml
index f5505a0baf..35d6a8eefb 100644
--- a/model/messaging-common.yaml
+++ b/model/messaging-common.yaml
@@ -12,12 +12,7 @@ groups:
           conditionally_required: If and only if the messaging operation has failed.
       - ref: server.address
         note: >
-          This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from.
+          Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.
         requirement_level:
           conditionally_required: If available.
       - ref: server.port
-      - ref: network.protocol.name
-        examples: ['amqp', 'mqtt']
-        requirement_level:
-          conditionally_required: Only for messaging systems and frameworks that support more than one protocol.
-      - ref: network.protocol.version
diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml
index 362eaab9f4..75410d34de 100644
--- a/model/trace/messaging.yaml
+++ b/model/trace/messaging.yaml
@@ -80,28 +80,51 @@ groups:
       - ref: messaging.message.conversation_id
       - ref: messaging.message.envelope.size
       - ref: messaging.message.body.size
-      - ref: server.address
       - ref: network.peer.address
+        brief: Peer address of the messaging intermediary node where the operation was performed.
+        requirement_level:
+          recommended: If applicable for this messaging system.
+        note: >
+          Semantic conventions for individual messaging systems SHOULD document whether `network.peer.*` attributes are applicable.
+
+          Network peer address and port are important when the application interacts with individual intermediary nodes directly,
+
+          If a messaging operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
       - ref: network.peer.port
+        brief: Peer port of the messaging intermediary node where the operation was performed.
         requirement_level:
-          recommended: If `network.peer.address` is set.
-      - ref: network.transport
-      - ref: network.type
+          recommended: if and only if `network.peer.address` is set.
 
-  - id: messaging.rabbitmq
+  - id: messaging.tech_specific.network.attributes
     type: attribute_group
+    brief: Attributes that describe messaging operation along with network information.
     extends: messaging
+    attributes:
+      - ref: network.peer.address
+        requirement_level: recommended
+        note: >
+          If an operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
+      - ref: network.peer.port
+        requirement_level: recommended
+
+  - id: messaging.rabbitmq
+    type: attribute_group
+    extends: messaging.tech_specific.network.attributes
     brief: >
       Attributes for RabbitMQ
     attributes:
       - ref: messaging.rabbitmq.destination.routing_key
         requirement_level:
           conditionally_required: If not empty.
-        tag: tech-specific-rabbitmq
+        tag: tech-specific
       - ref: messaging.rabbitmq.message.delivery_tag
         requirement_level:
           conditionally_required: When available.
-        tag: tech-specific-rabbitmq
+        tag: tech-specific
+      - ref: network.peer.address
+        tag: tech-specific
+      - ref: network.peer.port
+        tag: tech-specific
 
   - id: messaging.kafka
     type: attribute_group
@@ -112,17 +135,17 @@ groups:
       - ref: messaging.destination.partition.id
         brief: >
           "String representation of the partition id the message  (or batch) is sent to or received from.""
-        tag: tech-specific-kafka
+        tag: tech-specific
       - ref: messaging.kafka.message.key
-        tag: tech-specific-kafka
+        tag: tech-specific
       - ref: messaging.kafka.consumer.group
-        tag: tech-specific-kafka
+        tag: tech-specific
       - ref: messaging.kafka.message.offset
-        tag: tech-specific-kafka
+        tag: tech-specific
       - ref: messaging.kafka.message.tombstone
         requirement_level:
           conditionally_required: If value is `true`. When missing, the value is assumed to be `false`.
-        tag: tech-specific-kafka
+        tag: tech-specific
 
   - id: messaging.rocketmq
     type: attribute_group
@@ -132,30 +155,30 @@ groups:
     attributes:
       - ref: messaging.rocketmq.namespace
         requirement_level: required
-        tag: tech-specific-rocketmq
+        tag: tech-specific
       - ref: messaging.rocketmq.client_group
         requirement_level: required
-        tag: tech-specific-rocketmq
+        tag: tech-specific
       - ref: messaging.rocketmq.message.delivery_timestamp
         requirement_level:
           conditionally_required: If the message type is delay and delay time level is not specified.
-        tag: tech-specific-rocketmq
+        tag: tech-specific
       - ref: messaging.rocketmq.message.delay_time_level
         requirement_level:
           conditionally_required: If the message type is delay and delivery timestamp is not specified.
-        tag: tech-specific-rocketmq
+        tag: tech-specific
       - ref: messaging.rocketmq.message.group
         requirement_level:
           conditionally_required: If the message type is FIFO.
-        tag: tech-specific-rocketmq
+        tag: tech-specific
       - ref: messaging.rocketmq.message.type
-        tag: tech-specific-rocketmq
+        tag: tech-specific
       - ref: messaging.rocketmq.message.tag
-        tag: tech-specific-rocketmq
+        tag: tech-specific
       - ref: messaging.rocketmq.message.keys
-        tag: tech-specific-rocketmq
+        tag: tech-specific
       - ref: messaging.rocketmq.consumption_model
-        tag: tech-specific-rocketmq
+        tag: tech-specific
   - id: messaging.gcp_pubsub
     type: attribute_group
     extends: messaging
@@ -163,7 +186,7 @@ groups:
       Attributes for Google Cloud Pub/Sub
     attributes:
       - ref: messaging.gcp_pubsub.message.ordering_key
-        tag: tech-specific-gcp-pubsub
+        tag: tech-specific
         requirement_level:
           conditionally_required: If the message type has an ordering key set.
   - id: messaging.servicebus

From 83119ef0d0050a55353ff48bd3cb6c36dc86bb37 Mon Sep 17 00:00:00 2001
From: Liudmila Molkova <limolkova@microsoft.com>
Date: Mon, 25 Mar 2024 09:44:25 -0700
Subject: [PATCH 06/18] Clarify that `network.protocol.version` represents
 negotiated version (#817)

---
 .chloggen/817.yaml                    |  4 ++++
 docs/attributes-registry/network.md   |  4 ++--
 docs/dotnet/dotnet-http-metrics.md    |  6 ++---
 docs/dotnet/dotnet-kestrel-metrics.md |  8 +++----
 docs/general/attributes.md            |  4 ++--
 docs/http/http-metrics.md             | 32 +++++++++++++--------------
 docs/http/http-spans.md               |  4 ++--
 model/registry/network.yaml           | 10 ++++-----
 8 files changed, 38 insertions(+), 34 deletions(-)
 create mode 100644 .chloggen/817.yaml

diff --git a/.chloggen/817.yaml b/.chloggen/817.yaml
new file mode 100644
index 0000000000..bf56ad5daa
--- /dev/null
+++ b/.chloggen/817.yaml
@@ -0,0 +1,4 @@
+change_type: bug_fix
+component: network
+note: Clarifies that network.protocol.version represents negotiated version
+issues: [ 686 ]
diff --git a/docs/attributes-registry/network.md b/docs/attributes-registry/network.md
index a06417c9dc..b534c86f54 100644
--- a/docs/attributes-registry/network.md
+++ b/docs/attributes-registry/network.md
@@ -22,13 +22,13 @@ These attributes may be used for any network related operation.
 | `network.peer.address` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` |
 | `network.peer.port` | int | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Peer port number of the network connection. | `65123` |
 | `network.protocol.name` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [1] | `amqp`; `http`; `mqtt` |
-| `network.protocol.version` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Version of the protocol specified in `network.protocol.name`. [2] | `3.1.1` |
+| `network.protocol.version` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>The actual version of the protocol used for network communication. [2] | `1.1`; `2` |
 | `network.transport` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` |
 | `network.type` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` |
 
 **[1]:** The value SHOULD be normalized to lowercase.
 
-**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
+**[2]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
 
 **[3]:** The value SHOULD be normalized to lowercase.
 
diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md
index e4e4f7c28c..e59166dd01 100644
--- a/docs/dotnet/dotnet-http-metrics.md
+++ b/docs/dotnet/dotnet-http-metrics.md
@@ -54,7 +54,7 @@ Notes:
 |---|---|---|---|---|
 | `http.connection.state` | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | Required |
 | [`network.peer.address`](../attributes-registry/network.md) | string | Remote IP address of the socket connection. | `10.1.2.80` | Recommended |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | HTTP protocol version of the connection in the connection pool. [1] | `1.1`; `2`; `3` | Recommended |
+| [`network.protocol.version`](../attributes-registry/network.md) | string | The negotiated version of the protocol associated with connection in the connection pool. [1] | `1.1`; `2`; `3` | Recommended |
 | [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required |
 | [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] |
 | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended |
@@ -90,7 +90,7 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | HTTP protocol version of the connection in the connection pool. [1] | `1.1`; `2`; `3` | Recommended |
+| [`network.protocol.version`](../attributes-registry/network.md) | string | The negotiated version of the protocol associated with connection in the connection pool. [1] | `1.1`; `2`; `3` | Recommended |
 | [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required |
 | [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] |
 | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended |
@@ -119,7 +119,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | HTTP protocol version of the connection in the connection pool. [2] | `1.1`; `2`; `3` | Recommended |
+| [`network.protocol.version`](../attributes-registry/network.md) | string | The negotiated version of the protocol associated with connection in the connection pool. [2] | `1.1`; `2`; `3` | Recommended |
 | [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required |
 | [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
 | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended |
diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md
index 81ea6e79a4..a6971f77ef 100644
--- a/docs/dotnet/dotnet-kestrel-metrics.md
+++ b/docs/dotnet/dotnet-kestrel-metrics.md
@@ -96,7 +96,7 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
 |---|---|---|---|---|
 | [`error.type`](../attributes-registry/error.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>The full name of exception type. [1] | `System.OperationCanceledException`; `Contoso.MyException` | Conditionally Required: if and only if an error has occurred. |
 | [`network.protocol.name`](../attributes-registry/network.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [2] | `http`; `web_sockets` | Recommended |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Version of the protocol specified in `network.protocol.name`. [3] | `1.1`; `2` | Recommended |
+| [`network.protocol.version`](../attributes-registry/network.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>The actual version of the protocol used for network communication. [3] | `1.1`; `2` | Recommended |
 | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [4] | `tcp`; `unix` | Recommended |
 | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [5] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` |
 | [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended |
@@ -107,7 +107,7 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
 
 **[2]:** The value SHOULD be normalized to lowercase.
 
-**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
+**[3]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
 
 **[4]:** The value SHOULD be normalized to lowercase.
 
@@ -253,7 +253,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | [`network.protocol.name`](../attributes-registry/network.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [1] | `http`; `web_sockets` | Recommended |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Version of the protocol specified in `network.protocol.name`. [2] | `1.1`; `2` | Recommended |
+| [`network.protocol.version`](../attributes-registry/network.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>The actual version of the protocol used for network communication. [2] | `1.1`; `2` | Recommended |
 | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `unix` | Recommended |
 | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended: if the transport is `tcp` or `udp` |
 | [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended |
@@ -261,7 +261,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
 
 **[1]:** The value SHOULD be normalized to lowercase.
 
-**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
+**[2]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
 
 **[3]:** The value SHOULD be normalized to lowercase.
 
diff --git a/docs/general/attributes.md b/docs/general/attributes.md
index 3ae6cbfdfd..d809f56add 100644
--- a/docs/general/attributes.md
+++ b/docs/general/attributes.md
@@ -164,13 +164,13 @@ if they do not cause breaking changes to HTTP semantic conventions.
 | [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended |
 | [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended |
 | [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [1] | `amqp`; `http`; `mqtt` | Recommended |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `3.1.1` | Recommended |
+| [`network.protocol.version`](../attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [2] | `1.1`; `2` | Recommended |
 | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` | Recommended |
 | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended |
 
 **[1]:** The value SHOULD be normalized to lowercase.
 
-**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
+**[2]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
 
 **[3]:** The value SHOULD be normalized to lowercase.
 
diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md
index dd429a32fb..f6e5d7ec3c 100644
--- a/docs/http/http-metrics.md
+++ b/docs/http/http-metrics.md
@@ -83,7 +83,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
 | [`http.response.status_code`](../attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
 | [`http.route`](../attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
 | [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `http`; `spdy` | Conditionally Required: [5] |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [6] | `1.0`; `1.1`; `2`; `3` | Recommended |
+| [`network.protocol.version`](../attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [6] | `1.0`; `1.1`; `2`; `3` | Recommended |
 | [`server.address`](../attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Opt-In |
 | [`server.port`](../attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [8] | `80`; `8080`; `443` | Opt-In |
 | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. [9] | `http`; `https` | Required |
@@ -127,7 +127,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
 
 **[5]:** If not `http` and `network.protocol.version` is set.
 
-**[6]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
+**[6]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
 
 **[7]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
 > **Warning**
@@ -246,7 +246,7 @@ This metric is optional.
 | [`http.response.status_code`](../attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
 | [`http.route`](../attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
 | [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `http`; `spdy` | Conditionally Required: [5] |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [6] | `1.0`; `1.1`; `2`; `3` | Recommended |
+| [`network.protocol.version`](../attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [6] | `1.0`; `1.1`; `2`; `3` | Recommended |
 | [`server.address`](../attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Opt-In |
 | [`server.port`](../attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [8] | `80`; `8080`; `443` | Opt-In |
 | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. [9] | `http`; `https` | Required |
@@ -290,7 +290,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
 
 **[5]:** If not `http` and `network.protocol.version` is set.
 
-**[6]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
+**[6]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
 
 **[7]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
 > **Warning**
@@ -348,7 +348,7 @@ This metric is optional.
 | [`http.response.status_code`](../attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
 | [`http.route`](../attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
 | [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `http`; `spdy` | Conditionally Required: [5] |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [6] | `1.0`; `1.1`; `2`; `3` | Recommended |
+| [`network.protocol.version`](../attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [6] | `1.0`; `1.1`; `2`; `3` | Recommended |
 | [`server.address`](../attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Opt-In |
 | [`server.port`](../attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [8] | `80`; `8080`; `443` | Opt-In |
 | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. [9] | `http`; `https` | Required |
@@ -392,7 +392,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
 
 **[5]:** If not `http` and `network.protocol.version` is set.
 
-**[6]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
+**[6]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
 
 **[7]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
 > **Warning**
@@ -455,7 +455,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
 | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required |
 | [`http.response.status_code`](../attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
 | [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `http`; `spdy` | Conditionally Required: [4] |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `1.0`; `1.1`; `2`; `3` | Recommended |
+| [`network.protocol.version`](../attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [5] | `1.0`; `1.1`; `2`; `3` | Recommended |
 | [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required |
 | [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [7] | `80`; `8080`; `443` | Required |
 | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Opt-In |
@@ -496,7 +496,7 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
 
 **[4]:** If not `http` and `network.protocol.version` is set.
 
-**[5]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
+**[5]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
 
 **[6]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used.
 
@@ -545,7 +545,7 @@ This metric is optional.
 | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required |
 | [`http.response.status_code`](../attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
 | [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `http`; `spdy` | Conditionally Required: [4] |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `1.0`; `1.1`; `2`; `3` | Recommended |
+| [`network.protocol.version`](../attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [5] | `1.0`; `1.1`; `2`; `3` | Recommended |
 | [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required |
 | [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [7] | `80`; `8080`; `443` | Required |
 | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Opt-In |
@@ -586,7 +586,7 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
 
 **[4]:** If not `http` and `network.protocol.version` is set.
 
-**[5]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
+**[5]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
 
 **[6]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used.
 
@@ -635,7 +635,7 @@ This metric is optional.
 | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required |
 | [`http.response.status_code`](../attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
 | [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `http`; `spdy` | Conditionally Required: [4] |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `1.0`; `1.1`; `2`; `3` | Recommended |
+| [`network.protocol.version`](../attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [5] | `1.0`; `1.1`; `2`; `3` | Recommended |
 | [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required |
 | [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [7] | `80`; `8080`; `443` | Required |
 | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Opt-In |
@@ -676,7 +676,7 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
 
 **[4]:** If not `http` and `network.protocol.version` is set.
 
-**[5]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
+**[5]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
 
 **[6]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used.
 
@@ -721,12 +721,12 @@ This metric is optional.
 |---|---|---|---|---|
 | [`http.connection.state`](../attributes-registry/http.md) | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | Required |
 | [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `3.1.1` | Recommended |
+| [`network.protocol.version`](../attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [1] | `1.1`; `2` | Recommended |
 | [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required |
 | [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Required |
 | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Opt-In |
 
-**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
+**[1]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
 
 **[2]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
 
@@ -760,12 +760,12 @@ This metric is optional.
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `3.1.1` | Recommended |
+| [`network.protocol.version`](../attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [1] | `1.1`; `2` | Recommended |
 | [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required |
 | [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Required |
 | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Opt-In |
 
-**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
+**[1]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
 
 **[2]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
 
diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md
index 1668199fa2..fcbadbf9b3 100644
--- a/docs/http/http-spans.md
+++ b/docs/http/http-spans.md
@@ -125,7 +125,7 @@ sections below.
 | [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended |
 | [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. |
 | [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [5] | `http`; `spdy` | Conditionally Required: [6] |
-| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [7] | `1.0`; `1.1`; `2`; `3` | Recommended |
+| [`network.protocol.version`](../attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | Recommended |
 | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [8] | `tcp`; `udp` | Opt-In |
 
 **[1]:** If the request fails with an error before response status code was sent or received,
@@ -170,7 +170,7 @@ The attribute value MUST consist of either multiple header values as an array of
 
 **[6]:** If not `http` and `network.protocol.version` is set.
 
-**[7]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
+**[7]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
 
 **[8]:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible.
 
diff --git a/model/registry/network.yaml b/model/registry/network.yaml
index e7520bae9c..0c1da314c4 100644
--- a/model/registry/network.yaml
+++ b/model/registry/network.yaml
@@ -141,12 +141,12 @@ groups:
       - id: protocol.version
         stability: stable
         type: string
-        brief: Version of the protocol specified in `network.protocol.name`.
-        examples: '3.1.1'
+        brief: The actual version of the protocol used for network communication.
+        examples: ['1.1', '2']
         note: >
-          `network.protocol.version` refers to the version of the protocol used and might be
-          different from the protocol client's version. If the HTTP client has a version
-          of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
+          If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)),
+          this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known,
+          this attribute SHOULD NOT be set.
       - id: transport
         stability: stable
         type:

From 8ac8d450f30c076b40f49f51ff01f0db5f59d51d Mon Sep 17 00:00:00 2001
From: Emily S <emily.stolfo@elastic.co>
Date: Tue, 26 Mar 2024 12:36:32 +0100
Subject: [PATCH 07/18] Use db.instance.id instead of specific elasticsearch
 node name attribute (#738)

Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>
---
 .chloggen/738.yaml                | 22 ++++++++++++++++++++++
 docs/attributes-registry/db.md    | 15 +++++++++++++--
 docs/database/elasticsearch.md    | 10 +++++-----
 model/registry/db.yaml            |  7 -------
 model/registry/deprecated/db.yaml |  5 +++++
 model/trace/database.yaml         |  2 +-
 6 files changed, 46 insertions(+), 15 deletions(-)
 create mode 100644 .chloggen/738.yaml

diff --git a/.chloggen/738.yaml b/.chloggen/738.yaml
new file mode 100644
index 0000000000..1d09182d8a
--- /dev/null
+++ b/.chloggen/738.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: db
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Update Elasticsearch attributes to use db.instance.id instead of db.elasticsearch.node.name
+
+# 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: [725]
+
+# (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:
diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md
index be7f5753d0..0c39de22e2 100644
--- a/docs/attributes-registry/db.md
+++ b/docs/attributes-registry/db.md
@@ -14,6 +14,7 @@
 - [Redis Attributes](#redis-attributes)
 - [SQL Attributes](#sql-attributes)
 - [Deprecated DB Attributes](#deprecated-db-attributes)
+  - [Deprecated Elasticsearch Attributes](#deprecated-elasticsearch-attributes)
 
 <!-- tocstop -->
 
@@ -171,7 +172,6 @@
 | Attribute  | Type | Description  | Examples  |
 |---|---|---|---|
 | `db.elasticsearch.cluster.name` | string | Represents the identifier of an Elasticsearch cluster. | `e9106fc68e3044f0b1475b04bf4ffd5f` |
-| `db.elasticsearch.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` |
 | `db.elasticsearch.path_parts.<key>` | string | A dynamic value in the url path. [1] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` |
 
 **[1]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.<key>`, where `<key>` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names.
@@ -219,5 +219,16 @@
 | Attribute  | Type | Description  | Examples  |
 |---|---|---|---|
 | `db.connection_string` | string | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Deprecated, use `server.address`, `server.port` attributes instead. | `Server=(localdb)\v11.0;Integrated Security=true;` |
+| `db.elasticsearch.node.name` | string | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Deprecated, use `db.instance.id` instead. | `instance-0000000001` |
 | `db.jdbc.driver_classname` | string | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Removed, no replacement at this time. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` |
-<!-- endsemconv -->
\ No newline at end of file
+<!-- endsemconv -->
+
+### Deprecated Elasticsearch Attributes
+
+<!-- semconv attributes.db.deprecated(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `db.connection_string` | string | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Deprecated, use `server.address`, `server.port` attributes instead. | `Server=(localdb)\v11.0;Integrated Security=true;` |
+| `db.elasticsearch.node.name` | string | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Deprecated, use `db.instance.id` instead. | `instance-0000000001` |
+| `db.jdbc.driver_classname` | string | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Removed, no replacement at this time. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` |
+<!-- endsemconv -->
diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md
index 4603978dda..5c8d9f5a9d 100644
--- a/docs/database/elasticsearch.md
+++ b/docs/database/elasticsearch.md
@@ -27,8 +27,8 @@ If the endpoint id is not available, the span name SHOULD be the `http.request.m
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | [`db.elasticsearch.cluster.name`](../attributes-registry/db.md) | string | Represents the identifier of an Elasticsearch cluster. | `e9106fc68e3044f0b1475b04bf4ffd5f` | Recommended: [1] |
-| [`db.elasticsearch.node.name`](../attributes-registry/db.md) | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | Recommended: [2] |
-| [`db.elasticsearch.path_parts.<key>`](../attributes-registry/db.md) | string | A dynamic value in the url path. [3] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | Conditionally Required: when the url has dynamic values |
+| [`db.elasticsearch.path_parts.<key>`](../attributes-registry/db.md) | string | A dynamic value in the url path. [2] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | Conditionally Required: when the url has dynamic values |
+| [`db.instance.id`](../attributes-registry/db.md) | string | An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. | `mysql-e26b99z.example.com` | Recommended: [3] |
 | [`db.operation`](../attributes-registry/db.md) | string | The endpoint identifier for the request. [4] | `search`; `ml.close_job`; `cat.aliases` | Required |
 | [`db.statement`](../attributes-registry/db.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | Recommended: [5] |
 | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [6] | `GET`; `POST`; `HEAD` | Required |
@@ -40,9 +40,9 @@ If the endpoint id is not available, the span name SHOULD be the `http.request.m
 
 **[1]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header.
 
-**[2]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header.
+**[2]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.<key>`, where `<key>` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names.
 
-**[3]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.<key>`, where `<key>` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names.
+**[3]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header.
 
 **[4]:** When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted.
 
@@ -105,6 +105,6 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
 | `url.full`                          | `"https://elasticsearch.mydomain.com:9200/my-index-000001/_search?from=40&size=20"`                                                 |
 | `db.elasticsearch.path_parts.index` | `"my-index-000001"`                                                                                                                 |
 | `db.elasticsearch.cluster.name`     | `"e9106fc68e3044f0b1475b04bf4ffd5f"`                                                                                                |
-| `db.elasticsearch.node.name` | `"instance-0000000001"`                                                                                                             |
+| `db.instance.id`      | `"instance-0000000001"`                                                                                                             |
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
diff --git a/model/registry/db.yaml b/model/registry/db.yaml
index 4185c279ab..781cc68f9f 100644
--- a/model/registry/db.yaml
+++ b/model/registry/db.yaml
@@ -173,13 +173,6 @@ groups:
           Represents the identifier of an Elasticsearch cluster.
         examples: ["e9106fc68e3044f0b1475b04bf4ffd5f"]
         tag: tech-specific-elasticsearch
-      - id: elasticsearch.node.name
-        type: string
-        stability: experimental
-        brief: >
-          Represents the human-readable identifier of the node/instance to which a request was routed.
-        examples: ["instance-0000000001"]
-        tag: tech-specific-elasticsearch
       - id: elasticsearch.path_parts
         type: template[string]
         stability: experimental
diff --git a/model/registry/deprecated/db.yaml b/model/registry/deprecated/db.yaml
index 1dd6996704..76430d1b1b 100644
--- a/model/registry/deprecated/db.yaml
+++ b/model/registry/deprecated/db.yaml
@@ -16,3 +16,8 @@ groups:
         brief: 'Removed, no replacement at this time.'
         deprecated: 'Removed as not used.'
         examples: ['org.postgresql.Driver', 'com.microsoft.sqlserver.jdbc.SQLServerDriver']
+      - id: elasticsearch.node.name
+        type: string
+        brief: 'Deprecated, use `db.instance.id` instead.'
+        deprecated: "Replaced by `db.instance.id`."
+        examples: ["instance-0000000001"]
diff --git a/model/trace/database.yaml b/model/trace/database.yaml
index e824438bf9..7435d4e485 100644
--- a/model/trace/database.yaml
+++ b/model/trace/database.yaml
@@ -189,7 +189,7 @@ groups:
           recommended: >
             When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header.
         tag: tech-specific
-      - ref: db.elasticsearch.node.name
+      - ref: db.instance.id
         requirement_level:
           recommended: >
             When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header.

From 4368358cdcdd78f37291317a31cbc413080738ec Mon Sep 17 00:00:00 2001
From: Yash Tibrewal <yashkt@google.com>
Date: Tue, 26 Mar 2024 05:48:05 -0700
Subject: [PATCH 08/18] Link to proposal for gRPC metrics (#627)

Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
---
 .chloggen/627.yaml      | 22 ++++++++++++++++++++++
 docs/rpc/README.md      |  4 ++++
 docs/rpc/rpc-metrics.md |  4 ++++
 3 files changed, 30 insertions(+)
 create mode 100755 .chloggen/627.yaml

diff --git a/.chloggen/627.yaml b/.chloggen/627.yaml
new file mode 100755
index 0000000000..1e96d83745
--- /dev/null
+++ b/.chloggen/627.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: rpc
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add link to specification for metrics defined by gRPC community.
+
+# 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: [627]
+
+# (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:
diff --git a/docs/rpc/README.md b/docs/rpc/README.md
index 353f6bce85..f028fd910a 100644
--- a/docs/rpc/README.md
+++ b/docs/rpc/README.md
@@ -23,4 +23,8 @@ Technology specific semantic conventions are defined for the following RPC syste
 * [gRPC](grpc.md): Semantic Conventions for *gRPC*.
 * [JSON-RPC](json-rpc.md): Semantic Conventions for *JSON-RPC*.
 
+Specifications defined by maintainers of RPC systems:
+
+* [gRPC](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md): Semantic Conventions for *gRPC*.
+
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md
index ff162640e3..6369eb4461 100644
--- a/docs/rpc/rpc-metrics.md
+++ b/docs/rpc/rpc-metrics.md
@@ -288,5 +288,9 @@ More specific Semantic Conventions are defined for the following RPC technologie
 * [gRPC](grpc.md): Semantic Conventions for *gRPC*.
 * [JSON-RPC](json-rpc.md): Semantic Conventions for *JSON-RPC*.
 
+Specifications defined by maintainers of RPC systems:
+
+* [gRPC](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md): Semantic Conventions for *gRPC*.
+
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
 [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended

From 0941ebb01638da01086baeaafe39c6de8a6b3d91 Mon Sep 17 00:00:00 2001
From: Chris Mark <chrismarkou92@gmail.com>
Date: Wed, 27 Mar 2024 11:47:38 +0200
Subject: [PATCH 09/18] Add container metric fields (from ECS) (#282)

Signed-off-by: ChrsMark <chrismarkou92@gmail.com>
Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
---
 .chloggen/add_new_container_metrics.yaml |  21 +++++
 docs/attributes-registry/container.md    |   9 ++
 docs/system/container-metrics.md         | 105 +++++++++++++++++++++++
 model/metrics/container.yaml             |  53 ++++++++++++
 model/registry/container.yaml            |  15 ++++
 5 files changed, 203 insertions(+)
 create mode 100644 .chloggen/add_new_container_metrics.yaml
 create mode 100644 docs/system/container-metrics.md
 create mode 100644 model/metrics/container.yaml

diff --git a/.chloggen/add_new_container_metrics.yaml b/.chloggen/add_new_container_metrics.yaml
new file mode 100644
index 0000000000..4e6c71bb49
--- /dev/null
+++ b/.chloggen/add_new_container_metrics.yaml
@@ -0,0 +1,21 @@
+# 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: "container"
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "Add new container metrics for `cpu`, `memory`, `disk` and `network`"
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [282, 72]
+
+# (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:
diff --git a/docs/attributes-registry/container.md b/docs/attributes-registry/container.md
index d9f66e67f9..4e6ec20847 100644
--- a/docs/attributes-registry/container.md
+++ b/docs/attributes-registry/container.md
@@ -11,6 +11,7 @@
 | `container.command` | string | The command used to run the container (i.e. the command name). [1] | `otelcontribcol` |
 | `container.command_args` | string[] | All the command arguments (including the command/executable itself) run by the container. [2] | `[otelcontribcol, --config, config.yaml]` |
 | `container.command_line` | string | The full command run by the container as a single string representing the full command. [2] | `otelcontribcol --config config.yaml` |
+| `container.cpu.state` | string | The CPU state for this data point. | `user`; `kernel` |
 | `container.id` | string | Container ID. Usually a UUID, as for example used to [identify Docker containers](https://docs.docker.com/engine/reference/run/#container-identification). The UUID might be abbreviated. | `a3bf90e006b2` |
 | `container.image.id` | string | Runtime specific image identifier. Usually a hash algorithm followed by a UUID. [2] | `sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f` |
 | `container.image.name` | string | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` |
@@ -27,4 +28,12 @@ K8s defines a link to the container registry repository with digest `"imageID":
 The ID is assinged by the container runtime and can vary in different environments. Consider using `oci.manifest.digest` if it is important to identify the same image in different environments/runtimes.
 
 **[3]:** [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field.
+
+`container.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
+
+| Value  | Description |
+|---|---|
+| `user` | When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows). |
+| `system` | When CPU is used by the system (host OS) |
+| `kernel` | When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows). |
 <!-- endsemconv -->
diff --git a/docs/system/container-metrics.md b/docs/system/container-metrics.md
new file mode 100644
index 0000000000..d5df4933b2
--- /dev/null
+++ b/docs/system/container-metrics.md
@@ -0,0 +1,105 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Container
+--->
+
+# Semantic Conventions for Container Metrics
+
+**Status**: [Experimental][DocumentStatus]
+
+## Container Metrics
+
+### Metric: `container.cpu.time`
+
+This metric is [opt-in][MetricOptIn].
+
+<!-- semconv metric.container.cpu.time(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `container.cpu.time` | Counter | `s` | Total CPU time consumed [1] |
+
+**[1]:** Total CPU time consumed by the specific container on all available CPU cores
+<!-- endsemconv -->
+
+<!-- semconv metric.container.cpu.time(full) -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| [`container.cpu.state`](../attributes-registry/container.md) | string | The CPU state for this data point. A container SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `user`; `kernel` | Opt-In |
+
+`container.cpu.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
+
+| Value  | Description |
+|---|---|
+| `user` | When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows). |
+| `system` | When CPU is used by the system (host OS) |
+| `kernel` | When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows). |
+<!-- endsemconv -->
+
+### Metric: `container.memory.usage`
+
+This metric is [opt-in][MetricOptIn].
+
+<!-- semconv metric.container.memory.usage(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `container.memory.usage` | Counter | `By` | Memory usage of the container. [1] |
+
+**[1]:** Memory usage of the container.
+<!-- endsemconv -->
+
+<!-- semconv metric.container.memory.usage(full) -->
+<!-- endsemconv -->
+
+### Metric: `container.disk.io`
+
+This metric is [opt-in][MetricOptIn].
+
+<!-- semconv metric.container.disk.io(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `container.disk.io` | Counter | `By` | Disk bytes for the container. [1] |
+
+**[1]:** The total number of bytes read/written successfully (aggregated from all disks).
+<!-- endsemconv -->
+
+<!-- semconv metric.container.disk.io(full) -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| [`disk.io.direction`](../attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | Recommended |
+| `system.device` | string | The device identifier | `(identifier)` | Recommended |
+
+`disk.io.direction` MUST be one of the following:
+
+| Value  | Description |
+|---|---|
+| `read` | read |
+| `write` | write |
+<!-- endsemconv -->
+
+### Metric: `container.network.io`
+
+This metric is [opt-in][MetricOptIn].
+
+<!-- semconv metric.container.network.io(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `container.network.io` | Counter | `By` | Network bytes for the container. [1] |
+
+**[1]:** The number of bytes sent/received on all network interfaces by the container.
+<!-- endsemconv -->
+
+<!-- semconv metric.container.network.io(full) -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| [`network.io.direction`](../attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | Recommended |
+| `system.device` | string | The device identifier | `(identifier)` | Recommended |
+
+`network.io.direction` MUST be one of the following:
+
+| Value  | Description |
+|---|---|
+| `transmit` | transmit |
+| `receive` | receive |
+<!-- endsemconv -->
+
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md
+[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.26.0/specification/metrics/metric-requirement-level.md#opt-in
diff --git a/model/metrics/container.yaml b/model/metrics/container.yaml
new file mode 100644
index 0000000000..3904f168be
--- /dev/null
+++ b/model/metrics/container.yaml
@@ -0,0 +1,53 @@
+groups:
+  # container.cpu.* metrics and attribute group
+  - id: metric.container.cpu.time
+    type: metric
+    metric_name: container.cpu.time
+    brief: "Total CPU time consumed"
+    note: >
+      Total CPU time consumed by the specific container on all available CPU cores
+    instrument: counter
+    unit: "s"
+    attributes:
+      - ref: container.cpu.state
+        brief: "The CPU state for this data point. A container SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels."
+        requirement_level: opt_in
+
+  # container.memory.* metrics and attribute group
+  - id: metric.container.memory.usage
+    type: metric
+    metric_name: container.memory.usage
+    brief: "Memory usage of the container."
+    note: >
+      Memory usage of the container.
+    instrument: counter
+    unit: "By"
+
+  # container.disk.io.* metrics and attribute group
+  - id: metric.container.disk.io
+    type: metric
+    metric_name: container.disk.io
+    brief: "Disk bytes for the container."
+    note: >
+      The total number of bytes read/written
+      successfully (aggregated from all disks).
+    instrument: counter
+    unit: "By"
+    attributes:
+      - ref: disk.io.direction
+      - ref: system.device
+
+  # container.network.io.* metrics and attribute group
+  - id: metric.container.network.io
+    type: metric
+    metric_name: container.network.io
+    brief: "Network bytes for the container."
+    note: >
+      The number of bytes sent/received
+      on all network interfaces
+      by the container.
+    instrument: counter
+    unit: "By"
+    attributes:
+      - ref: network.io.direction
+      - ref: system.device
diff --git a/model/registry/container.yaml b/model/registry/container.yaml
index 343c63b927..2878766b66 100644
--- a/model/registry/container.yaml
+++ b/model/registry/container.yaml
@@ -95,3 +95,18 @@ groups:
         brief: >
           Container labels, `<key>` being the label name, the value being the label value.
         examples: [ 'container.label.app=nginx' ]
+      - id: cpu.state
+        brief: "The CPU state for this data point."
+        type:
+          allow_custom_values: true
+          members:
+            - id: user
+              value: 'user'
+              brief: "When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows)."
+            - id: system
+              value: 'system'
+              brief: "When CPU is used by the system (host OS)"
+            - id: kernel
+              value: 'kernel'
+              brief: "When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows)."
+        examples: ["user", "kernel"]

From f8f1e16fecf6035f055240fceec0c6c1d741b492 Mon Sep 17 00:00:00 2001
From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Date: Wed, 27 Mar 2024 16:23:16 +0100
Subject: [PATCH 10/18] [chore] Move CloudEvents attributes to the registry
 (#837)

---
 .github/ISSUE_TEMPLATE/bug_report.yaml      |  1 +
 .github/ISSUE_TEMPLATE/change_proposal.yaml |  1 +
 .github/ISSUE_TEMPLATE/new-conventions.yaml |  1 +
 docs/attributes-registry/README.md          |  1 +
 docs/attributes-registry/cloudevents.md     | 16 +++++++++
 docs/cloudevents/cloudevents-spans.md       | 10 +++---
 model/registry/cloudevents.yaml             | 37 +++++++++++++++++++
 model/trace/cloudevents.yaml                | 39 +++++----------------
 8 files changed, 70 insertions(+), 36 deletions(-)
 create mode 100644 docs/attributes-registry/cloudevents.md
 create mode 100644 model/registry/cloudevents.yaml

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml
index 08dca47531..c363fa1bfd 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yaml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yaml
@@ -23,6 +23,7 @@ body:
         - area:browser
         - area:client
         - area:cloud
+        - area:cloudevents
         - area:code
         - area:container
         - area:db
diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml
index edaa3a4a75..a14603adf1 100644
--- a/.github/ISSUE_TEMPLATE/change_proposal.yaml
+++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml
@@ -16,6 +16,7 @@ body:
         - area:browser
         - area:client
         - area:cloud
+        - area:cloudevents
         - area:code
         - area:container
         - area:db
diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml
index 8a72b6bff2..161b9c7eeb 100644
--- a/.github/ISSUE_TEMPLATE/new-conventions.yaml
+++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml
@@ -25,6 +25,7 @@ body:
         - area:browser
         - area:client
         - area:cloud
+        - area:cloudevents
         - area:code
         - area:container
         - area:db
diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md
index 00ff6ad8e6..8b22577d09 100644
--- a/docs/attributes-registry/README.md
+++ b/docs/attributes-registry/README.md
@@ -31,6 +31,7 @@ Currently, the following namespaces exist:
 * [Browser](browser.md)
 * [Client](client.md)
 * [Cloud](cloud.md)
+* [CloudEvents](cloudevents.md)
 * [Code](code.md)
 * [Container](container.md)
 * [DB](db.md) (database)
diff --git a/docs/attributes-registry/cloudevents.md b/docs/attributes-registry/cloudevents.md
new file mode 100644
index 0000000000..aba5249b29
--- /dev/null
+++ b/docs/attributes-registry/cloudevents.md
@@ -0,0 +1,16 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+
+# CloudEvents
+
+## CloudEvents Attributes
+
+<!-- semconv registry.cloudevents(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event. | `123e4567-e89b-12d3-a456-426614174000`; `0001` |
+| `cloudevents.event_source` | string | The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` |
+| `cloudevents.event_spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses. | `1.0` |
+| `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` |
+| `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` |
+<!-- endsemconv -->
diff --git a/docs/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md
index 44f112fe7a..472f8aea16 100644
--- a/docs/cloudevents/cloudevents-spans.md
+++ b/docs/cloudevents/cloudevents-spans.md
@@ -202,11 +202,11 @@ The following attributes are applicable to creation and processing Spans.
 <!-- semconv cloudevents -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event. | `123e4567-e89b-12d3-a456-426614174000`; `0001` | Required |
-| `cloudevents.event_source` | string | The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | Required |
-| `cloudevents.event_spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses. | `1.0` | Recommended |
-| `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | Recommended |
-| `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | Recommended |
+| [`cloudevents.event_id`](../attributes-registry/cloudevents.md) | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event. | `123e4567-e89b-12d3-a456-426614174000`; `0001` | Required |
+| [`cloudevents.event_source`](../attributes-registry/cloudevents.md) | string | The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | Required |
+| [`cloudevents.event_spec_version`](../attributes-registry/cloudevents.md) | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses. | `1.0` | Recommended |
+| [`cloudevents.event_subject`](../attributes-registry/cloudevents.md) | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | Recommended |
+| [`cloudevents.event_type`](../attributes-registry/cloudevents.md) | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | Recommended |
 <!-- endsemconv -->
 <!-- prettier-ignore-end -->
 
diff --git a/model/registry/cloudevents.yaml b/model/registry/cloudevents.yaml
new file mode 100644
index 0000000000..4da702f8a8
--- /dev/null
+++ b/model/registry/cloudevents.yaml
@@ -0,0 +1,37 @@
+groups:
+  - id: registry.cloudevents
+    prefix: cloudevents
+    type: attribute_group
+    brief: >
+        This document defines attributes for CloudEvents.
+    attributes:
+      - id: event_id
+        type: string
+        stability: experimental
+        brief: >
+          The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event.
+        examples: ['123e4567-e89b-12d3-a456-426614174000', '0001']
+      - id: event_source
+        type: string
+        stability: experimental
+        brief: >
+          The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened.
+        examples: ['https://github.com/cloudevents', '/cloudevents/spec/pull/123', 'my-service' ]
+      - id: event_spec_version
+        type: string
+        stability: experimental
+        brief: >
+          The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses.
+        examples: '1.0'
+      - id: event_type
+        type: string
+        stability: experimental
+        brief: >
+          The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence.
+        examples: ['com.github.pull_request.opened', 'com.example.object.deleted.v2']
+      - id: event_subject
+        type: string
+        stability: experimental
+        brief: >
+          The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source).
+        examples: 'mynewfile.jpg'
diff --git a/model/trace/cloudevents.yaml b/model/trace/cloudevents.yaml
index 931b082f94..604d101c17 100644
--- a/model/trace/cloudevents.yaml
+++ b/model/trace/cloudevents.yaml
@@ -1,41 +1,18 @@
 groups:
   - id: cloudevents
-    prefix: cloudevents
     type: span
     brief: >
         This document defines attributes for CloudEvents.
         CloudEvents is a specification on how to define event data in a standard way.
         These attributes can be attached to spans when performing operations with CloudEvents, regardless of the protocol being used.
     attributes:
-      - id: event_id
-        type: string
-        stability: experimental
+      - ref: cloudevents.event_id
         requirement_level: required
-        brief: >
-          The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event.
-        examples: ['123e4567-e89b-12d3-a456-426614174000', '0001']
-      - id: event_source
-        type: string
-        stability: experimental
+      - ref: cloudevents.event_source
         requirement_level: required
-        brief: >
-          The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened.
-        examples: ['https://github.com/cloudevents', '/cloudevents/spec/pull/123', 'my-service' ]
-      - id: event_spec_version
-        type: string
-        stability: experimental
-        brief: >
-          The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses.
-        examples: '1.0'
-      - id: event_type
-        type: string
-        stability: experimental
-        brief: >
-          The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence.
-        examples: ['com.github.pull_request.opened', 'com.example.object.deleted.v2']
-      - id: event_subject
-        type: string
-        stability: experimental
-        brief: >
-          The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source).
-        examples: 'mynewfile.jpg'
+      - ref: cloudevents.event_spec_version
+        requirement_level: recommended
+      - ref: cloudevents.event_type
+        requirement_level: recommended
+      - ref: cloudevents.event_subject
+        requirement_level: recommended

From ae4005e8a13bb05eae238a325dc40e65852f6cea Mon Sep 17 00:00:00 2001
From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Date: Wed, 27 Mar 2024 16:43:32 +0100
Subject: [PATCH 11/18] Fix path of yaml files for VSCode schema auto
 completion (#846)

Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com>
---
 .vscode/settings.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.vscode/settings.json b/.vscode/settings.json
index 6b792056bd..ec636cc19b 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -10,8 +10,8 @@
         "MD040": false,
     },
     "yaml.schemas": {
-        "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.21.0/semantic-conventions/semconv.schema.json": [
-            "semantic_conventions/**/*.yaml"
+        "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.24.0/semantic-conventions/semconv.schema.json": [
+            "model/**/*.yaml",
         ]
     },
     "json.schemaDownload.enable": true

From 6bbc74de661ee98ce1c9aec05c8382ea59b84198 Mon Sep 17 00:00:00 2001
From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Date: Wed, 27 Mar 2024 17:40:44 +0100
Subject: [PATCH 12/18] [chore] Move Feature Flag attributes to the registry
 (#842)

---
 .github/ISSUE_TEMPLATE/bug_report.yaml      |  1 +
 .github/ISSUE_TEMPLATE/change_proposal.yaml |  1 +
 .github/ISSUE_TEMPLATE/new-conventions.yaml |  1 +
 docs/attributes-registry/README.md          |  1 +
 docs/attributes-registry/feature-flag.md    | 19 ++++++++++++
 docs/feature-flags/feature-flags-logs.md    |  6 ++--
 docs/feature-flags/feature-flags-spans.md   |  6 ++--
 model/logs/log-feature_flag.yaml            |  2 +-
 model/registry/feature-flag.yaml            | 33 +++++++++++++++++++++
 model/trace/feature-flag.yaml               | 31 +++----------------
 10 files changed, 67 insertions(+), 34 deletions(-)
 create mode 100644 docs/attributes-registry/feature-flag.md
 create mode 100644 model/registry/feature-flag.yaml

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml
index c363fa1bfd..16b2187e26 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yaml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yaml
@@ -34,6 +34,7 @@ body:
         - area:error
         - area:exception
         - area:faas
+        - area:feature-flag
         - area:host
         - area:http
         - area:k8s
diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml
index a14603adf1..269d42edac 100644
--- a/.github/ISSUE_TEMPLATE/change_proposal.yaml
+++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml
@@ -27,6 +27,7 @@ body:
         - area:error
         - area:exception
         - area:faas
+        - area:feature-flag
         - area:host
         - area:http
         - area:k8s
diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml
index 161b9c7eeb..8c4df4f09e 100644
--- a/.github/ISSUE_TEMPLATE/new-conventions.yaml
+++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml
@@ -36,6 +36,7 @@ body:
         - area:error
         - area:exception
         - area:faas
+        - area:feature-flag
         - area:host
         - area:http
         - area:k8s
diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md
index 8b22577d09..187f3847ee 100644
--- a/docs/attributes-registry/README.md
+++ b/docs/attributes-registry/README.md
@@ -41,6 +41,7 @@ Currently, the following namespaces exist:
 * [Error](error.md)
 * [Exception](exception.md)
 * [FaaS](faas.md)
+* [Feature Flag](feature-flag.md)
 * [Host](host.md)
 * [HTTP](http.md)
 * [K8s](k8s.md)
diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md
new file mode 100644
index 0000000000..b1fcf8f872
--- /dev/null
+++ b/docs/attributes-registry/feature-flag.md
@@ -0,0 +1,19 @@
+# Feature Flag
+
+## Feature Flag Attributes
+<!-- semconv registry.feature_flag(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `feature_flag.key` | string | The unique identifier of the feature flag. | `logo-color` |
+| `feature_flag.provider_name` | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` |
+| `feature_flag.variant` | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` |
+
+**[1]:** A semantic identifier, commonly referred to as a variant, provides a means
+for referring to a value without including the value itself. This can
+provide additional context for understanding the meaning behind a value.
+For example, the variant `red` maybe be used for the value `#c05543`.
+
+A stringified version of the value can be used in situations where a
+semantic identifier is unavailable. String representation of the value
+should be determined by the implementer.
+<!-- endsemconv -->
diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md
index 200229fab7..e86df3b2f3 100644
--- a/docs/feature-flags/feature-flags-logs.md
+++ b/docs/feature-flags/feature-flags-logs.md
@@ -42,9 +42,9 @@ The event name MUST be `feature_flag`.
 
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| [`feature_flag.key`](feature-flags-spans.md) | string | The unique identifier of the feature flag. | `logo-color` | Required |
-| [`feature_flag.provider_name`](feature-flags-spans.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | Recommended |
-| [`feature_flag.variant`](feature-flags-spans.md) | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | Recommended |
+| [`feature_flag.key`](../attributes-registry/feature-flag.md) | string | The unique identifier of the feature flag. | `logo-color` | Recommended |
+| [`feature_flag.provider_name`](../attributes-registry/feature-flag.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | Recommended |
+| [`feature_flag.variant`](../attributes-registry/feature-flag.md) | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | Recommended |
 
 **[1]:** A semantic identifier, commonly referred to as a variant, provides a means
 for referring to a value without including the value itself. This can
diff --git a/docs/feature-flags/feature-flags-spans.md b/docs/feature-flags/feature-flags-spans.md
index bdd94a0106..da0fa1cc1f 100644
--- a/docs/feature-flags/feature-flags-spans.md
+++ b/docs/feature-flags/feature-flags-spans.md
@@ -46,9 +46,9 @@ The event name MUST be `feature_flag`.
 
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `feature_flag.key` | string | The unique identifier of the feature flag. | `logo-color` | Required |
-| `feature_flag.provider_name` | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | Recommended |
-| `feature_flag.variant` | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | Recommended |
+| [`feature_flag.key`](../attributes-registry/feature-flag.md) | string | The unique identifier of the feature flag. | `logo-color` | Required |
+| [`feature_flag.provider_name`](../attributes-registry/feature-flag.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | Recommended |
+| [`feature_flag.variant`](../attributes-registry/feature-flag.md) | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | Recommended |
 
 **[1]:** A semantic identifier, commonly referred to as a variant, provides a means
 for referring to a value without including the value itself. This can
diff --git a/model/logs/log-feature_flag.yaml b/model/logs/log-feature_flag.yaml
index 6d902423f5..4530096de7 100644
--- a/model/logs/log-feature_flag.yaml
+++ b/model/logs/log-feature_flag.yaml
@@ -1,7 +1,7 @@
 groups:
   - id: log-feature_flag
     type: event
-    prefix: feature_flag
+    name: feature_flag
     brief: >
       This document defines attributes for feature flag evaluations
       represented using Log Records.
diff --git a/model/registry/feature-flag.yaml b/model/registry/feature-flag.yaml
new file mode 100644
index 0000000000..9de106ffc8
--- /dev/null
+++ b/model/registry/feature-flag.yaml
@@ -0,0 +1,33 @@
+groups:
+  - id: registry.feature_flag
+    prefix: feature_flag
+    type: attribute_group
+    brief: >
+        This document defines attributes for Feature Flags.
+    attributes:
+      - id: key
+        type: string
+        stability: experimental
+        brief: The unique identifier of the feature flag.
+        examples: ["logo-color"]
+      - id: provider_name
+        type: string
+        stability: experimental
+        brief: The name of the service provider that performs the flag evaluation.
+        examples: ["Flag Manager"]
+      - id: variant
+        type: string
+        stability: experimental
+        examples: ["red", "true", "on"]
+        brief: >
+          SHOULD be a semantic identifier for a value. If one is unavailable, a
+          stringified version of the value can be used.
+        note: |-
+          A semantic identifier, commonly referred to as a variant, provides a means
+          for referring to a value without including the value itself. This can
+          provide additional context for understanding the meaning behind a value.
+          For example, the variant `red` maybe be used for the value `#c05543`.
+
+          A stringified version of the value can be used in situations where a
+          semantic identifier is unavailable. String representation of the value
+          should be determined by the implementer.
diff --git a/model/trace/feature-flag.yaml b/model/trace/feature-flag.yaml
index b6bc1ba1dc..8aae493385 100644
--- a/model/trace/feature-flag.yaml
+++ b/model/trace/feature-flag.yaml
@@ -1,37 +1,14 @@
 groups:
   - id: feature_flag
-    prefix: feature_flag
     type: event
+    name: feature_flag
     brief: >
       This semantic convention defines the attributes used to represent a
       feature flag evaluation as an event.
     attributes:
-      - id: key
-        type: string
-        stability: experimental
+      - ref: feature_flag.key
         requirement_level: required
-        brief: The unique identifier of the feature flag.
-        examples: ["logo-color"]
-      - id: provider_name
-        type: string
-        stability: experimental
+      - ref: feature_flag.provider_name
         requirement_level: recommended
-        brief: The name of the service provider that performs the flag evaluation.
-        examples: ["Flag Manager"]
-      - id: variant
-        type: string
-        stability: experimental
+      - ref: feature_flag.variant
         requirement_level: recommended
-        examples: ["red", "true", "on"]
-        brief: >
-          SHOULD be a semantic identifier for a value. If one is unavailable, a
-          stringified version of the value can be used.
-        note: |-
-          A semantic identifier, commonly referred to as a variant, provides a means
-          for referring to a value without including the value itself. This can
-          provide additional context for understanding the meaning behind a value.
-          For example, the variant `red` maybe be used for the value `#c05543`.
-
-          A stringified version of the value can be used in situations where a
-          semantic identifier is unavailable. String representation of the value
-          should be determined by the implementer.

From 3adaac281c21480c53dfa00db4eb7bbbbe835599 Mon Sep 17 00:00:00 2001
From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Date: Wed, 27 Mar 2024 17:48:13 +0100
Subject: [PATCH 13/18] [chore] Move end user attributes to the registry (#844)

---
 .github/ISSUE_TEMPLATE/bug_report.yaml      |  1 +
 .github/ISSUE_TEMPLATE/change_proposal.yaml |  1 +
 .github/ISSUE_TEMPLATE/new-conventions.yaml |  1 +
 docs/attributes-registry/README.md          |  1 +
 docs/attributes-registry/enduser.md         | 10 +++++++
 docs/general/attributes.md                  |  6 ++---
 model/general.yaml                          | 29 +++++----------------
 model/registry/enduser.yaml                 | 29 +++++++++++++++++++++
 8 files changed, 52 insertions(+), 26 deletions(-)
 create mode 100644 docs/attributes-registry/enduser.md
 create mode 100644 model/registry/enduser.yaml

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml
index 16b2187e26..4c7e81a5d0 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yaml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yaml
@@ -31,6 +31,7 @@ body:
         - area:device
         - area:disk
         - area:dns
+        - area:enduser
         - area:error
         - area:exception
         - area:faas
diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml
index 269d42edac..c2c40ec74a 100644
--- a/.github/ISSUE_TEMPLATE/change_proposal.yaml
+++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml
@@ -24,6 +24,7 @@ body:
         - area:device
         - area:disk
         - area:dns
+        - area:enduser
         - area:error
         - area:exception
         - area:faas
diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml
index 8c4df4f09e..311ee512cb 100644
--- a/.github/ISSUE_TEMPLATE/new-conventions.yaml
+++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml
@@ -33,6 +33,7 @@ body:
         - area:device
         - area:disk
         - area:dns
+        - area:enduser
         - area:error
         - area:exception
         - area:faas
diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md
index 187f3847ee..a1fb7a30fe 100644
--- a/docs/attributes-registry/README.md
+++ b/docs/attributes-registry/README.md
@@ -38,6 +38,7 @@ Currently, the following namespaces exist:
 * [Destination](destination.md)
 * [Device](device.md)
 * [Disk](disk.md)
+* [End user](enduser.md)
 * [Error](error.md)
 * [Exception](exception.md)
 * [FaaS](faas.md)
diff --git a/docs/attributes-registry/enduser.md b/docs/attributes-registry/enduser.md
new file mode 100644
index 0000000000..f8be2f3699
--- /dev/null
+++ b/docs/attributes-registry/enduser.md
@@ -0,0 +1,10 @@
+# End User
+
+## End User Attributes
+<!-- semconv registry.enduser(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `enduser.id` | string | Username or client_id extracted from the access token or [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) header in the inbound request from outside the system. | `username` |
+| `enduser.role` | string | Actual/assumed role the client is making the request under extracted from token or application security context. | `admin` |
+| `enduser.scope` | string | Scopes or granted authorities the client currently possesses extracted from token or application security context. The value would come from the scope associated with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3) or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). | `read:message, write:files` |
+<!-- endsemconv -->
diff --git a/docs/general/attributes.md b/docs/general/attributes.md
index d809f56add..9a74f6807f 100644
--- a/docs/general/attributes.md
+++ b/docs/general/attributes.md
@@ -311,9 +311,9 @@ These attributes may be used for any operation with an authenticated and/or auth
 <!-- semconv identity -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `enduser.id` | string | Username or client_id extracted from the access token or [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) header in the inbound request from outside the system. | `username` | Recommended |
-| `enduser.role` | string | Actual/assumed role the client is making the request under extracted from token or application security context. | `admin` | Recommended |
-| `enduser.scope` | string | Scopes or granted authorities the client currently possesses extracted from token or application security context. The value would come from the scope associated with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3) or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). | `read:message, write:files` | Recommended |
+| [`enduser.id`](../attributes-registry/enduser.md) | string | Username or client_id extracted from the access token or [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) header in the inbound request from outside the system. | `username` | Recommended |
+| [`enduser.role`](../attributes-registry/enduser.md) | string | Actual/assumed role the client is making the request under extracted from token or application security context. | `admin` | Recommended |
+| [`enduser.scope`](../attributes-registry/enduser.md) | string | Scopes or granted authorities the client currently possesses extracted from token or application security context. The value would come from the scope associated with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3) or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). | `read:message, write:files` | Recommended |
 <!-- endsemconv -->
 
 These attributes describe the authenticated user driving the user agent making requests to the instrumented
diff --git a/model/general.yaml b/model/general.yaml
index ec38d6e8dd..23ec6cd32e 100644
--- a/model/general.yaml
+++ b/model/general.yaml
@@ -41,33 +41,16 @@ groups:
           resource attribute of the remote service if any.
         examples: "AuthTokenCache"
   - id: identity
-    prefix: enduser
     type: span
     brief: >
       These attributes may be used for any operation with an authenticated and/or authorized enduser.
     attributes:
-      - id: id
-        type: string
-        stability: experimental
-        brief: >
-          Username or client_id extracted from the access token or
-          [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2)
-          header in the inbound request from outside the system.
-        examples: 'username'
-      - id: role
-        type: string
-        stability: experimental
-        brief: 'Actual/assumed role the client is making the request under extracted from token or application security context.'
-        examples: 'admin'
-      - id: scope
-        type: string
-        stability: experimental
-        brief: >
-          Scopes or granted authorities the client currently possesses extracted from token
-          or application security context. The value would come from the scope associated
-          with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3)
-          or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html).
-        examples: 'read:message, write:files'
+      - ref: enduser.id
+        requirement_level: recommended
+      - ref: enduser.role
+        requirement_level: recommended
+      - ref: enduser.scope
+        requirement_level: recommended
   - id: thread
     type: span
     brief: >
diff --git a/model/registry/enduser.yaml b/model/registry/enduser.yaml
new file mode 100644
index 0000000000..656f36d682
--- /dev/null
+++ b/model/registry/enduser.yaml
@@ -0,0 +1,29 @@
+groups:
+  - id: registry.enduser
+    prefix: enduser
+    type: attribute_group
+    brief: >
+      This document defines attributes for operations with an authenticated and/or authorized enduser.
+    attributes:
+      - id: id
+        type: string
+        stability: experimental
+        brief: >
+          Username or client_id extracted from the access token or
+          [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2)
+          header in the inbound request from outside the system.
+        examples: 'username'
+      - id: role
+        type: string
+        stability: experimental
+        brief: 'Actual/assumed role the client is making the request under extracted from token or application security context.'
+        examples: 'admin'
+      - id: scope
+        type: string
+        stability: experimental
+        brief: >
+          Scopes or granted authorities the client currently possesses extracted from token
+          or application security context. The value would come from the scope associated
+          with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3)
+          or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html).
+        examples: 'read:message, write:files'

From a187625b51dd8f4b0f8ecff2461f65cba0f27e5a Mon Sep 17 00:00:00 2001
From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Date: Wed, 27 Mar 2024 17:55:19 +0100
Subject: [PATCH 14/18] [chore] Move deployment attributes to the registry
 (#845)

---
 .github/ISSUE_TEMPLATE/bug_report.yaml      |  1 +
 .github/ISSUE_TEMPLATE/change_proposal.yaml |  1 +
 .github/ISSUE_TEMPLATE/new-conventions.yaml |  1 +
 docs/attributes-registry/README.md          |  1 +
 docs/attributes-registry/deployment.md      | 16 +++++++++++++++
 docs/resource/deployment-environment.md     |  2 +-
 model/registry/deployment.yaml              | 22 +++++++++++++++++++++
 model/resource/deployment_environment.yaml  | 18 ++---------------
 8 files changed, 45 insertions(+), 17 deletions(-)
 create mode 100644 docs/attributes-registry/deployment.md
 create mode 100644 model/registry/deployment.yaml

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml
index 4c7e81a5d0..30d6a421f7 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yaml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yaml
@@ -27,6 +27,7 @@ body:
         - area:code
         - area:container
         - area:db
+        - area:deployment
         - area:destination
         - area:device
         - area:disk
diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml
index c2c40ec74a..d47978fd71 100644
--- a/.github/ISSUE_TEMPLATE/change_proposal.yaml
+++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml
@@ -20,6 +20,7 @@ body:
         - area:code
         - area:container
         - area:db
+        - area:deployment
         - area:destination
         - area:device
         - area:disk
diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml
index 311ee512cb..deef5d5aa1 100644
--- a/.github/ISSUE_TEMPLATE/new-conventions.yaml
+++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml
@@ -29,6 +29,7 @@ body:
         - area:code
         - area:container
         - area:db
+        - area:deployment
         - area:destination
         - area:device
         - area:disk
diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md
index a1fb7a30fe..eddd116a5c 100644
--- a/docs/attributes-registry/README.md
+++ b/docs/attributes-registry/README.md
@@ -35,6 +35,7 @@ Currently, the following namespaces exist:
 * [Code](code.md)
 * [Container](container.md)
 * [DB](db.md) (database)
+* [Deployment](deployment.md)
 * [Destination](destination.md)
 * [Device](device.md)
 * [Disk](disk.md)
diff --git a/docs/attributes-registry/deployment.md b/docs/attributes-registry/deployment.md
new file mode 100644
index 0000000000..7e4ad484ed
--- /dev/null
+++ b/docs/attributes-registry/deployment.md
@@ -0,0 +1,16 @@
+# Deployment
+
+## Deployment Attributes
+<!-- semconv registry.deployment(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `deployment.environment` | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` |
+
+**[1]:** `deployment.environment` does not affect the uniqueness constraints defined through
+the `service.namespace`, `service.name` and `service.instance.id` resource attributes.
+This implies that resources carrying the following attribute combinations MUST be
+considered to be identifying the same service:
+
+* `service.name=frontend`, `deployment.environment=production`
+* `service.name=frontend`, `deployment.environment=staging`.
+<!-- endsemconv -->
diff --git a/docs/resource/deployment-environment.md b/docs/resource/deployment-environment.md
index faba4a47d9..12301f3ae5 100644
--- a/docs/resource/deployment-environment.md
+++ b/docs/resource/deployment-environment.md
@@ -9,7 +9,7 @@
 <!-- semconv deployment -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `deployment.environment` | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` | Recommended |
+| [`deployment.environment`](../attributes-registry/deployment.md) | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` | Recommended |
 
 **[1]:** `deployment.environment` does not affect the uniqueness constraints defined through
 the `service.namespace`, `service.name` and `service.instance.id` resource attributes.
diff --git a/model/registry/deployment.yaml b/model/registry/deployment.yaml
new file mode 100644
index 0000000000..ffc0050eab
--- /dev/null
+++ b/model/registry/deployment.yaml
@@ -0,0 +1,22 @@
+groups:
+  - id: registry.deployment
+    prefix: deployment
+    type: attribute_group
+    brief: >
+     This document defines attributes for software deployments.
+    attributes:
+      - id: environment
+        type: string
+        stability: experimental
+        brief: >
+          Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment)
+          (aka deployment tier).
+        note: |
+          `deployment.environment` does not affect the uniqueness constraints defined through
+          the `service.namespace`, `service.name` and `service.instance.id` resource attributes.
+          This implies that resources carrying the following attribute combinations MUST be
+          considered to be identifying the same service:
+
+          * `service.name=frontend`, `deployment.environment=production`
+          * `service.name=frontend`, `deployment.environment=staging`.
+        examples: ['staging', 'production']
diff --git a/model/resource/deployment_environment.yaml b/model/resource/deployment_environment.yaml
index bc2574386a..c9a54bc7fa 100644
--- a/model/resource/deployment_environment.yaml
+++ b/model/resource/deployment_environment.yaml
@@ -1,22 +1,8 @@
 groups:
   - id: deployment
-    prefix: deployment
     type: resource
     brief: >
       The software deployment.
     attributes:
-      - id: environment
-        type: string
-        stability: experimental
-        brief: >
-          Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment)
-          (aka deployment tier).
-        note: |
-          `deployment.environment` does not affect the uniqueness constraints defined through
-          the `service.namespace`, `service.name` and `service.instance.id` resource attributes.
-          This implies that resources carrying the following attribute combinations MUST be
-          considered to be identifying the same service:
-
-          * `service.name=frontend`, `deployment.environment=production`
-          * `service.name=frontend`, `deployment.environment=staging`.
-        examples: ['staging', 'production']
+      - ref: deployment.environment
+        requirement_level: recommended

From 2541b872367cd4ca3119fd71ee2c468e09e4a3d5 Mon Sep 17 00:00:00 2001
From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Date: Wed, 27 Mar 2024 18:14:09 +0100
Subject: [PATCH 15/18] [chore] Move GCP attributes to the registry (#849)

---
 .github/ISSUE_TEMPLATE/bug_report.yaml        |  2 ++
 .github/ISSUE_TEMPLATE/change_proposal.yaml   |  2 ++
 .github/ISSUE_TEMPLATE/new-conventions.yaml   |  2 ++
 docs/attributes-registry/README.md            |  2 ++
 docs/attributes-registry/gcp-cloud-run.md     |  9 +++++++
 docs/attributes-registry/gcp-gce.md           |  9 +++++++
 docs/resource/cloud-provider/gcp/cloud-run.md |  4 +--
 docs/resource/cloud-provider/gcp/gce.md       |  4 +--
 model/registry/gcp-cloud-run.yaml             | 25 +++++++++++++++++++
 model/registry/gcp-gce.yaml                   | 24 ++++++++++++++++++
 .../cloud_provider/gcp/cloud_run.yaml         | 23 +++--------------
 model/resource/cloud_provider/gcp/gce.yaml    | 22 +++-------------
 12 files changed, 87 insertions(+), 41 deletions(-)
 create mode 100644 docs/attributes-registry/gcp-cloud-run.md
 create mode 100644 docs/attributes-registry/gcp-gce.md
 create mode 100644 model/registry/gcp-cloud-run.yaml
 create mode 100644 model/registry/gcp-gce.yaml

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml
index 30d6a421f7..42e2d38a75 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yaml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yaml
@@ -37,6 +37,8 @@ body:
         - area:exception
         - area:faas
         - area:feature-flag
+        - area:gcp-cloud-run
+        - area:gcp-gce
         - area:host
         - area:http
         - area:k8s
diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml
index d47978fd71..b4ba2ee211 100644
--- a/.github/ISSUE_TEMPLATE/change_proposal.yaml
+++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml
@@ -30,6 +30,8 @@ body:
         - area:exception
         - area:faas
         - area:feature-flag
+        - area:gcp-cloud-run
+        - area:gcp-gce
         - area:host
         - area:http
         - area:k8s
diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml
index deef5d5aa1..a289b3b6bd 100644
--- a/.github/ISSUE_TEMPLATE/new-conventions.yaml
+++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml
@@ -39,6 +39,8 @@ body:
         - area:exception
         - area:faas
         - area:feature-flag
+        - area:gcp-cloud-run
+        - area:gcp-gce
         - area:host
         - area:http
         - area:k8s
diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md
index eddd116a5c..8d8cd7e466 100644
--- a/docs/attributes-registry/README.md
+++ b/docs/attributes-registry/README.md
@@ -44,6 +44,8 @@ Currently, the following namespaces exist:
 * [Exception](exception.md)
 * [FaaS](faas.md)
 * [Feature Flag](feature-flag.md)
+* [Google Cloud Run](gcp-cloud-run.md)
+* [Google Compute Engine](gcp-gce.md)
 * [Host](host.md)
 * [HTTP](http.md)
 * [K8s](k8s.md)
diff --git a/docs/attributes-registry/gcp-cloud-run.md b/docs/attributes-registry/gcp-cloud-run.md
new file mode 100644
index 0000000000..219b854ebb
--- /dev/null
+++ b/docs/attributes-registry/gcp-cloud-run.md
@@ -0,0 +1,9 @@
+# Google Cloud Run
+
+## Google Cloud Run Attributes
+<!-- semconv registry.gcp.cloud_run(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `gcp.cloud_run.job.execution` | string | The name of the Cloud Run [execution](https://cloud.google.com/run/docs/managing/job-executions) being run for the Job, as set by the [`CLOUD_RUN_EXECUTION`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) environment variable. | `job-name-xxxx`; `sample-job-mdw84` |
+| `gcp.cloud_run.job.task_index` | int | The index for a task within an execution as provided by the [`CLOUD_RUN_TASK_INDEX`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) environment variable. | `0`; `1` |
+<!-- endsemconv -->
diff --git a/docs/attributes-registry/gcp-gce.md b/docs/attributes-registry/gcp-gce.md
new file mode 100644
index 0000000000..da3b46486d
--- /dev/null
+++ b/docs/attributes-registry/gcp-gce.md
@@ -0,0 +1,9 @@
+# Google Compute Engine
+
+## Google Compute Engine Attributes
+<!-- semconv registry.gcp.gce(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `gcp.gce.instance.hostname` | string | The hostname of a GCE instance. This is the full value of the default or [custom hostname](https://cloud.google.com/compute/docs/instances/custom-hostname-vm). | `my-host1234.example.com`; `sample-vm.us-west1-b.c.my-project.internal` |
+| `gcp.gce.instance.name` | string | The instance name of a GCE instance. This is the value provided by `host.name`, the visible name of the instance in the Cloud Console UI, and the prefix for the default hostname of the instance as defined by the [default internal DNS name](https://cloud.google.com/compute/docs/internal-dns#instance-fully-qualified-domain-names). | `instance-1`; `my-vm-name` |
+<!-- endsemconv -->
diff --git a/docs/resource/cloud-provider/gcp/cloud-run.md b/docs/resource/cloud-provider/gcp/cloud-run.md
index d929928a9a..1f79773078 100644
--- a/docs/resource/cloud-provider/gcp/cloud-run.md
+++ b/docs/resource/cloud-provider/gcp/cloud-run.md
@@ -11,8 +11,8 @@ These conventions are recommended for resources running on Cloud Run.
 <!-- semconv gcp.cloud_run -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `gcp.cloud_run.job.execution` | string | The name of the Cloud Run [execution](https://cloud.google.com/run/docs/managing/job-executions) being run for the Job, as set by the [`CLOUD_RUN_EXECUTION`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) environment variable. | `job-name-xxxx`; `sample-job-mdw84` | Recommended |
-| `gcp.cloud_run.job.task_index` | int | The index for a task within an execution as provided by the [`CLOUD_RUN_TASK_INDEX`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) environment variable. | `0`; `1` | Recommended |
+| [`gcp.cloud_run.job.execution`](../../../attributes-registry/gcp-cloud-run.md) | string | The name of the Cloud Run [execution](https://cloud.google.com/run/docs/managing/job-executions) being run for the Job, as set by the [`CLOUD_RUN_EXECUTION`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) environment variable. | `job-name-xxxx`; `sample-job-mdw84` | Recommended |
+| [`gcp.cloud_run.job.task_index`](../../../attributes-registry/gcp-cloud-run.md) | int | The index for a task within an execution as provided by the [`CLOUD_RUN_TASK_INDEX`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) environment variable. | `0`; `1` | Recommended |
 <!-- endsemconv -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
diff --git a/docs/resource/cloud-provider/gcp/gce.md b/docs/resource/cloud-provider/gcp/gce.md
index 986ce0fbe5..4e2855ed76 100644
--- a/docs/resource/cloud-provider/gcp/gce.md
+++ b/docs/resource/cloud-provider/gcp/gce.md
@@ -7,6 +7,6 @@
 <!-- semconv gcp.gce -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `gcp.gce.instance.hostname` | string | The hostname of a GCE instance. This is the full value of the default or [custom hostname](https://cloud.google.com/compute/docs/instances/custom-hostname-vm). | `my-host1234.example.com`; `sample-vm.us-west1-b.c.my-project.internal` | Recommended |
-| `gcp.gce.instance.name` | string | The instance name of a GCE instance. This is the value provided by `host.name`, the visible name of the instance in the Cloud Console UI, and the prefix for the default hostname of the instance as defined by the [default internal DNS name](https://cloud.google.com/compute/docs/internal-dns#instance-fully-qualified-domain-names). | `instance-1`; `my-vm-name` | Recommended |
+| [`gcp.gce.instance.hostname`](../../../attributes-registry/gcp-gce.md) | string | The hostname of a GCE instance. This is the full value of the default or [custom hostname](https://cloud.google.com/compute/docs/instances/custom-hostname-vm). | `my-host1234.example.com`; `sample-vm.us-west1-b.c.my-project.internal` | Recommended |
+| [`gcp.gce.instance.name`](../../../attributes-registry/gcp-gce.md) | string | The instance name of a GCE instance. This is the value provided by `host.name`, the visible name of the instance in the Cloud Console UI, and the prefix for the default hostname of the instance as defined by the [default internal DNS name](https://cloud.google.com/compute/docs/internal-dns#instance-fully-qualified-domain-names). | `instance-1`; `my-vm-name` | Recommended |
 <!-- endsemconv -->
diff --git a/model/registry/gcp-cloud-run.yaml b/model/registry/gcp-cloud-run.yaml
new file mode 100644
index 0000000000..11b9481feb
--- /dev/null
+++ b/model/registry/gcp-cloud-run.yaml
@@ -0,0 +1,25 @@
+groups:
+  - id: registry.gcp.cloud_run
+    prefix: gcp.cloud_run
+    type: attribute_group
+    brief: >
+      This document defines attributes for Google Cloud Run.
+    attributes:
+      - id: job.execution
+        type: string
+        stability: experimental
+        brief: >
+          The name of the Cloud Run
+          [execution](https://cloud.google.com/run/docs/managing/job-executions)
+          being run for the Job, as set by the
+          [`CLOUD_RUN_EXECUTION`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars)
+          environment variable.
+        examples: ['job-name-xxxx', 'sample-job-mdw84']
+      - id: job.task_index
+        type: int
+        stability: experimental
+        brief: >
+          The index for a task within an execution as provided by the
+          [`CLOUD_RUN_TASK_INDEX`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars)
+          environment variable.
+        examples: [0, 1]
diff --git a/model/registry/gcp-gce.yaml b/model/registry/gcp-gce.yaml
new file mode 100644
index 0000000000..1ca30ee72d
--- /dev/null
+++ b/model/registry/gcp-gce.yaml
@@ -0,0 +1,24 @@
+groups:
+  - id: registry.gcp.gce
+    prefix: gcp.gce
+    type: attribute_group
+    brief: >
+      This document defines attributes for Google Compute Engine (GCE).
+    attributes:
+      - id: instance.name
+        type: string
+        stability: experimental
+        brief: >
+          The instance name of a GCE instance. This is the value
+          provided by `host.name`, the visible name of the instance in
+          the Cloud Console UI, and the prefix for the default
+          hostname of the instance as defined by the [default internal
+          DNS
+          name](https://cloud.google.com/compute/docs/internal-dns#instance-fully-qualified-domain-names).
+        examples: ['instance-1', 'my-vm-name']
+      - id: instance.hostname
+        type: string
+        stability: experimental
+        brief: >
+          The hostname of a GCE instance. This is the full value of the default or [custom hostname](https://cloud.google.com/compute/docs/instances/custom-hostname-vm).
+        examples: ['my-host1234.example.com', 'sample-vm.us-west1-b.c.my-project.internal']
diff --git a/model/resource/cloud_provider/gcp/cloud_run.yaml b/model/resource/cloud_provider/gcp/cloud_run.yaml
index 269f4a6f84..3f05837747 100644
--- a/model/resource/cloud_provider/gcp/cloud_run.yaml
+++ b/model/resource/cloud_provider/gcp/cloud_run.yaml
@@ -1,25 +1,10 @@
 groups:
   - id: gcp.cloud_run
-    prefix: gcp.cloud_run
     type: resource
     brief: >
       Resource used by Google Cloud Run.
     attributes:
-      - id: job.execution
-        type: string
-        stability: experimental
-        brief: >
-          The name of the Cloud Run
-          [execution](https://cloud.google.com/run/docs/managing/job-executions)
-          being run for the Job, as set by the
-          [`CLOUD_RUN_EXECUTION`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars)
-          environment variable.
-        examples: ['job-name-xxxx', 'sample-job-mdw84']
-      - id: job.task_index
-        type: int
-        stability: experimental
-        brief: >
-          The index for a task within an execution as provided by the
-          [`CLOUD_RUN_TASK_INDEX`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars)
-          environment variable.
-        examples: [0, 1]
+      - ref: gcp.cloud_run.job.execution
+        requirement_level: recommended
+      - ref: gcp.cloud_run.job.task_index
+        requirement_level: recommended
diff --git a/model/resource/cloud_provider/gcp/gce.yaml b/model/resource/cloud_provider/gcp/gce.yaml
index 22b96628dc..d29684b2a3 100644
--- a/model/resource/cloud_provider/gcp/gce.yaml
+++ b/model/resource/cloud_provider/gcp/gce.yaml
@@ -1,24 +1,10 @@
 groups:
   - id: gcp.gce
-    prefix: gcp.gce
     type: resource
     brief: >
       Resources used by Google Compute Engine (GCE).
     attributes:
-      - id: instance.name
-        type: string
-        stability: experimental
-        brief: >
-          The instance name of a GCE instance. This is the value
-          provided by `host.name`, the visible name of the instance in
-          the Cloud Console UI, and the prefix for the default
-          hostname of the instance as defined by the [default internal
-          DNS
-          name](https://cloud.google.com/compute/docs/internal-dns#instance-fully-qualified-domain-names).
-        examples: ['instance-1', 'my-vm-name']
-      - id: instance.hostname
-        type: string
-        stability: experimental
-        brief: >
-          The hostname of a GCE instance. This is the full value of the default or [custom hostname](https://cloud.google.com/compute/docs/instances/custom-hostname-vm).
-        examples: ['my-host1234.example.com', 'sample-vm.us-west1-b.c.my-project.internal']
+      - ref: gcp.gce.instance.name
+        requirement_level: recommended
+      - ref: gcp.gce.instance.hostname
+        requirement_level: recommended

From 0e2eca51cdda5bc87c7e54fc9735cbdd2c0e2be2 Mon Sep 17 00:00:00 2001
From: Alexandra Konrad <10500694+trisch-me@users.noreply.github.com>
Date: Thu, 28 Mar 2024 10:34:17 +0100
Subject: [PATCH 16/18] [chore] propagate error up (#841)

Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
---
 internal/tools/scripts/update-issue-template-areas.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/internal/tools/scripts/update-issue-template-areas.sh b/internal/tools/scripts/update-issue-template-areas.sh
index 1e7c7cb276..da2f81ebcf 100755
--- a/internal/tools/scripts/update-issue-template-areas.sh
+++ b/internal/tools/scripts/update-issue-template-areas.sh
@@ -37,7 +37,7 @@ echo -e "The replacement text will be:"
 echo -e "---------------------------------------------\n"
 echo -e $replacement
 
-find ${TEMPLATES_DIR} -type f -name '*.yaml' -exec sed -i "/$START_AREA_LIST/,/$END_AREA_LIST/c\\$replacement" {} \;
+find ${TEMPLATES_DIR} -type f -name '*.yaml'  -print0 | xargs -0 sed -i "/$START_AREA_LIST/,/$END_AREA_LIST/c\\$replacement"
 
 echo -e "\nISSUE_TEMPLATES updated successfully"
 echo -e "---------------------------------------------"

From 5a94098c2a80417f4d5bde58ed470314290ed7da Mon Sep 17 00:00:00 2001
From: Alexandra Konrad <10500694+trisch-me@users.noreply.github.com>
Date: Thu, 28 Mar 2024 10:59:43 +0100
Subject: [PATCH 17/18] add new ECS file namespace (#732)

Co-authored-by: Alexander Wert <AlexanderWert@users.noreply.github.com>
---
 .chloggen/file.yaml                         | 22 ++++++++++++++
 .github/ISSUE_TEMPLATE/bug_report.yaml      |  1 +
 .github/ISSUE_TEMPLATE/change_proposal.yaml |  1 +
 .github/ISSUE_TEMPLATE/new-conventions.yaml |  1 +
 docs/attributes-registry/README.md          |  1 +
 docs/attributes-registry/file.md            | 18 +++++++++++
 model/registry/file.yaml                    | 33 +++++++++++++++++++++
 7 files changed, 77 insertions(+)
 create mode 100755 .chloggen/file.yaml
 create mode 100644 docs/attributes-registry/file.md
 create mode 100644 model/registry/file.yaml

diff --git a/.chloggen/file.yaml b/.chloggen/file.yaml
new file mode 100755
index 0000000000..20bcdca15b
--- /dev/null
+++ b/.chloggen/file.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: new_component
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: file
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add new file namespace
+
+# 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: [732]
+
+# (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:
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml
index 42e2d38a75..de2be6b191 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yaml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yaml
@@ -37,6 +37,7 @@ body:
         - area:exception
         - area:faas
         - area:feature-flag
+        - area:file
         - area:gcp-cloud-run
         - area:gcp-gce
         - area:host
diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml
index b4ba2ee211..5b1f182e55 100644
--- a/.github/ISSUE_TEMPLATE/change_proposal.yaml
+++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml
@@ -30,6 +30,7 @@ body:
         - area:exception
         - area:faas
         - area:feature-flag
+        - area:file
         - area:gcp-cloud-run
         - area:gcp-gce
         - area:host
diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml
index a289b3b6bd..da5ba98845 100644
--- a/.github/ISSUE_TEMPLATE/new-conventions.yaml
+++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml
@@ -39,6 +39,7 @@ body:
         - area:exception
         - area:faas
         - area:feature-flag
+        - area:file
         - area:gcp-cloud-run
         - area:gcp-gce
         - area:host
diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md
index 8d8cd7e466..07c0d1754a 100644
--- a/docs/attributes-registry/README.md
+++ b/docs/attributes-registry/README.md
@@ -44,6 +44,7 @@ Currently, the following namespaces exist:
 * [Exception](exception.md)
 * [FaaS](faas.md)
 * [Feature Flag](feature-flag.md)
+* [File](file.md)
 * [Google Cloud Run](gcp-cloud-run.md)
 * [Google Compute Engine](gcp-gce.md)
 * [Host](host.md)
diff --git a/docs/attributes-registry/file.md b/docs/attributes-registry/file.md
new file mode 100644
index 0000000000..1848908a45
--- /dev/null
+++ b/docs/attributes-registry/file.md
@@ -0,0 +1,18 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+
+# File
+
+## File Attributes
+
+<!-- semconv registry.file(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `file.directory` | string | Directory where the file is located. It should include the drive letter, when appropriate. | `/home/user`; `C:\Program Files\MyApp` |
+| `file.extension` | string | File extension, excluding the leading dot. [1] | `png`; `gz` |
+| `file.name` | string | Name of the file including the extension, without the directory. | `example.png` |
+| `file.path` | string | Full path to the file, including the file name. It should include the drive letter, when appropriate. | `/home/alice/example.png`; `C:\Program Files\MyApp\myapp.exe` |
+| `file.size` | int | File size in bytes. |  |
+
+**[1]:** When the file name has multiple extensions (example.tar.gz), only the last one should be captured ("gz", not "tar.gz").
+<!-- endsemconv -->
diff --git a/model/registry/file.yaml b/model/registry/file.yaml
new file mode 100644
index 0000000000..6a86aa9f9b
--- /dev/null
+++ b/model/registry/file.yaml
@@ -0,0 +1,33 @@
+groups:
+  - id: registry.file
+    prefix: file
+    type: attribute_group
+    brief: "Describes file attributes."
+    attributes:
+      - id: directory
+        type: string
+        brief: >
+          Directory where the file is located. It should include the drive letter, when appropriate.
+        examples: ['/home/user', 'C:\Program Files\MyApp']
+      - id: extension
+        type: string
+        brief: >
+          File extension, excluding the leading dot.
+        examples: ['png', 'gz']
+        note: >
+          When the file name has multiple extensions (example.tar.gz), only the last one should
+          be captured ("gz", not "tar.gz").
+      - id: name
+        type: string
+        brief: >
+          Name of the file including the extension, without the directory.
+        examples: ['example.png']
+      - id: path
+        type: string
+        brief: >
+          Full path to the file, including the file name. It should include the drive letter, when appropriate.
+        examples: ['/home/alice/example.png', 'C:\Program Files\MyApp\myapp.exe']
+      - id: size
+        type: int
+        brief: >
+          File size in bytes.

From e44693245eef815071402b88c3a44a8f7f8f24c8 Mon Sep 17 00:00:00 2001
From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Date: Thu, 28 Mar 2024 18:30:54 +0100
Subject: [PATCH 18/18] [chore] Force create labels in workflow (#852)

---
 .github/workflows/scripts/generate-registry-area-labels.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/scripts/generate-registry-area-labels.sh b/.github/workflows/scripts/generate-registry-area-labels.sh
index e06082e982..3a2af777e6 100755
--- a/.github/workflows/scripts/generate-registry-area-labels.sh
+++ b/.github/workflows/scripts/generate-registry-area-labels.sh
@@ -25,7 +25,7 @@ for AREA in ${AREAS}; do
         continue
     fi
     echo "area:${LABEL_NAME}"
-    gh label create "area:${LABEL_NAME}" -c "#425cc7"
+    gh label create "area:${LABEL_NAME}" -c "#425cc7" --force
 done
 
 echo -e "\nLabels created successfully"