From 0b44321007450de9e16285f6ecb10b537f112984 Mon Sep 17 00:00:00 2001 From: James Thompson Date: Sun, 3 Aug 2025 13:56:54 +1000 Subject: [PATCH 1/2] Define namespaces in yaml --- docs/proposals/namespaces.md | 206 +++++++++++++++++++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 docs/proposals/namespaces.md diff --git a/docs/proposals/namespaces.md b/docs/proposals/namespaces.md new file mode 100644 index 000000000..1b11cc904 --- /dev/null +++ b/docs/proposals/namespaces.md @@ -0,0 +1,206 @@ +# Namespaces + +This document is a design proposal to add the ability to define namespaces in semconv. + +## Use cases + +There are a few different use cases which namespaces will help us to achieve. + +### Describing attribute/signal collections + +By introducing namespaces ie `gen-ai` we can define a group which all the attributes can be assigned to. +This linking can occur in 1 of 3 ways which are explicit, implicit and fallback and described below. + +Currently in v1 schema this can be achieved to a point via attribute groups however these do not exist in v2 schema. +Hence this proposal becomes a useful way to migrate the information which is contained in the attribute groups to v2 +and in the process increase the capabilities of this grouping to include other signals. + +#### Explicit linking + +This is where the author explicitly states the namespace which this telemetry signal should be associated with. +This is to help with the when the namespace of an attribute changes. +For instance `az` has become `azure`. + +#### Implicit linking + +This is where the full namespace of the attribute is used to detemine which namespace it belongs to. +An example of this is the `gen_ai.openai.request.service_tier` attribute could be +automatically associated with the `gen_ai` namespace, +if the namespace definition existed. + +This approach can be also used for subnamespaces for instance the `gen_ai.openai.request.service_tier` attribute could be +automatically associated with the `gen_ai.openai` namespace, +if the namespace definition existed. + +#### Fallback linking + +If neither of the 2 previous methods are satisifed, +a namespace is created by weaver which corresponds to the first path segment. +This namespace will use the default values for a namespace. + +### Migration Guides + +By introducing the namespaces we now have a location to define information for migration guides. +In the future these migration guides could be generated by weaver, +by using the output from weaver diff hence further automating documentation and increasing consistency. + +This ability to indicate a migration guide is a key benefit as currently these links/descriptiions are manually added into the markdown and the documents manually prepred. + +The namespace opt-in option would look something like: + +``` +version: "2" +namespaces: + - name: gen_ai + migration-guide: + enabled: true + brief: + note: + target: 1.a.x +``` + +### Revision history + +Currently as part of the process of writing/updating semantic conventions, +a changelog file is also needing to be authored. +By having namespaces, we could also be automatically generating a revision history document using the output of weaver diff. + +This output could produce a single file as per now and/or namespace revision history. +The namespace option would either need to be opted in on a per namespace basis or possibly a weaver setting to control the default behaviour. + +The namespace opt-in option would look something like: + +``` +version: "2" +namespaces: + - name: gen_ai + revison-history: + enabled: true + brief: + note: +``` + +## Unresolved schema Defintition (input) + +At it's core the namespace definition does not differ much at all to the defintion of any other signal. + +As such the defintition would be something like: + +``` +version: "2" +namespaces: + - name: gen_ai + brief: + note: + annotations: + migration-guide: + enabled: true + brief: + note: + target: 1.b.y + revison-history: + enabled: true + brief: + note: + - name: gen_ai.openai + brief: + note: + annotations: + migration-guide: + enabled: true + brief: + note: + target: 1.c.z + revison-history: + enabled: true + brief: + note: +``` + +## Resolved schema (output) + +### Each [Application Mode] + +This application mode is what is utisiled to generate definitions of a single items. + +The definition of this would be something like: + +``` +version: "2" +mode: each +definition: + name: gen_ai.client.token.usage + signal-type: metric + ...... + namespace: + name: gen_ai + brief: + note: + migration-guide: + enabled: true + brief: + note: + revison-history: + enabled: true + brief: + note: +``` + +*Subject to change as part of the v2 works + +### Namespace [Application Mode] + +This application mode is what is utisiled to generate definitions of namespaces +and is also what is produced by the resolve schema command. + +The definition of this would be something like: + +``` +version: "2" +mode: namespace +namespace: + name: gen_ai + brief: + note: + migration-guide: + enabled: true + brief: + note: + history: + - version: x.y.z + ....... + revison-history: + enabled: true + brief: + note: + history: + - version: x.y.z + ....... + metrics: + - name: gen_ai.client.token.usage + type: histogram + ...... + attributes: + ...... + spans: + ...... + events: + ...... +``` + +*Subject to change as part of the v2 works + +### Registry/Single [Application Mode] + +This is used to produce index pages in the registry which covers multiple namespaces. + +The structure is the same as Namespace with the only difference being an array of namespaces are outputted rather than a single namespace. + +``` +version: "2" +mode: registry +registry: + namespaces: + - name: gen_ai + ...... +``` From caf70fcf28e406b92f8e895d5d0f5eab2946c31f Mon Sep 17 00:00:00 2001 From: James Thompson Date: Sun, 19 Jul 2026 15:10:50 +1000 Subject: [PATCH 2/2] Fix typos in namespaces.md documentation --- docs/proposals/namespaces.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/proposals/namespaces.md b/docs/proposals/namespaces.md index 1b11cc904..230d92e49 100644 --- a/docs/proposals/namespaces.md +++ b/docs/proposals/namespaces.md @@ -23,7 +23,7 @@ For instance `az` has become `azure`. #### Implicit linking -This is where the full namespace of the attribute is used to detemine which namespace it belongs to. +This is where the full namespace of the attribute is used to determine which namespace it belongs to. An example of this is the `gen_ai.openai.request.service_tier` attribute could be automatically associated with the `gen_ai` namespace, if the namespace definition existed. @@ -34,7 +34,7 @@ if the namespace definition existed. #### Fallback linking -If neither of the 2 previous methods are satisifed, +If neither of the 2 previous methods are satisfied, a namespace is created by weaver which corresponds to the first path segment. This namespace will use the default values for a namespace. @@ -74,17 +74,17 @@ The namespace opt-in option would look something like: version: "2" namespaces: - name: gen_ai - revison-history: + revision-history: enabled: true brief: note: ``` -## Unresolved schema Defintition (input) +## Unresolved schema Definition (input) -At it's core the namespace definition does not differ much at all to the defintion of any other signal. +At it's core the namespace definition does not differ much at all to the definition of any other signal. -As such the defintition would be something like: +As such the definition would be something like: ``` version: "2" @@ -98,7 +98,7 @@ namespaces: brief: note: target: 1.b.y - revison-history: + revision-history: enabled: true brief: note: @@ -111,7 +111,7 @@ namespaces: brief: note: target: 1.c.z - revison-history: + revision-history: enabled: true brief: note: @@ -140,7 +140,7 @@ definition: enabled: true brief: note: - revison-history: + revision-history: enabled: true brief: note: @@ -169,7 +169,7 @@ namespace: history: - version: x.y.z ....... - revison-history: + revision-history: enabled: true brief: note: