Generate Attribute Registry using Weaver (#917)

Author: jsuereth

.chloggen/917.yaml

@@ -0,0 +1,18 @@
+change_type: enhancement
+component: all
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Migrate Attribute Registry to be completely autogenerated.
+
+# 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: [197]
+
+# (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: |
+  Migrate to using weaver for markdown generation (snippet + registry).
+  The entirety of the registry now is generated using weaver with templates
+  under the `templates/` directory.  Snippets still require a hardcoded
+  command.

.github/CODEOWNERS

@@ -42,13 +42,6 @@
 /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
-/docs/attribute-registry/http.md   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
-/docs/attribute-registry/server.md   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
-/docs/attribute-registry/client.md   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
-/docs/attribute-registry/network.md   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
-/docs/attribute-registry/error.md   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
-/docs/attribute-registry/url.md   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
-/docs/attribute-registry/user-agent.md   @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
@@ -62,14 +55,11 @@
 
 # K8s semantic conventions approvers
 /docs/resource/k8s.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers
-/docs/attributes-registry/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
 
 # Container semantic conventions approvers
 /docs/resource/container.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers
-/docs/attributes-registry/container.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers
-/docs/attributes-registry/oci.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
@@ -79,14 +69,11 @@
 /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
-/docs/attributes-registry/aspnetcore.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-dotnet-approver  @open-telemetry/semconv-http-approvers
-/docs/attributes-registry/signalr.md @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
-/docs/attributes-registry/llm.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-llm-approvers
 
 # TODO - Add semconv area experts

.markdownlint.yaml

@@ -12,3 +12,4 @@ ol-prefix:
   style: ordered
 no-inline-html: false
 fenced-code-language: false
+no-space-in-code: false

.prettierignore

@@ -5,5 +5,8 @@
 /docs/**
 !/docs/cloud*
 !/docs/cloud*/**
+!/docs/attributes-registry*
+!/docs/attributes-registry*/**
 /model
 /schemas
+CHANGELOG.md

CONTRIBUTING.md

@@ -103,10 +103,10 @@ You can also take examples from past changes inside the `schemas` folder.
 ### 2. Update the markdown files
 
 After updating the YAML file(s), you need to update
-the respective markdown files. For this, run the following command:
+the respective markdown files. For this, run the following commands:
 
 ```bash
-make table-generation
+make table-generation attribute-registry-generation
 ```
 
 #### Hugo frontmatter

Makefile

@@ -14,6 +14,7 @@ CHLOGGEN_CONFIG  := .chloggen/config.yaml
 # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates
 # Keep links in model/README.md and .vscode/settings.json in sync!
 SEMCONVGEN_VERSION=0.24.0
+WEAVER_VERSION=latest
 
 # TODO: add `yamllint` step to `all` after making sure it works on Mac.
 .PHONY: all
@@ -95,13 +96,31 @@ yamllint:
 .PHONY: table-generation
 table-generation:
 	docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec \
-		otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec
+		otel/weaver:${WEAVER_VERSION} registry update-markdown \
+		--registry=/source \
+		--attribute-registry-base-url="/docs/attributes-registry" \
+		/spec
+
+# Generate attribute registry markdown.
+.PHONY: attribute-registry-generation
+attribute-registry-generation:
+	docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec -v $(PWD)/templates:/weaver/templates \
+		otel/weaver:${WEAVER_VERSION} registry generate \
+		  --registry=/source \
+		  --templates=/weaver/templates \
+		  markdown \
+		  /spec/attributes-registry/
+	npm run fix:format
 
-# Check if current markdown tables differ from the ones that would be generated from YAML definitions
+# Check if current markdown tables differ from the ones that would be generated from YAML definitions (weaver).
 .PHONY: table-check
 table-check:
 	docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec \
-		otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec --md-check
+		otel/weaver:${WEAVER_VERSION} registry update-markdown \
+		--registry=/source \
+		--attribute-registry-base-url="/docs/attributes-registry" \
+		--dry-run \
+		/spec
 
 LATEST_RELEASED_SEMCONV_VERSION := $(shell git describe --tags --abbrev=0 | sed 's/v//g')
 .PHONY: compatibility-check
@@ -122,14 +141,15 @@ fix-format:
 	npm run fix:format
 
 # Run all checks in order of speed / likely failure.
+# As a last thing, run attribute registry generation and git-diff for differences.
 .PHONY: check
-check: misspell markdownlint check-format markdown-toc compatibility-check markdown-link-check
+check: misspell markdownlint check-format markdown-toc compatibility-check markdown-link-check attribute-registry-generation
 	git diff --exit-code ':*.md' || (echo 'Generated markdown Table of Contents is out of date, please run "make markdown-toc" and commit the changes in this PR.' && exit 1)
 	@echo "All checks complete"
 
 # Attempt to fix issues / regenerate tables.
 .PHONY: fix
-fix: table-generation misspell-correction fix-format markdown-toc
+fix: table-generation attribute-registry-generation misspell-correction fix-format markdown-toc
 	@echo "All autofixes complete"
 
 .PHONY: install-tools

docs/attributes-registry/README.md

@@ -3,7 +3,10 @@ linkTitle: Registry
 weight: -2
 --->
 
-# Attributes Registry
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/readme.md.j2 -->
+
+# Attribute Registry
 
 The attributes registry is the place where attributes are defined. An attribute definition covers the following properties of an attribute:
 
@@ -28,52 +31,58 @@ All registered attributes are listed by namespace in this registry.
 
 Currently, the following namespaces exist:
 
-* [Android](android.md)
-* [AWS](aws.md)
-* [Browser](browser.md)
-* [Client](client.md)
-* [Cloud](cloud.md)
-* [CloudEvents](cloudevents.md)
-* [Code](code.md)
-* [Container](container.md)
-* [DB](db.md) (database)
-* [Deployment](deployment.md)
-* [Destination](destination.md)
-* [Device](device.md)
-* [Disk](disk.md)
-* [End user](enduser.md)
-* [Error](error.md)
-* [Event](event.md)
-* [Exception](exception.md)
-* [FaaS](faas.md)
-* [Feature Flag](feature-flag.md)
-* [File](file.md)
-* [Google Cloud Platform (GCP)](gcp.md)
-* [GraphQl](graphql.md)
-* [Heroku](heroku.md)
-* [Host](host.md)
-* [HTTP](http.md)
-* [iOS](ios.md)
-* [JVM](jvm.md)
-* [K8s](k8s.md)
-* [Log](log.md)
-* [Network](network.md)
-* [OCI](oci.md)
-* [OpenTelemetry](otel.md)
-* [OpenTracing](opentracing.md)
-* [OS](os.md)
-* [Peer](peer.md)
-* [Process](process.md)
-* [RPC](rpc.md)
-* [Server](server.md)
-* [Service](service.md)
-* [Session](session.md)
-* [Source](source.md)
-* [Telemetry](telemetry.md)
-* [Thread](thread.md)
-* [TLS](tls.md)
-* [URL](url.md)
-* [User agent](user-agent.md)
-* [Webengine](webengine.md)
+- [Android](android.md)
+- [Aspnetcore](aspnetcore.md)
+- [AWS](aws.md)
+- [Browser](browser.md)
+- [Client](client.md)
+- [Cloud](cloud.md)
+- [CloudEvents](cloudevents.md)
+- [Code](code.md)
+- [Container](container.md)
+- [Db](db.md)
+- [Deployment](deployment.md)
+- [Destination](destination.md)
+- [Device](device.md)
+- [Disk](disk.md)
+- [Dns](dns.md)
+- [Enduser](enduser.md)
+- [Error](error.md)
+- [Event](event.md)
+- [Exception](exception.md)
+- [Faas](faas.md)
+- [Feature Flag](feature-flag.md)
+- [File](file.md)
+- [GCP](gcp.md)
+- [Gen AI](gen-ai.md)
+- [GraphQL](graphql.md)
+- [Heroku](heroku.md)
+- [Host](host.md)
+- [HTTP](http.md)
+- [iOS](ios.md)
+- [JVM](jvm.md)
+- [K8s](k8s.md)
+- [Log](log.md)
+- [Messaging](messaging.md)
+- [Network](network.md)
+- [OCI](oci.md)
+- [OpenTracing](opentracing.md)
+- [OS](os.md)
+- [OTel](otel.md)
+- [Peer](peer.md)
+- [Process](process.md)
+- [RPC](rpc.md)
+- [Server](server.md)
+- [Service](service.md)
+- [Session](session.md)
+- [SignalR](signalr.md)
+- [Source](source.md)
+- [System](system.md)
+- [Telemetry](telemetry.md)
+- [Thread](thread.md)
+- [TLS](tls.md)
+- [URL](url.md)
+- [User Agent](user-agent.md)
+- [Webengine](webengine.md)
 
 [developers recommendations]: ../general/attribute-naming.md#recommendations-for-application-developers

docs/attributes-registry/android.md

@@ -1,34 +1,36 @@
-# Android
+<!--- Hugo front matter used to generate the website version of this page:
+--->
 
-<!-- toc -->
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
 
-- [Android Attributes](#android-attributes)
-- [Deprecated Android Attributes](#deprecated-android-attributes)
+# Android
 
-<!-- tocstop -->
+- [Android](#android-attributes)
+- [Android Deprecated](#android-deprecated-attributes)
 
 ## Android Attributes
 
-<!-- semconv registry.android(omit_requirement_level) -->
-| Attribute  | Type | Description  | Examples  | Stability |
-|---|---|---|---|---|
+The Android platform on which the Android application is running.
+
+| Attribute              | Type   | Description                                                                                                                                                                                                                               | Examples   | Stability                                                        |
+| ---------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------- |
 | `android.os.api_level` | string | Uniquely identifies the framework API revision offered by a version (`os.version`) of the android operating system. More information can be found [here](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels). | `33`; `32` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-<!-- endsemconv -->
 
-## Deprecated Android Attributes
+## Android Deprecated Attributes
+
+This document defines attributes that represents an occurrence of a lifecycle transition on the Android platform.
 
-<!-- semconv registry.android.deprecated(omit_requirement_level) -->
-| Attribute  | Type | Description  | Examples  | Stability |
-|---|---|---|---|---|
-| `android.state` | string | Deprecated use the `device.app.lifecycle` event definition including `android.state` as a payload field instead. [1] | `created` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| Attribute       | Type   | Description                                                                                                          | Examples                              | Stability                                                        |
+| --------------- | ------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------- |
+| `android.state` | string | Deprecated use the `device.app.lifecycle` event definition including `android.state` as a payload field instead. [1] | `created`; `background`; `foreground` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[1]:** The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived.
 
 `android.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 | Stability |
-|---|---|---|
-| `created` | Any time before Activity.onResume() or, if the app has no Activity, Context.startService() has been called in the app for the first time. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `background` | Any time after Activity.onPause() or, if the app has no Activity, Context.stopService() has been called when the app was in the foreground state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| Value        | Description                                                                                                                                                            | Stability                                                        |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `created`    | Any time before Activity.onResume() or, if the app has no Activity, Context.startService() has been called in the app for the first time.                              | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `background` | Any time after Activity.onPause() or, if the app has no Activity, Context.stopService() has been called when the app was in the foreground state.                      | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `foreground` | Any time after Activity.onResume() or, if the app has no Activity, Context.startService() has been called when the app was in either the created or background states. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-<!-- endsemconv -->