diff --git a/CHANGELOG.md b/CHANGELOG.md index 75401f5a8..145af7dda 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ All notable changes to this project will be documented in this file. - Rename `resolved_schema_uri` to `resolved_registry_uri` in publication manifest and in `package` command. ([#1425](https://github.com/open-telemetry/weaver/pull/1425)) - Fix V2 resolver overwriting `SpanName.note` with the span type id during resolution. ([#1401](https://github.com/open-telemetry/weaver/pull/1401)) +- Add `semconv_grouped_events` JQ helper with v1/v2 options parity and coverage. ([#1439](https://github.com/open-telemetry/weaver/pull/1439)) - New feature ([#1344](https://github.com/open-telemetry/weaver/issues/1344)) - Support authenticated HTTP downloads of remote registries, including GitHub private release assets. Auth is configured per-URL via `[[auth]]` entries in `.weaver.toml` (longest `url_prefix` wins), with tokens sourced from a literal `token`, a `token_env` variable, or a `token_command` helper (e.g. `["gh", "auth", "token"]`). ([#1356](https://github.com/open-telemetry/weaver/pull/1356) by @jerbly) - New feature - `.weaver.toml` project configuration now covers all subcommands allowing for simplified configuration management. See the [README.md](https://github.com/open-telemetry/weaver/blob/main/crates/weaver_config/README.md) ([#1410](https://github.com/open-telemetry/weaver/pull/1410) by @jerbly) - Live-check OTLP log findings are now dog-fooded: the event schema, attributes, and enumerations are defined in a semconv model and code-generated using Weaver's own templates. See [`finding.md`](crates/weaver_live_check/docs/finding.md) for the generated reference documentation and [`dog-fooding.md`](crates/weaver_live_check/docs/dog-fooding.md) for the full dog-fooding guide. diff --git a/crates/weaver_forge/expected_output/semconv_jq_fn/semconv_events.json b/crates/weaver_forge/expected_output/semconv_jq_fn/semconv_events.json index eb489413b..8fa1711ef 100644 --- a/crates/weaver_forge/expected_output/semconv_jq_fn/semconv_events.json +++ b/crates/weaver_forge/expected_output/semconv_jq_fn/semconv_events.json @@ -1,209 +1,220 @@ [ { - "body": { - "fields": [ - { - "brief": "This attribute represents the state the application has transitioned into at the occurrence of the event.\n", - "id": "ios.state", - "members": [ - { - "brief": "The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`.\n", - "id": "active", - "stability": "stable", - "value": "active" - }, - { - "brief": "The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`.\n", - "id": "inactive", - "stability": "stable", - "value": "inactive" - }, - { - "brief": "The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`.\n", - "id": "background", - "stability": "stable", - "value": "background" - }, + "events": [ + { + "attributes": null, + "body": { + "fields": [ { - "brief": "The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`.\n", - "id": "foreground", - "stability": "stable", - "value": "foreground" + "brief": "This attribute represents the state the application has transitioned into at the occurrence of the event.\n", + "id": "ios.state", + "members": [ + { + "brief": "The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`.\n", + "id": "active", + "stability": "stable", + "value": "active" + }, + { + "brief": "The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`.\n", + "id": "inactive", + "stability": "stable", + "value": "inactive" + }, + { + "brief": "The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`.\n", + "id": "background", + "stability": "stable", + "value": "background" + }, + { + "brief": "The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`.\n", + "id": "foreground", + "stability": "stable", + "value": "foreground" + }, + { + "brief": "The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`.\n", + "id": "terminate", + "stability": "stable", + "value": "terminate" + } + ], + "note": "The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived.\n", + "requirement_level": { + "conditionally_required": "if and only if `os.name` is `ios`" + }, + "stability": "development", + "type": "enum" }, { - "brief": "The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`.\n", - "id": "terminate", - "stability": "stable", - "value": "terminate" + "brief": "This attribute represents the state the application has transitioned into at the occurrence of the event.\n", + "id": "android.state", + "members": [ + { + "brief": "Any time before Activity.onResume() or, if the app has no Activity, Context.startService() has been called in the app for the first time.\n", + "id": "created", + "stability": "stable", + "value": "created" + }, + { + "brief": "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.\n", + "id": "background", + "stability": "stable", + "value": "background" + }, + { + "brief": "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.", + "id": "foreground", + "stability": "stable", + "value": "foreground" + } + ], + "note": "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.\n", + "requirement_level": { + "conditionally_required": "if and only if `os.name` is `android`" + }, + "stability": "development", + "type": "enum" } ], - "note": "The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived.\n", - "requirement_level": { - "conditionally_required": "if and only if `os.name` is `ios`" - }, - "stability": "development", - "type": "enum" + "id": "device.app.lifecycle.fields", + "requirement_level": "required", + "stability": "stable", + "type": "map" }, - { - "brief": "This attribute represents the state the application has transitioned into at the occurrence of the event.\n", - "id": "android.state", - "members": [ - { - "brief": "Any time before Activity.onResume() or, if the app has no Activity, Context.startService() has been called in the app for the first time.\n", - "id": "created", - "stability": "stable", - "value": "created" - }, - { - "brief": "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.\n", - "id": "background", - "stability": "stable", - "value": "background" - }, - { - "brief": "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.", - "id": "foreground", - "stability": "stable", - "value": "foreground" - } - ], - "note": "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.\n", - "requirement_level": { - "conditionally_required": "if and only if `os.name` is `android`" - }, - "stability": "development", - "type": "enum" - } - ], - "id": "device.app.lifecycle.fields", - "requirement_level": "required", - "stability": "stable", - "type": "map" - }, - "brief": "This event represents an occurrence of a lifecycle transition on Android or iOS platform.\n", - "event_namespace": "device.app", - "id": "device.app.lifecycle", - "lineage": { - "provenance": { - "path": "data/registry/mobile-events.yaml", - "schema_url": "https://default/1.0.0" + "brief": "This event represents an occurrence of a lifecycle transition on Android or iOS platform.\n", + "id": "device.app.lifecycle", + "lineage": { + "provenance": { + "path": "data/registry/mobile-events.yaml", + "schema_url": "https://default/1.0.0" + } + }, + "name": "device.app.lifecycle", + "note": "This event identifies the fields that are common to all lifecycle events for android and iOS using the `android.state` and `ios.state` fields. The `android.state` and `ios.state` attributes are mutually exclusive.\n", + "root_namespace": "app", + "stability": "development", + "type": "event" } - }, - "name": "device.app.lifecycle", - "note": "This event identifies the fields that are common to all lifecycle events for android and iOS using the `android.state` and `ios.state` fields. The `android.state` and `ios.state` attributes are mutually exclusive.\n", - "stability": "development", - "type": "event" + ], + "root_namespace": "app" }, { - "attributes": [ + "events": [ { - "annotations": { - "collector": { - "optional": true + "attributes": [ + { + "annotations": { + "collector": { + "optional": true + } + }, + "brief": "SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span.\n", + "name": "exception.escaped", + "note": "An exception is considered to have escaped (or left) the scope of a span,\nif that span is ended while the exception is still logically \"in flight\".\nThis may be actually \"in flight\" in some languages (e.g. if the exception\nis passed to a Context manager\u0027s `__exit__` method in Python) but will\nusually be caught at the point of recording the exception in most languages.\n\nIt is usually not possible to determine at the point where an exception is thrown\nwhether it will escape the scope of a span.\nHowever, it is trivial to know that an exception\nwill escape, if one checks for an active exception just before ending the span,\nas done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception).\n\nIt follows that an exception may still escape the scope of the span\neven if the `exception.escaped` attribute was not set or set to false,\nsince the event might have been recorded at a time where it was not\nclear whether the exception will escape.", + "requirement_level": "recommended", + "stability": "stable", + "type": "boolean" + }, + { + "brief": "The exception message.", + "examples": [ + "Division by zero", + "Can\u0027t convert \u0027int\u0027 object to str implicitly" + ], + "name": "exception.message", + "requirement_level": { + "conditionally_required": "Required if `exception.type` is not set, recommended otherwise." + }, + "stability": "stable", + "type": "string" + }, + { + "brief": "A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG.\n", + "examples": "Exception in thread \"main\" java.lang.RuntimeException: Test exception\\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\\n at com.example.GenerateTrace.main(GenerateTrace.java:5)", + "name": "exception.stacktrace", + "requirement_level": "recommended", + "stability": "stable", + "type": "string" + }, + { + "brief": "The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it.\n", + "examples": [ + "java.net.ConnectException", + "OSError" + ], + "name": "exception.type", + "requirement_level": { + "conditionally_required": "Required if `exception.message` is not set, recommended otherwise." + }, + "stability": "stable", + "type": "string" } - }, - "brief": "SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span.\n", - "name": "exception.escaped", - "note": "An exception is considered to have escaped (or left) the scope of a span,\nif that span is ended while the exception is still logically \"in flight\".\nThis may be actually \"in flight\" in some languages (e.g. if the exception\nis passed to a Context manager\u0027s `__exit__` method in Python) but will\nusually be caught at the point of recording the exception in most languages.\n\nIt is usually not possible to determine at the point where an exception is thrown\nwhether it will escape the scope of a span.\nHowever, it is trivial to know that an exception\nwill escape, if one checks for an active exception just before ending the span,\nas done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception).\n\nIt follows that an exception may still escape the scope of the span\neven if the `exception.escaped` attribute was not set or set to false,\nsince the event might have been recorded at a time where it was not\nclear whether the exception will escape.", - "requirement_level": "recommended", - "stability": "stable", - "type": "boolean" - }, - { - "brief": "The exception message.", - "examples": [ - "Division by zero", - "Can\u0027t convert \u0027int\u0027 object to str implicitly" ], - "name": "exception.message", - "requirement_level": { - "conditionally_required": "Required if `exception.type` is not set, recommended otherwise." - }, - "stability": "stable", - "type": "string" - }, - { - "brief": "A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG.\n", - "examples": "Exception in thread \"main\" java.lang.RuntimeException: Test exception\\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\\n at com.example.GenerateTrace.main(GenerateTrace.java:5)", - "name": "exception.stacktrace", - "requirement_level": "recommended", - "stability": "stable", - "type": "string" - }, - { - "brief": "The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it.\n", - "examples": [ - "java.net.ConnectException", - "OSError" + "brief": "This document defines the attributes used to report a single exception associated with a span.\n", + "entity_associations": [ + "service" ], - "name": "exception.type", - "requirement_level": { - "conditionally_required": "Required if `exception.message` is not set, recommended otherwise." + "id": "trace-exception", + "lineage": { + "attributes": { + "exception.escaped": { + "inherited_fields": [ + "annotations", + "brief", + "note", + "requirement_level", + "stability" + ], + "source_group": "registry.exception" + }, + "exception.message": { + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ], + "source_group": "registry.exception" + }, + "exception.stacktrace": { + "inherited_fields": [ + "brief", + "examples", + "note", + "requirement_level", + "stability" + ], + "source_group": "registry.exception" + }, + "exception.type": { + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ], + "source_group": "registry.exception" + } + }, + "provenance": { + "path": "data/registry/trace-exception.yaml", + "schema_url": "https://default/1.0.0" + } }, - "stability": "stable", - "type": "string" + "name": "exception", + "root_namespace": "other", + "stability": "development", + "type": "event" } ], - "brief": "This document defines the attributes used to report a single exception associated with a span.\n", - "entity_associations": [ - "service" - ], - "event_namespace": "other", - "id": "trace-exception", - "lineage": { - "attributes": { - "exception.escaped": { - "inherited_fields": [ - "annotations", - "brief", - "note", - "requirement_level", - "stability" - ], - "source_group": "registry.exception" - }, - "exception.message": { - "inherited_fields": [ - "brief", - "examples", - "note", - "stability" - ], - "locally_overridden_fields": [ - "requirement_level" - ], - "source_group": "registry.exception" - }, - "exception.stacktrace": { - "inherited_fields": [ - "brief", - "examples", - "note", - "requirement_level", - "stability" - ], - "source_group": "registry.exception" - }, - "exception.type": { - "inherited_fields": [ - "brief", - "examples", - "note", - "stability" - ], - "locally_overridden_fields": [ - "requirement_level" - ], - "source_group": "registry.exception" - } - }, - "provenance": { - "path": "data/registry/trace-exception.yaml", - "schema_url": "https://default/1.0.0" - } - }, - "name": "exception", - "stability": "development", - "type": "event" + "root_namespace": "other" } ] \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/semconv_jq_fn_v2/semconv_events.json b/crates/weaver_forge/expected_output/semconv_jq_fn_v2/semconv_events.json new file mode 100644 index 000000000..462493700 --- /dev/null +++ b/crates/weaver_forge/expected_output/semconv_jq_fn_v2/semconv_events.json @@ -0,0 +1,14 @@ +[ + { + "events": [ + { + "attributes": null, + "brief": "", + "name": "db.query", + "root_namespace": "db", + "stability": "alpha" + } + ], + "root_namespace": "db" + } +] \ No newline at end of file diff --git a/crates/weaver_forge/src/lib.rs b/crates/weaver_forge/src/lib.rs index c0aae7550..fdc9cd289 100644 --- a/crates/weaver_forge/src/lib.rs +++ b/crates/weaver_forge/src/lib.rs @@ -868,6 +868,7 @@ mod tests { use crate::extensions::case::case_converter; use crate::file_loader::FileSystemFileLoader; use crate::registry::ResolvedRegistry; + use crate::v2::event::Event; use crate::v2::registry::{ForgeResolvedRegistry, Refinements, Registry as V2Registry}; use crate::v2::span::Span; use crate::{run_filter_raw, OutputDirective, TemplateEngine}; @@ -962,7 +963,13 @@ mod tests { common: CommonFields::default(), provenance: Default::default(), }], - events: vec![], + events: vec![Event { + name: SignalId::from("db.query".to_owned()), + attributes: vec![], + entity_associations: vec![], + common: CommonFields::default(), + provenance: Default::default(), + }], entities: vec![], }, refinements: Refinements { @@ -1352,6 +1359,55 @@ mod tests { assert_eq!(result, expected); } + #[test] + fn test_run_filter_raw_semconv_grouped_events_v2() { + let input = serde_json::json!({ + "registry": { + "events": [ + { + "name": "http.request", + "brief": "stable event", + "stability": "stable" + }, + { + "name": "db.query", + "brief": "deprecated event", + "stability": "stable", + "deprecated": { "note": "deprecated" } + }, + { + "name": "other.event", + "brief": "excluded namespace", + "stability": "stable" + } + ] + } + }); + + let result = run_filter_raw( + &input, + "semconv_grouped_events({\"v2\": true, \"exclude_deprecated\": true, \"exclude_root_namespace\": [\"other\"]})", + ) + .expect("failed to run semconv_grouped_events for v2"); + + let expected = serde_json::json!([ + { + "root_namespace": "http", + "events": [ + { + "name": "http.request", + "brief": "stable event", + "stability": "stable", + "root_namespace": "http", + "attributes": null + } + ] + } + ]); + + assert_eq!(result, expected); + } + #[test] fn test_auto_escape_modes() { use minijinja::{AutoEscape, Environment}; diff --git a/crates/weaver_forge/templates/semconv_jq_fn/weaver.yaml b/crates/weaver_forge/templates/semconv_jq_fn/weaver.yaml index 4454eac7a..244c5d6d1 100644 --- a/crates/weaver_forge/templates/semconv_jq_fn/weaver.yaml +++ b/crates/weaver_forge/templates/semconv_jq_fn/weaver.yaml @@ -33,10 +33,7 @@ templates: application_mode: single - template: semconv_events.json filter: > - .groups - | map(select(.type == "event")) - | map(. + { - event_namespace: (if .id | index(".") then (.id | split(".") | .[0:-1] | join(".")) else "other" end) - }) - | sort_by(.event_namespace, .id) + semconv_grouped_events({ + "stable_only": false + }) application_mode: single diff --git a/crates/weaver_forge/templates/semconv_jq_fn_v2/semconv_events.j2 b/crates/weaver_forge/templates/semconv_jq_fn_v2/semconv_events.j2 new file mode 100644 index 000000000..4e891c1f5 --- /dev/null +++ b/crates/weaver_forge/templates/semconv_jq_fn_v2/semconv_events.j2 @@ -0,0 +1 @@ +{{ ctx | tojson(indent=true) }} diff --git a/crates/weaver_forge/templates/semconv_jq_fn_v2/weaver.yaml b/crates/weaver_forge/templates/semconv_jq_fn_v2/weaver.yaml index 055b97704..9e1029f22 100644 --- a/crates/weaver_forge/templates/semconv_jq_fn_v2/weaver.yaml +++ b/crates/weaver_forge/templates/semconv_jq_fn_v2/weaver.yaml @@ -4,3 +4,8 @@ templates: semconv_grouped_spans({"v2": true}) application_mode: single file_name: semconv_spans.json + - template: semconv_events.j2 + filter: > + semconv_grouped_events({"v2": true}) + application_mode: single + file_name: semconv_events.json diff --git a/defaults/jq/semconv.jq b/defaults/jq/semconv.jq index c6f5d8a6e..d59348df1 100644 --- a/defaults/jq/semconv.jq +++ b/defaults/jq/semconv.jq @@ -29,13 +29,25 @@ def stability_filter($options): map( select(.stability == "stable") ) - | map(.type.members? |= map(select(.stability == "stable"))) + | map( + if .type? == null then + . + else + .type.members? |= map(select(.stability == "stable")) + end + ) else . end | if $options | has("exclude_stability") then map(select(.stability as $st | expand_stability($options.exclude_stability) | index($st) | not)) - | map(.type.members? |= map(select(.stability as $st | expand_stability($options.exclude_stability) | index($st) | not))) + | map( + if .type? == null then + . + else + .type.members? |= map(select(.stability as $st | expand_stability($options.exclude_stability) | index($st) | not)) + end + ) else . end; @@ -90,10 +102,16 @@ def code_generation_exclude_filter($options): or .annotations.code_generation.exclude == null or .annotations.code_generation.exclude == false )) - | map(.type.members? |= map(select(.annotations == null - or .annotations.code_generation == null - or .annotations.code_generation.exclude == null - or .annotations.code_generation.exclude == false))) + | map( + if .type? == null then + . + else + .type.members? |= map(select(.annotations == null + or .annotations.code_generation == null + or .annotations.code_generation.exclude == null + or .annotations.code_generation.exclude == false)) + end + ) end; # Filters the input list of attributes and enum members based on deprecation status. @@ -102,7 +120,13 @@ def code_generation_exclude_filter($options): def deprecated_filter($options): if ($options | has("exclude_deprecated") and $options.exclude_deprecated == true) then map(select(has("deprecated") | not)) - | map(.type.members? |= map(select(has("deprecated") | not))) + | map( + if .type? == null then + . + else + .type.members? |= map(select(has("deprecated") | not)) + end + ) else . end; @@ -261,3 +285,35 @@ def semconv_grouped_spans($options): semconv_spans($options) | semconv_group_spa # Convenience function to group all spans by their root namespace without any filtering options. def semconv_grouped_spans: semconv_grouped_spans({}); + +# Event Functions +# Groups the events by their root namespace and sorts events by name. +def semconv_group_events_by_root_namespace: + group_by(.root_namespace) + | map({ root_namespace: .[0].root_namespace, events: . | sort_by(.name) }); + +# Extracts and processes semantic convention events based on provided options. +# $options is an object that can contain: +# - stable_only: a boolean to exclude all non-stable events and non-stable attributes on stable events. +# - exclude_deprecated: a boolean to exclude deprecated events and deprecated attributes. +# - exclude_root_namespace: a list of root namespaces to exclude - applies to top-level events and does not apply to nested attributes. +# - exclude_stability: a list of stability statuses to exclude. Use `stable_only` to exclude all non-stable events instead. Applies to nested attributes as well. +# - ignore_code_generation_annotations: a boolean to ignore code generation annotations. Applies to signals and nested attributes. +# - v2: a boolean to use v2 schema. +def semconv_events($options): semconv_signal("event"; $options) | sort_by(.name); + +# Convenience function to extract all events without any filtering options. +def semconv_events: semconv_events({}); + +# Groups the processed events by their root namespace based on provided options. +# $options is an object that can contain: +# - stable_only: a boolean to exclude all non-stable events and non-stable attributes on stable events. +# - exclude_deprecated: a boolean to exclude deprecated events and deprecated attributes. +# - exclude_root_namespace: a list of root namespaces to exclude - applies to top-level events and does not apply to nested attributes. +# - exclude_stability: a list of stability statuses to exclude. Use `stable_only` to exclude all non-stable events instead. Applies to nested attributes as well. +# - ignore_code_generation_annotations: a boolean to ignore code generation annotations. Applies to signals and nested attributes. +# - v2: a boolean to use v2 schema. +def semconv_grouped_events($options): semconv_events($options) | semconv_group_events_by_root_namespace; + +# Convenience function to group all events by their root namespace without any filtering options. +def semconv_grouped_events: semconv_grouped_events({});