Introduce metadata about SIGs and markdown generation (#2648)

Signed-off-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Co-authored-by: Liudmila Molkova <neskazu@gmail.com>
2025-09-05 08:23:59 +02:00 · 2025-09-05 08:23:59 +02:00 · e9f37e2180
parent 5c7d07a147
commit e9f37e2180
8 changed files with 452 additions and 0 deletions
--- a/.github/workflows/checks.yml
+++ b/.github/workflows/checks.yml
@ -126,3 +126,10 @@ jobs:
    - name: find signals defined in yaml files that are not used in the markdown files
      run: make check-dead-yaml

+  areas-table-check:
+    runs-on: ubuntu-latest
+    steps:
+    - name: check out code
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+    - name: check if the areas table is out-of-date
+      run: make areas-table-check
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@ -3,6 +3,9 @@
    "yaml.schemas": {
        "https://raw.githubusercontent.com/open-telemetry/weaver/v0.17.0/schemas/semconv.schema.json": [
            "model/**/*.yaml"
+        ],
+        "./sigs-schema.json": [
+            "sigs.yaml"
        ]
    },
    "json.schemaDownload.enable": true,
--- a/AREAS.md
+++ b/AREAS.md
@ -0,0 +1,50 @@
+# Semantic Convention Areas
+
+Semantic conventions in OpenTelemetry are organized into distinct areas,
+with some of them being overseen by Special Interest Group (SIG).
+
+Non-trivial changes to semantic conventions require the creation of a
+project, which may or may not also require the formation of a SIG.
+
+To learn more about the process of creating a new project and form a SIG,
+refer to the
+[Project Management](https://github.com/open-telemetry/community/blob/main/project-management.md)
+guide in the Community repository.
+
+SIGs have several responsibilities and goals, but their primary focus is to
+define and guide semantic conventions toward stabilization. SIGs that achieve their goal
+may be dissolved, but the codeowner group stays serving as domain experts
+for pull request (PR) reviews and issue triage.
+
+This document provides an overview of the semantic conventions areas, along with
+their owners, related project (and project board) as well as its current status.
+
+<!-- NOTE: THIS TABLE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see internal/tools/scripts/update-sig-table.py -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+<!-- areas -->
+| Name | Owners | Project | Board | Labels | Status | Notes |
+|------|--------|---------|-------|-------|--------|-------|
+| Semantic Conventions: System | [semconv-system-approvers](https://github.com/orgs/open-telemetry/teams/semconv-system-approvers) | https://github.com/open-telemetry/community/blob/main/projects/system-semconv.md | https://github.com/orgs/open-telemetry/projects/55 | `area:system`, `area:host`, `area:process` | `accepting_contributions`, `active` | The SIG is looking for contributions! |
+| Semantic Conventions: K8s | [semconv-k8s-approvers](https://github.com/orgs/open-telemetry/teams/semconv-k8s-approvers) | https://github.com/open-telemetry/community/blob/main/projects/k8s-semconv.md | https://github.com/orgs/open-telemetry/projects/114 | `area:k8s` | `accepting_contributions`, `active` | The SIG is looking for contributions! |
+| Semantic Conventions: GenAI | [semconv-genai-approvers](https://github.com/orgs/open-telemetry/teams/semconv-genai-approvers) | https://github.com/open-telemetry/community/blob/main/projects/gen-ai.md | https://github.com/orgs/open-telemetry/projects/82 | `area:gen-ai`, `area:openai` | `accepting_contributions`, `active` | The SIG is looking for contributions! |
+| Semantic Conventions: CI/CD | [semconv-cicd-approvers](https://github.com/orgs/open-telemetry/teams/semconv-cicd-approvers) | https://github.com/open-telemetry/community/blob/main/projects/ci-cd.md | https://github.com/orgs/open-telemetry/projects/79 | `area:cicd`, `area:artifact`, `area:deployment`, `area:test`, `area:vcs` | `accepting_contributions`, `active` | The SIG is looking for contributions! |
+| Semantic Conventions: Security | [semconv-security-approvers](https://github.com/orgs/open-telemetry/teams/semconv-security-approvers) | https://github.com/open-telemetry/community/blob/main/projects/security-semconv.md | https://github.com/orgs/open-telemetry/projects/104 | `area:security`, `area:log`, `area:user` | `accepting_contributions`, `active` | The SIG is looking for contributions! |
+| Semantic Conventions: Browser Instrumentation | [semconv-browser-approvers](https://github.com/orgs/open-telemetry/teams/semconv-browser-approvers) | https://github.com/open-telemetry/community/blob/main/projects/browser-phase-1.md | https://github.com/orgs/open-telemetry/projects/146 | `area:browser`, `area:enduser`, `area:user`, `area:user-agent` | `accepting_contributions`, `active` | The SIG is looking for contributions! |
+| Semantic Conventions: Client Instrumentation | [semconv-client-approvers](https://github.com/orgs/open-telemetry/teams/semconv-client-approvers) | https://github.com/open-telemetry/community/blob/main/projects/client-instrumentation.md | https://github.com/orgs/open-telemetry/projects/19 | `area:client`, `area:event` | `accepting_contributions`, `active` | The SIG is looking for contributions! |
+| Semantic Conventions: Resources and Entities | [specs-semconv-maintainers](https://github.com/orgs/open-telemetry/teams/specs-semconv-maintainers) | https://github.com/open-telemetry/community/blob/main/projects/resources-and-entities.md | https://github.com/orgs/open-telemetry/projects/85 | `area:entities` | `accepting_contributions`, `active` | The SIG is looking for contributions! |
+| Semantic Conventions: Messaging | [semconv-messaging-approvers](https://github.com/orgs/open-telemetry/teams/semconv-messaging-approvers) | https://github.com/open-telemetry/community/blob/main/projects/currently-inactive/messaging-semconv.md | https://github.com/orgs/open-telemetry/projects/20 | `area:messaging` | `inactive`, `needs_staffing` | The SIG is inactive. If you have interest in working towards messaging stabilization, consider proposing a [project update](https://github.com/open-telemetry/community/blob/main/projects/currently-inactive/messaging-semconv.md) |
+| Semantic Conventions: HTTP | [semconv-http-approvers](https://github.com/orgs/open-telemetry/teams/semconv-http-approvers) | https://github.com/open-telemetry/community/blob/main/projects/completed-projects/http.md | https://github.com/orgs/open-telemetry/projects/41 | `area:http` | `inactive` | The SIG is inactive. Bugs and bugfixes are welcome. For substantial changes, follow the [new project process](https://github.com/open-telemetry/community/blob/main/project-management.md) |
+| Semantic Conventions: Database | [semconv-db-approvers](https://github.com/orgs/open-telemetry/teams/semconv-db-approvers) | https://github.com/open-telemetry/community/blob/main/projects/completed-projects/database-client-semconv.md | https://github.com/orgs/open-telemetry/projects/73 | `area:db` | `inactive` | The SIG is inactive. Bugs and bugfixes are welcome. For substantial changes, follow the [new project process](https://github.com/open-telemetry/community/blob/main/project-management.md) |
+| Semantic Conventions: FaaS | [specs-semconv-maintainers](https://github.com/orgs/open-telemetry/teams/specs-semconv-maintainers) | https://github.com/open-telemetry/community/blob/main/projects/completed-projects/faas.md | N/A | `area:faas` | `inactive` | The SIG is inactive. Bugs and bugfixes are welcome. For substantial changes, follow the [new project process](https://github.com/open-telemetry/community/blob/main/project-management.md) |
+| Semantic Conventions: JVM | [semconv-jvm-approvers](https://github.com/orgs/open-telemetry/teams/semconv-jvm-approvers) | N/A | https://github.com/orgs/open-telemetry/projects/49 | `area:jvm` | `inactive` | The SIG is inactive. Bugs and bugfixes are welcome. For substantial changes, follow the [new project process](https://github.com/open-telemetry/community/blob/main/project-management.md) |
+| Semantic Conventions: Logs | [semconv-log-approvers](https://github.com/orgs/open-telemetry/teams/semconv-log-approvers) | N/A | N/A | `area:log` | `accepting_contributions`, `active` | The SIG is looking for contributions! |
+| Semantic Conventions: Mainframe | [sig-mainframe-approvers](https://github.com/orgs/open-telemetry/teams/sig-mainframe-approvers) | https://github.com/open-telemetry/community/blob/main/projects/mainframe.md | N/A | `area:mainframe` | `accepting_contributions`, `active` | The SIG is looking for contributions! |
+| Semantic Conventions: Profiling | [profiling-approvers](https://github.com/orgs/open-telemetry/teams/profiling-approvers) | N/A | N/A | `area:profile` | `accepting_contributions`, `active` | The SIG is looking for contributions! |
+| Semantic Conventions: .NET | [semconv-dotnet-approver](https://github.com/orgs/open-telemetry/teams/semconv-dotnet-approver) | N/A | N/A | `area:dotnet`, `area:aspnetcore` | `accepting_contributions`, `active` | SIG is driven by members of the .NET runtime team. Contributions are welcomed but must be aligned with the .NET runtime features/roadmap |
+<!-- endareas -->
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
--- a/8
+++ b/8
@ -335,3 +335,11 @@ generate-schema-next:
 		--output /home/weaver/target
 		# --param next_version=$(NEXT_SEMCONV_VERSION)
 	$(TOOLS_DIR)/scripts/generate-schema-next.sh $(NEXT_SEMCONV_VERSION) $(LATEST_RELEASED_SEMCONV_VERSION) $(TOOLS_DIR)/bin/schema-diff.yaml
+
+.PHONY: areas-table-generation
+areas-table-generation:
+	docker run --rm -v ${PWD}:/repo -w /repo python:3-alpine python internal/tools/scripts/update-areas-table.py --install;
+
+.PHONY: areas-table-check
+areas-table-check:
+	docker run --rm -v ${PWD}:/repo -w /repo python:3-alpine python internal/tools/scripts/update-areas-table.py --install --check;
--- a/README.md
+++ b/README.md
@ -12,6 +12,10 @@ provide meaning to data when collecting, producing and consuming it.
 The human-readable version of the semantic conventions resides in the [docs](docs/README.md) folder.
 Major parts of these Markdown documents are generated from the YAML definitions located in the [model](model/README.md) folder.

+## Areas and Special Interest Groups
+
+See: [Areas](AREAS.md)
+
 ## Contributing

 See [CONTRIBUTING.md](CONTRIBUTING.md)
--- a/areas.yaml
+++ b/areas.yaml
@ -0,0 +1,217 @@
+areas:
+  - name: "Semantic Conventions: System"
+    owner:
+      - name: "semconv-system-approvers"
+        github: semconv-system-approvers
+    project: "https://github.com/open-telemetry/community/blob/main/projects/system-semconv.md"
+    board: "https://github.com/orgs/open-telemetry/projects/55"
+    labels:
+      - area:system
+      - area:host
+      - area:process
+    status:
+      - accepting_contributions
+      - active
+
+  - name: "Semantic Conventions: K8s"
+    owner:
+      - name: "semconv-k8s-approvers"
+        github: semconv-k8s-approvers
+    project: "https://github.com/open-telemetry/community/blob/main/projects/k8s-semconv.md"
+    board: "https://github.com/orgs/open-telemetry/projects/114"
+    labels:
+      - area:k8s
+    status:
+      - accepting_contributions
+      - active
+
+  - name: "Semantic Conventions: GenAI"
+    owner:
+      - name: "semconv-genai-approvers"
+        github: semconv-genai-approvers
+    project: "https://github.com/open-telemetry/community/blob/main/projects/gen-ai.md"
+    board: "https://github.com/orgs/open-telemetry/projects/82"
+    labels:
+      - area:gen-ai
+      - area:openai
+    status:
+      - accepting_contributions
+      - active
+
+  - name: "Semantic Conventions: CI/CD"
+    owner:
+      - name: "semconv-cicd-approvers"
+        github: semconv-cicd-approvers
+    project: "https://github.com/open-telemetry/community/blob/main/projects/ci-cd.md"
+    board: "https://github.com/orgs/open-telemetry/projects/79"
+    labels:
+      - area:cicd
+      - area:artifact
+      - area:deployment
+      - area:test
+      - area:vcs
+    status:
+      - accepting_contributions
+      - active
+
+  - name: "Semantic Conventions: Security"
+    owner:
+      - name: "semconv-security-approvers"
+        github: semconv-security-approvers
+    project: "https://github.com/open-telemetry/community/blob/main/projects/security-semconv.md"
+    board: "https://github.com/orgs/open-telemetry/projects/104"
+    labels:
+      - area:security
+      - area:log
+      - area:user
+    status:
+      - accepting_contributions
+      - active
+
+  - name: "Semantic Conventions: Browser Instrumentation"
+    owner:
+      - name: "semconv-browser-approvers"
+        github: semconv-browser-approvers
+    project: "https://github.com/open-telemetry/community/blob/main/projects/browser-phase-1.md"
+    board: "https://github.com/orgs/open-telemetry/projects/146"
+    labels:
+      - area:browser
+      - area:enduser
+      - area:user
+      - area:user-agent
+    status:
+      - accepting_contributions
+      - active
+
+  - name: "Semantic Conventions: Client Instrumentation"
+    owner:
+      - name: "semconv-client-approvers"
+        github: semconv-client-approvers
+    project: "https://github.com/open-telemetry/community/blob/main/projects/client-instrumentation.md"
+    board: "https://github.com/orgs/open-telemetry/projects/19"
+    labels:
+      - area:client
+      - area:event
+    status:
+      - accepting_contributions
+      - active
+
+  - name: "Semantic Conventions: Resources and Entities"
+    owner:
+      - name: "specs-semconv-maintainers" # TODO: Missing team user for entities?
+        github: specs-semconv-maintainers
+    project: "https://github.com/open-telemetry/community/blob/main/projects/resources-and-entities.md"
+    board: "https://github.com/orgs/open-telemetry/projects/85"
+    labels:
+      - area:entities
+    status:
+      - accepting_contributions
+      - active
+
+  - name: "Semantic Conventions: Messaging"
+    owner:
+      - name: "semconv-messaging-approvers"
+        github: semconv-messaging-approvers
+    project: "https://github.com/open-telemetry/community/blob/main/projects/currently-inactive/messaging-semconv.md"
+    board: "https://github.com/orgs/open-telemetry/projects/20"
+    labels:
+      - area:messaging
+    status:
+      - inactive
+      - needs_staffing
+    notes: >
+      The SIG is inactive. If you have interest in working towards messaging stabilization,
+      consider proposing a [project update](https://github.com/open-telemetry/community/blob/main/projects/currently-inactive/messaging-semconv.md)
+
+  - name: "Semantic Conventions: HTTP"
+    owner:
+      - name: "semconv-http-approvers"
+        github: semconv-http-approvers
+    project: "https://github.com/open-telemetry/community/blob/main/projects/completed-projects/http.md"
+    board: "https://github.com/orgs/open-telemetry/projects/41"
+    labels:
+      - area:http
+    status:
+      - inactive
+  - name: "Semantic Conventions: Database"
+    owner:
+      - name: "semconv-db-approvers"
+        github: semconv-db-approvers
+    project: "https://github.com/open-telemetry/community/blob/main/projects/completed-projects/database-client-semconv.md"
+    board: "https://github.com/orgs/open-telemetry/projects/73"
+    labels:
+      - area:db
+    status:
+      - inactive
+
+  - name: "Semantic Conventions: FaaS"
+    owner:
+      - name: "specs-semconv-maintainers" # TODO: Missing team user for faas?
+        github: specs-semconv-maintainers
+    project: "https://github.com/open-telemetry/community/blob/main/projects/completed-projects/faas.md"
+    board: "N/A"
+    labels:
+      - area:faas
+    status:
+      - inactive
+
+  - name: "Semantic Conventions: JVM"
+    owner:
+      - name: "semconv-jvm-approvers"
+        github: semconv-jvm-approvers
+    project: "N/A"
+    board: "https://github.com/orgs/open-telemetry/projects/49"
+    labels:
+      - area:jvm
+    status:
+      - inactive
+
+  - name: "Semantic Conventions: Logs"
+    owner:
+      - name: "semconv-log-approvers"
+        github: semconv-log-approvers
+    project: "N/A"
+    board: "N/A"
+    labels:
+      - area:log
+    status:
+      - accepting_contributions
+      - active
+
+  - name: "Semantic Conventions: Mainframe"
+    owner:
+      - name: "sig-mainframe-approvers"
+        github: sig-mainframe-approvers
+    project: "https://github.com/open-telemetry/community/blob/main/projects/mainframe.md"
+    board: "N/A"
+    labels:
+      - area:mainframe
+    status:
+      - accepting_contributions
+      - active
+
+  - name: "Semantic Conventions: Profiling"
+    owner:
+      - name: "profiling-approvers"
+        github: profiling-approvers
+    project: "N/A"
+    board: "N/A"
+    labels:
+      - area:profile
+    status:
+      - accepting_contributions
+      - active
+
+  - name: "Semantic Conventions: .NET"
+    owner:
+      - name: "semconv-dotnet-approver"
+        github: semconv-dotnet-approver
+    project: "N/A"
+    board: "N/A"
+    labels:
+      - area:dotnet
+      - area:aspnetcore
+    status:
+      - accepting_contributions
+      - active
+    notes: "SIG is driven by members of the .NET runtime team. Contributions are welcomed but must be aligned with the .NET runtime features/roadmap"
--- a/internal/tools/scripts/update-areas-table.py
+++ b/internal/tools/scripts/update-areas-table.py
@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+import subprocess
+import sys
+
+# in the Makefile we use a unmodified python container to run this script, so we need to install pyyaml if it's not already installed
+if (len(sys.argv) > 1) and (sys.argv[1] == "--install"):
+    subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'pyyaml', '--root-user-action=ignore'])
+    sys.argv = sys.argv[1:]
+
+import yaml
+
+# Do not safe the file but verify that it is different from the original one.
+run_in_check_mode = (len(sys.argv) > 1) and (sys.argv[1] == "--check")
+
+# Define the YAML input file and the markdown file to be updated
+yaml_input = "areas.yaml"
+markdown_file = "AREAS.md"
+
+# Define the markers
+start_marker = "<!-- areas -->"
+end_marker = "<!-- endareas -->"
+
+# Read the YAML file
+with open(yaml_input, 'r') as file:
+    data = yaml.safe_load(file)
+
+# Extract the top and bottom parts of the existing markdown file
+with open(markdown_file, 'r') as file:
+    content = file.read()
+    top_part, bottom_part = content.split(start_marker, 1)[0], content.split(end_marker, 1)[1]
+
+# Generate the markdown content for each AREA group
+markdown_content = start_marker + '\n'
+markdown_content += "| Name | Owners | Project | Board | Labels | Status | Notes |\n"
+markdown_content += "|------|--------|---------|-------|-------|--------|-------|\n"
+
+for area in data['areas']:
+    name = area['name']
+    project = area['project']
+    board = area['board']
+
+    owners = ",<br/>".join(
+        [
+            f"[{owner['name']}](https://github.com/orgs/open-telemetry/teams/{owner['github']})"
+            for owner in area.get('owner', [])
+            if owner.get('name') and owner.get('github')
+        ]
+    )
+
+    labels = ", ".join(
+        [f"`{label}`"
+         for label in area.get('labels', [])
+         if label]
+    )
+
+    status = ", ".join(
+        [f"`{s}`"
+         for s in area.get('status', [])
+         if s]
+    )
+
+    # Add a default note for common states
+    if area.get('notes'):
+        notes = " ".join(area['notes'].split())
+    elif not area.get('notes') and 'inactive' in status:
+        notes = "The SIG is inactive. Bugs and bugfixes are welcome. For substantial changes, follow the [new project process](https://github.com/open-telemetry/community/blob/main/project-management.md)"
+    elif not area.get('notes') and 'accepting_contributions' in status:
+        notes = "The SIG is looking for contributions!"
+
+    markdown_content += f"| {name} | {owners} | {project} | {board} | {labels} | {status} | {notes} |\n"
+
+markdown_content += end_marker
+
+result = top_part + markdown_content + bottom_part
+
+if run_in_check_mode:
+    with open(markdown_file, 'r') as file:
+        original = file.read()
+    if original == result:
+        sys.exit(0)
+    else:
+        print("AREAS.md is outdated. Run make areas-table-generation to update")
+        sys.exit(1)
+else:
+    # Write the updated markdown content to file
+    with open(markdown_file, 'w') as file:
+        file.write(top_part)
+        file.write(markdown_content)
+        file.write(bottom_part)
+
+# Inform the user that the markdown file has been updated
+print("The markdown file has been updated with the new area tables.")
--- a/sigs-schema.json
+++ b/sigs-schema.json
@ -0,0 +1,71 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "areas": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "The name of the SIG."
+          },
+          "owner": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "description": "The name of the owner (team user)."
+                },
+                "github": {
+                  "type": "string",
+                  "description": "The GitHub handle of the owner (team user)."
+                }
+              },
+              "required": ["name", "github"]
+            },
+            "description": "List of owners for the SIG, which can include individuals or teams."
+          },
+          "project": {
+            "type": "string",
+            "format": "uri",
+            "description": "The URL of the project associated with the SIG, which must be defined in the OpenTelemetry community repository."
+          },
+          "status": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "enum": [
+                "needs_staffing",
+                "not_accepting_changes",
+                "accepting_contributions",
+                "active",
+                "inactive"
+              ]
+            },
+            "description": "A list of predefined labels representing the SIG's state or needs."
+          },
+          "labels": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "description": "Labels representing the areas this SIG is responsible for (e.g., area:k8s, area:database)."
+            },
+            "description": "A list of areas assigned to the SIG. Used for automation and context mapping."
+          },
+          "notes": {
+            "type": "string",
+            "description": "Additional notes about the SIG."
+          }
+        },
+        "required": ["name", "labels", "status"]
+      }
+    }
+  },
+  "required": ["areas"]
+}