Group yaml files by root namespace instead of signal (#1345)

open-telemetry · Sep 17, 2024 · b855a36 · b855a36
1 parent 422eeb7
commit b855a36
Show file tree

Hide file tree

Showing 181 changed files with 226 additions and 182 deletions.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -16,85 +16,74 @@
 *   @open-telemetry/specs-semconv-maintainers @open-telemetry/specs-semconv-approvers
 
 # Schemas and schema file tooling
-/schemas/                       @open-telemetry/specs-semconv-approvers @tigrannajaryan
-/internal/tools/schema_check.sh @open-telemetry/specs-semconv-approvers @tigrannajaryan
+/schemas/                                 @open-telemetry/specs-semconv-approvers @tigrannajaryan
+/internal/tools/schema_check.sh           @open-telemetry/specs-semconv-approvers @tigrannajaryan
 
-# Logs semantic conventions
-/model/logs/                        @open-telemetry/specs-semconv-approvers @tigrannajaryan
+# Logs and events semantic conventions
 /docs/exceptions/exceptions-logs.md       @open-telemetry/specs-semconv-approvers @tigrannajaryan
 /docs/feature-flags/feature-flags-logs.md @open-telemetry/specs-semconv-approvers @tigrannajaryan
 /docs/general/events-general.md           @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-event-approvers @tigrannajaryan
 /docs/general/logs-general.md             @open-telemetry/specs-semconv-approvers @tigrannajaryan
 /docs/logs/                               @open-telemetry/specs-semconv-approvers @tigrannajaryan
+/model/log/                               @open-telemetry/specs-semconv-approvers @tigrannajaryan
+/model/event/                             @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-event-approvers
 
-# JVM semantic conventions approvers
-/model/metrics/jvm-* @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers
-/docs/jvm/           @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers
+# JVM semantic conventions
+/docs/jvm/                        @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers
+/model/jvm/                       @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers
 
-# HTTP semantic conventions approvers
-/model/metrics/http.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
-/model/trace/http.yaml   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
-/model/registry/http.yaml   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
-/model/registry/server.yaml   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
-/model/registry/client.yaml   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
-/model/registry/network.yaml   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers @open-telemetry/semconv-security-approvers
-/model/registry/error.yaml   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
-/model/registry/url.yaml   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
-/model/registry/user-agent.yaml   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
-/docs/http/   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
+# HTTP semantic conventions
+/docs/http/                       @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
+/model/http/                      @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
+/model/error/                     @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
+/model/client/                    @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
+/model/network/                   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers @open-telemetry/semconv-security-approvers
+/model/server/                    @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
+/model/url/                       @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
+/model/user-agent/                @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
 
-# System semantic conventions approvers
-/docs/system/             @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
-/model/metrics/system-*   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
-/docs/resource/host.md    @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
-/model/resource/host.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
+# System semantic conventions
+/docs/system/                     @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
+/docs/resource/host.md            @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
+/model/host/                      @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
+/model/system/                    @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers
 
-# Mobile semantic conventions approvers
-/docs/mobile/        @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-mobile-approvers
-/model/logs/mobile*  @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-mobile-approvers
+# Mobile semantic conventions
+/docs/mobile/                     @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-mobile-approvers
+/model/device/                    @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-mobile-approvers
 
-# K8s semantic conventions approvers
-/docs/resource/k8s.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers
-/model/resource/k8s.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers
-/model/registry/k8s.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers
+# K8s semantic conventions
+/docs/resource/k8s.md             @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers
+/model/k8s/                       @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers
 
-# Container semantic conventions approvers
-/docs/resource/container.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers
-/model/resource/container.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers
-/model/registry/container.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers
-/model/registry/oci.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers
+# Container semantic conventions
+/docs/resource/container.md       @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers
+/model/container/                 @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers
+/model/oci/                       @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers
 
-# .NET semantic conventions approvers
-/model/metrics/dotnet/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers
-/model/registry/aspnetcore.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers
-/model/registry/signalr.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers
-/docs/dotnet/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers
-/model/metrics/dotnet-metrics.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver
-/model/registry/dotnet.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver
-/docs/runtime/dotnet-metrics.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver
+# .NET semantic conventions
+/docs/dotnet/                     @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers
+/docs/runtime/dotnet-metrics.md   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver
+/model/aspnetcore/                @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers
+/model/dotnet/                    @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers
+/model/signalr/                   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver @open-telemetry/semconv-http-approvers
 
-# Gen-AI semantic conventions approvers
-/model/registry/gen-ai.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-llm-approvers
-/model/metrics/gen-ai.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-llm-approvers
-/model/trace/gen-ai.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-llm-approvers
-/docs/gen-ai/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-llm-approvers
+# Gen-AI semantic conventions
+/docs/gen-ai/                     @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-llm-approvers
+/model/gen-ai/                    @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-llm-approvers
 
-# Security semantic conventions approvers
-/model/registry/file.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
-/model/registry/dns.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
-/model/registry/process.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
-/model/registry/tls.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
-/model/registry/user.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
+# Security semantic conventions
+/model/dns/                       @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
+/model/file/                      @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
+# /model/network/                 is defined in HTTP section
+/model/process/                   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
+/model/tls/                       @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
+/model/user/                      @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
 
-/model/metrics/dns.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
-/model/metrics/process-metrics.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
-/model/resource/process.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
-/model/network.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
-
-# CICD semantic conventions approvers
-/model/registry/artifact.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
-/model/registry/cicd.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
-/model/registry/code.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
-/model/registry/deployment.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
-/model/registry/test.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
-/model/registry/vcs.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
+# CICD semantic conventions
+/model/artifact/                  @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
+/model/cicd/                      @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
+/model/code/                      @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
+/model/deployment/                @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
+/model/test/                      @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
+/model/vcs/                       @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml
@@ -28,8 +28,8 @@ body:
         - area:browser
         - area:cicd
         - area:client
-        - area:cloudevents
         - area:cloud
+        - area:cloudevents
         - area:code
         - area:container
         - area:cpu
@@ -80,8 +80,8 @@ body:
         - area:thread
         - area:tls
         - area:url
-        - area:user-agent
         - area:user
+        - area:user-agent
         - area:v8js
         - area:vcs
         - area:webengine

diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml
@@ -20,8 +20,8 @@ body:
         - area:browser
         - area:cicd
         - area:client
-        - area:cloudevents
         - area:cloud
+        - area:cloudevents
         - area:code
         - area:container
         - area:cpu
@@ -72,8 +72,8 @@ body:
         - area:thread
         - area:tls
         - area:url
-        - area:user-agent
         - area:user
+        - area:user-agent
         - area:v8js
         - area:vcs
         - area:webengine

diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml
@@ -29,8 +29,8 @@ body:
         - area:browser
         - area:cicd
         - area:client
-        - area:cloudevents
         - area:cloud
+        - area:cloudevents
         - area:code
         - area:container
         - area:cpu
@@ -81,8 +81,8 @@ body:
         - area:thread
         - area:tls
         - area:url
-        - area:user-agent
         - area:user
+        - area:user-agent
         - area:v8js
         - area:vcs
         - area:webengine

diff --git a/.github/workflows/generate-registry-area-labels.yml b/.github/workflows/generate-registry-area-labels.yml
@@ -3,9 +3,10 @@ on:
   push:
     branches: [main]
     paths:
-      - model/registry/**
+      - model/**
       - ./.github/workflows/generate-registry-area-labels.yml
       - ./.github/workflows/scripts/generate-registry-area-labels.sh
+
   workflow_dispatch:
 
 jobs:
@@ -14,6 +15,9 @@ jobs:
     if: ${{ github.repository_owner == 'open-telemetry' }}
     steps:
       - uses: actions/checkout@v4
+      - name: Generate registry area labels
+        run: |
+          make generate-gh-issue-templates
 
       - name: Run update permissions
         run: chmod +x ./.github/workflows/scripts/generate-registry-area-labels.sh

diff --git a/.github/workflows/scripts/generate-registry-area-labels.sh b/.github/workflows/scripts/generate-registry-area-labels.sh
@@ -12,21 +12,19 @@
 set -euo pipefail
 
 CUR_DIRECTORY=$(dirname "$0")
-AREAS=$(sh "${CUR_DIRECTORY}/get-registry-areas.sh")
+AREAS=$1
 
 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"
+while IFS= read -r label; do
+    if (( "${#label}" > 50 )); then
+        echo -e "Label $label exceeds GitHubs 50-character limit on labels, skipping"
         continue
     fi
-    echo "area:${LABEL_NAME}"
-    gh label create "area:${LABEL_NAME}" -c "#425cc7" --force
-done
+    echo "$label"
+    gh label create "$label" -c "#425cc7" --force
+done < ${AREAS}
 
 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
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -15,6 +15,7 @@ requirements and recommendations.
 - [How to Contribute](#how-to-contribute)
   - [Prerequisites](#prerequisites)
   - [1. Modify the YAML model](#1-modify-the-yaml-model)
+    - [Code structure](#code-structure)
     - [Schema files](#schema-files)
   - [2. Update the markdown files](#2-update-the-markdown-files)
     - [Hugo frontmatter](#hugo-frontmatter)
@@ -93,6 +94,38 @@ Refer to the
 [Semantic Convention YAML Language](https://github.com/open-telemetry/build-tools/blob/v0.25.0/semantic-conventions/syntax.md)
 to learn how to make changes to the YAML files.
 
+#### Code structure
+
+The YAML (model definition) and Markdown (documentation) files are organized in the following way:
+
+```
+├── docs
+│   ├── attribute_registry
+│   ├── {root-namespace}
+│   │   ├── README.md
+│   │   ├── ....md
+├── model
+│   ├── {root-namespace}
+│   │   ├── events.yaml
+│   │   ├── metrics.yaml
+│   │   ├── registry.yaml
+│   │   ├── resources.yaml
+│   │   ├── spans.yaml
+```
+
+All attributes must be defined in the folder matching their root namespace under
+`/{root-namespace}/*registry.yaml` file.
+
+Corresponding markdown files are auto-generated (see [Update the markdown files](#2-update-the-markdown-files))
+in `/docs/attribute_registry` folder.
+
+All semantic conventions definitions for telemetry signals should be placed under
+`/model/{root-namespace}` and should follow `*{signal}.yaml` pattern. For example,
+HTTP spans are defined in `model/http/spans.yaml`.
+
+YAML definitions could be broken down into multiple files. For example, AWS spans
+are defined in `/model/aws/lambda-spans.yaml` and `/model/aws/sdk-spans.yaml` files.
+
 #### Schema files
 
 When making changes to existing semantic conventions (attributes, metrics, etc)

diff --git a/Makefile b/Makefile
@@ -210,7 +210,19 @@ chlog-update: $(CHLOGGEN)
 # files that have the "area" dropdown field
 .PHONY: generate-gh-issue-templates
 generate-gh-issue-templates:
-	$(TOOLS_DIR)/scripts/update-issue-template-areas.sh
+	mkdir -p $(TOOLS_DIR)/bin
+	docker run --rm \
+	-u $(id -u ${USER}):$(id -g ${USER}) \
+	--mount 'type=bind,source=$(PWD)/internal/tools/scripts,target=/home/weaver/templates,readonly' \
+	--mount 'type=bind,source=$(PWD)/model,target=/home/weaver/source,readonly' \
+	--mount 'type=bind,source=$(TOOLS_DIR)/bin,target=/home/weaver/target' \
+	$(WEAVER_CONTAINER) registry generate \
+		--registry=/home/weaver/source \
+		--templates=/home/weaver/templates \
+		--config=/home/weaver/templates/registry/areas-weaver.yaml \
+		. \
+		/home/weaver/target
+	$(TOOLS_DIR)/scripts/update-issue-template-areas.sh $(PWD)/internal/tools/bin/areas.txt
 
 # A previous iteration of calculating "LATEST_RELEASED_SEMCONV_VERSION"
 # relied on "git describe". However, that approach does not work with

diff --git a/docs/azure/events.md b/docs/azure/events.md
@@ -52,6 +52,6 @@ The event name MUST be `az.resource.log`.
 | `tenant.id` | string | The tenant ID of the Active Directory tenant that this event is tied to. | `607964b6-41a5-4e24-a5db-db7aab3b9b34` | `Conditionally Required`: if the event is tied to an Active Directory tenant. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 <!-- end of manually added table -->
 
-See [Azure Resource Log definition](/model/logs/azure.yaml) for the details.
+See [Azure Resource Log definition](/model/azure/logs.yaml) for the details.
 
 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/internal/tools/scripts/registry/areas-weaver.yaml b/internal/tools/scripts/registry/areas-weaver.yaml
@@ -0,0 +1,13 @@
+templates:
+  - pattern: areas.md.j2
+    filter: >
+      semconv_grouped_attributes({"exclude_deprecated": true}) | .[].root_namespace
+    application_mode: single
+whitespace_control:
+  trim_blocks: true
+  lstrip_blocks: true
+  keep_trailing_newline: true
+text_maps:
+  areas:
+    az: azure
+    hw: hardware
diff --git a/internal/tools/scripts/registry/areas.md.j2 b/internal/tools/scripts/registry/areas.md.j2
@@ -0,0 +1,5 @@
+{{- template.set_file_name("areas.txt") -}}
+
+{% for item in ctx | map('map_text', 'areas') | sort  %}
+area:{{ item | kebab_case }}
+{% endfor %}