Skip to content

Commit

Permalink
Generate Attribute Registry using Weaver (#917)
Browse files Browse the repository at this point in the history
  • Loading branch information
jsuereth authored May 1, 2024
1 parent 48f50d7 commit 651d779
Show file tree
Hide file tree
Showing 140 changed files with 3,339 additions and 2,551 deletions.
18 changes: 18 additions & 0 deletions .chloggen/917.yaml
Original file line number Diff line number Diff line change
@@ -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.
13 changes: 0 additions & 13 deletions .github/CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
1 change: 1 addition & 0 deletions .markdownlint.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,4 @@ ol-prefix:
style: ordered
no-inline-html: false
fenced-code-language: false
no-space-in-code: false
3 changes: 3 additions & 0 deletions .prettierignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,8 @@
/docs/**
!/docs/cloud*
!/docs/cloud*/**
!/docs/attributes-registry*
!/docs/attributes-registry*/**
/model
/schemas
CHANGELOG.md
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
30 changes: 25 additions & 5 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
105 changes: 57 additions & 48 deletions docs/attributes-registry/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
40 changes: 21 additions & 19 deletions docs/attributes-registry/android.md
Original file line number Diff line number Diff line change
@@ -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 -->
Loading

0 comments on commit 651d779

Please sign in to comment.