From 447b69430d4b76603111ad02bdd57f5e43538719 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 29 May 2025 18:46:37 -0700 Subject: [PATCH 1/4] Detect yaml groups that are not used in md files --- .github/workflows/checks.yml | 8 ++++ Makefile | 15 ++++++ docs/resource/app.md | 42 ++++++++++++++++ docs/resource/otel.md | 24 ++++++++++ docs/system/system-metrics.md | 25 ++++++++++ internal/tools/scripts/find-dead-yaml.sh | 48 +++++++++++++++++++ .../registry/signal-groups-weaver.yaml | 12 +++++ .../tools/scripts/registry/signal-groups.j2 | 5 ++ 8 files changed, 179 insertions(+) create mode 100644 docs/resource/app.md create mode 100644 docs/resource/otel.md create mode 100644 internal/tools/scripts/find-dead-yaml.sh create mode 100644 internal/tools/scripts/registry/signal-groups-weaver.yaml create mode 100644 internal/tools/scripts/registry/signal-groups.j2 diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index d84da552f4..84aeda4f41 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -126,3 +126,11 @@ jobs: - name: verify semantic conventions yaml definitions run: make test-policies + dead-yaml-check: + runs-on: ubuntu-latest + steps: + - name: check out code + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + - name: find signals defined in yaml files that are not used in the markdown files + run: make check-dead-yaml + diff --git a/Makefile b/Makefile index 81f16f0b85..c5b051e673 100644 --- a/Makefile +++ b/Makefile @@ -334,3 +334,18 @@ test-policies: /policies \ /policies_test +.PHONY: check-dead-yaml +check-dead-yaml: + mkdir -p $(TOOLS_DIR)/bin + $(DOCKER_RUN) --rm \ + $(DOCKER_USER_IS_HOST_USER_ARG) \ + --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/signal-groups-weaver.yaml \ + . \ + /home/weaver/target + $(TOOLS_DIR)/scripts/find-dead-yaml.sh $(PWD)/internal/tools/bin/signal-groups.txt $(PWD)/docs \ No newline at end of file diff --git a/docs/resource/app.md b/docs/resource/app.md new file mode 100644 index 0000000000..4dc2e336a3 --- /dev/null +++ b/docs/resource/app.md @@ -0,0 +1,42 @@ +# App + + + + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**type:** `app` + +**Description:** An app used directly by end users — like mobile, web, or desktop. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`app.installation.id`](/docs/registry/attributes/app.md) | string | A unique identifier representing the installation of an application on a specific device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `app.installation.id`:** Its value SHOULD persist across launches of the same application installation, including through application upgrades. +It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. +Additionally, users might be able to reset this value (e.g. by clearing application data). +If an app is installed multiple times on the same device (e.g. in different accounts on Android), each `app.installation.id` SHOULD have a different value. +If multiple OpenTelemetry SDKs are used within the same application, they SHOULD use the same value for `app.installation.id`. +Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the `app.installation.id`. + +For iOS, this value SHOULD be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor). + +For Android, examples of `app.installation.id` implementations include: + +- [Firebase Installation ID](https://firebase.google.com/docs/projects/manage-installations). +- A globally unique UUID which is persisted across sessions in your application. +- [App set ID](https://developer.android.com/identity/app-set-id). +- [`Settings.getString(Settings.Secure.ANDROID_ID)`](https://developer.android.com/reference/android/provider/Settings.Secure#ANDROID_ID). + +More information about Android identifier best practices can be found [here](https://developer.android.com/training/articles/user-data-ids). + + + + + diff --git a/docs/resource/otel.md b/docs/resource/otel.md new file mode 100644 index 0000000000..e389f6d93a --- /dev/null +++ b/docs/resource/otel.md @@ -0,0 +1,24 @@ +# Otel + + + + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**type:** `otel.scope` + +**Description:** Attributes used by non-OTLP exporters to represent OpenTelemetry Scope's concepts. +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`otel.scope.name`](/docs/registry/attributes/otel.md) | string | The name of the instrumentation scope - (`InstrumentationScope.Name` in OTLP). | `io.opentelemetry.contrib.mongodb` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`otel.scope.version`](/docs/registry/attributes/otel.md) | string | The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). | `1.0.0` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + + + diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 7995d46f2e..e9604f12e4 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -25,6 +25,7 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam - [Metric: `system.cpu.physical.count`](#metric-systemcpuphysicalcount) - [Metric: `system.cpu.logical.count`](#metric-systemcpulogicalcount) - [Metric: `system.cpu.time`](#metric-systemcputime) + - [Metric: `system.cpu.frequency`](#metric-systemcpufrequency) - [Metric: `system.cpu.utilization`](#metric-systemcpuutilization) - [Memory metrics](#memory-metrics) - [Metric: `system.memory.usage`](#metric-systemmemoryusage) @@ -187,6 +188,30 @@ This metric is [recommended][MetricRecommended]. +### Metric: `system.cpu.frequency` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `system.cpu.frequency` | Gauge | `Hz` | Operating frequency of the logical CPU in Hertz. | ![Development](https://img.shields.io/badge/-development-blue) | `host` | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`cpu.logical_number`](/docs/registry/attributes/cpu.md) | int | The logical CPU number [0..n-1] | `1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + ### Metric: `system.cpu.utilization` This metric is [opt-in][MetricOptIn]. diff --git a/internal/tools/scripts/find-dead-yaml.sh b/internal/tools/scripts/find-dead-yaml.sh new file mode 100644 index 0000000000..05cde2bf18 --- /dev/null +++ b/internal/tools/scripts/find-dead-yaml.sh @@ -0,0 +1,48 @@ +#!/bin/bash + +# Description: This script checks if all signal groups declared in a YAML file are present in the markdown files under a specified directory. +# Usage: ./check_lines.sh + +set -euo pipefail + +groups="$1" +docs_folder="$2" + +if [[ ! -f "$groups" ]]; then + echo "File with groups does not exist: $groups" + exit 1 +fi + +if [[ ! -d "$docs_folder" ]]; then + echo "Docs folder does not exist: $docs_folder" + exit 1 +fi + +declare -A semconv_snippets +# Extract only lines of the form from .md files +echo "Indexing semconv lines in .md files under: $docs_folder ..." +while IFS= read -r LINE; do + semconv_snippets["$LINE"]=1 +done < <( + grep -rhoP ')' "$docs_folder" --include="*.md" +) + +not_found_groups=() + +while IFS= read -r LINE || [[ -n "$LINE" ]]; do + if [[ -z "${semconv_snippets[$LINE]+_}" ]]; then + not_found_groups+=("$LINE") + fi +done < "$groups" + +echo + +if [[ ${#not_found_groups[@]} -gt 0 ]]; then + echo "❌ The following signals were declared in yaml and NOT found in markdown:" + for line in "${not_found_groups[@]}"; do + echo " - $line" + done + exit 1 +fi + +echo "All groups were found." diff --git a/internal/tools/scripts/registry/signal-groups-weaver.yaml b/internal/tools/scripts/registry/signal-groups-weaver.yaml new file mode 100644 index 0000000000..3dcf254171 --- /dev/null +++ b/internal/tools/scripts/registry/signal-groups-weaver.yaml @@ -0,0 +1,12 @@ +templates: + - pattern: signal-groups.j2 + filter: > + .groups + | map(select(.type != "attribute_group")) + | map(select(has("deprecated") | not)) + | .[].id + application_mode: single +whitespace_control: + trim_blocks: true + lstrip_blocks: true + keep_trailing_newline: true diff --git a/internal/tools/scripts/registry/signal-groups.j2 b/internal/tools/scripts/registry/signal-groups.j2 new file mode 100644 index 0000000000..89a0a91e90 --- /dev/null +++ b/internal/tools/scripts/registry/signal-groups.j2 @@ -0,0 +1,5 @@ +{{- template.set_file_name("signal-groups.txt") -}} + +{% for item in ctx | sort %} +{{ item }} +{% endfor %} \ No newline at end of file From cbc0ad343a2ac647c48c6a0a4c0246f904e44822 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 29 May 2025 18:52:49 -0700 Subject: [PATCH 2/4] permissions --- internal/tools/scripts/find-dead-yaml.sh | 0 1 file changed, 0 insertions(+), 0 deletions(-) mode change 100644 => 100755 internal/tools/scripts/find-dead-yaml.sh diff --git a/internal/tools/scripts/find-dead-yaml.sh b/internal/tools/scripts/find-dead-yaml.sh old mode 100644 new mode 100755 From d787ecd2b5803071a560974e7545dfa2abc20263 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Sun, 8 Jun 2025 12:48:56 -0700 Subject: [PATCH 3/4] deprecate otel.scope enitity --- .chloggen/2310.yaml | 4 ++++ docs/resource/otel.md | 24 ------------------- .../entities-deprecated.yaml} | 2 ++ 3 files changed, 6 insertions(+), 24 deletions(-) create mode 100644 .chloggen/2310.yaml delete mode 100644 docs/resource/otel.md rename model/otel/{entities.yaml => deprecated/entities-deprecated.yaml} (91%) diff --git a/.chloggen/2310.yaml b/.chloggen/2310.yaml new file mode 100644 index 0000000000..0c58a1f81b --- /dev/null +++ b/.chloggen/2310.yaml @@ -0,0 +1,4 @@ +change_type: bug_fix +component: otel +note: Removes `otel.scope` entity. +issues: [2310] diff --git a/docs/resource/otel.md b/docs/resource/otel.md deleted file mode 100644 index e389f6d93a..0000000000 --- a/docs/resource/otel.md +++ /dev/null @@ -1,24 +0,0 @@ -# Otel - - - - - - - - - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -**type:** `otel.scope` - -**Description:** Attributes used by non-OTLP exporters to represent OpenTelemetry Scope's concepts. -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`otel.scope.name`](/docs/registry/attributes/otel.md) | string | The name of the instrumentation scope - (`InstrumentationScope.Name` in OTLP). | `io.opentelemetry.contrib.mongodb` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`otel.scope.version`](/docs/registry/attributes/otel.md) | string | The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). | `1.0.0` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - - - - - diff --git a/model/otel/entities.yaml b/model/otel/deprecated/entities-deprecated.yaml similarity index 91% rename from model/otel/entities.yaml rename to model/otel/deprecated/entities-deprecated.yaml index c1a9f97af1..8253b81a10 100644 --- a/model/otel/entities.yaml +++ b/model/otel/deprecated/entities-deprecated.yaml @@ -4,6 +4,8 @@ groups: type: entity stability: development name: otel.scope + deprecated: + reason: obsoleted brief: Attributes used by non-OTLP exporters to represent OpenTelemetry Scope's concepts. attributes: - ref: otel.scope.name From a131483153500ac304ea999c024e0e8b285530fa Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 19 Jun 2025 14:22:27 -0700 Subject: [PATCH 4/4] prepare for auto-generated entities registry --- docs/resource/app.md | 42 ------------------- .../registry/signal-groups-weaver.yaml | 4 +- 2 files changed, 3 insertions(+), 43 deletions(-) delete mode 100644 docs/resource/app.md diff --git a/docs/resource/app.md b/docs/resource/app.md deleted file mode 100644 index 4dc2e336a3..0000000000 --- a/docs/resource/app.md +++ /dev/null @@ -1,42 +0,0 @@ -# App - - - - - - - - - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -**type:** `app` - -**Description:** An app used directly by end users — like mobile, web, or desktop. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`app.installation.id`](/docs/registry/attributes/app.md) | string | A unique identifier representing the installation of an application on a specific device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[1] `app.installation.id`:** Its value SHOULD persist across launches of the same application installation, including through application upgrades. -It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. -Additionally, users might be able to reset this value (e.g. by clearing application data). -If an app is installed multiple times on the same device (e.g. in different accounts on Android), each `app.installation.id` SHOULD have a different value. -If multiple OpenTelemetry SDKs are used within the same application, they SHOULD use the same value for `app.installation.id`. -Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the `app.installation.id`. - -For iOS, this value SHOULD be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor). - -For Android, examples of `app.installation.id` implementations include: - -- [Firebase Installation ID](https://firebase.google.com/docs/projects/manage-installations). -- A globally unique UUID which is persisted across sessions in your application. -- [App set ID](https://developer.android.com/identity/app-set-id). -- [`Settings.getString(Settings.Secure.ANDROID_ID)`](https://developer.android.com/reference/android/provider/Settings.Secure#ANDROID_ID). - -More information about Android identifier best practices can be found [here](https://developer.android.com/training/articles/user-data-ids). - - - - - diff --git a/internal/tools/scripts/registry/signal-groups-weaver.yaml b/internal/tools/scripts/registry/signal-groups-weaver.yaml index 3dcf254171..552a81aa16 100644 --- a/internal/tools/scripts/registry/signal-groups-weaver.yaml +++ b/internal/tools/scripts/registry/signal-groups-weaver.yaml @@ -1,8 +1,10 @@ templates: - pattern: signal-groups.j2 + # attribute groups and entities are auto-generated and don't need manual code + # snippets, let's filter them out from the check. filter: > .groups - | map(select(.type != "attribute_group")) + | map(select(.type != "attribute_group" and .type != "entity")) | map(select(has("deprecated") | not)) | .[].id application_mode: single