From bd2c3e68220bfa21110a3b2385bedccea06a8aeb Mon Sep 17 00:00:00 2001 From: James Thompson Date: Thu, 7 Aug 2025 12:30:43 +1000 Subject: [PATCH 1/2] Write up proposal for bundles #857 --- docs/proposals/bundles.md | 124 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 docs/proposals/bundles.md diff --git a/docs/proposals/bundles.md b/docs/proposals/bundles.md new file mode 100644 index 000000000..bf6f62adb --- /dev/null +++ b/docs/proposals/bundles.md @@ -0,0 +1,124 @@ +# Bundles + +This document is a design proposal to add the ability to define bundles of attributes in semconv. + +## Use cases + +There are a few different use cases which bundles will help us to achieve. + +### Defining signals + +By introducing bundles we are able to bundle a collection of attributes together into a single reusable item. +These items have the primary goal of reducing the need to copy paste definitions while also reducing the maintaince effort. + +An example of where this would be useful is if a `server` bundle was defined similiar to below: + +``` +bundle: + - name: server + brief: Defines a server + note: + attributes + - ref: sever.address + - ref: sever.port +``` + +Once it is defined, it can then be used on other signals to extend the definition. + +``` +span: + - name: messaging.produced + brief: Defines a span for sending a message via a message brooker such as rabbitmq + note: + attributes + - ref: message.system.name + bundles: + - ref: server +``` + +In terms of the resolved schema, these bundles are blended seamlessly in to the definition. + +``` +span: + - name: messaging.produced + brief: Defines a span for sending a message via a message brooker such as rabbitmq + note: + attributes + - id: message.system.name + .... + - id: sever.address + .... + - id: sever.port + .... +``` + +By adopting this approach we are improving the mantainability of the definitions, +by reusing the definition rather than copy and pasting strucutures. + +### Extending signals + +This use case is similiar to the previous except it is focussed on offering optional contextual extensions. +An example of this extension would be Cloud Events which are only applicable if the application is using Cloud Events, +hence the usage is contextual based upon cloud events being used. + +To indicate that a bundle is contextual, this can be done by defining this on the bundle, just like below for `cloud_events`: + +``` +bundle: + - name: cloud_events + brief: For more information on the concepts, terminology and background of CloudEvents consult the CloudEvents Primer document. + context: Can be used when a cloud event payload is being handled (sent/recieved). + note: + attributes + - ref: cloudevents.event_id + - ref: cloudevents.event_source + ...... +``` +Once it is defined, it can then be used on other signals ie the span defined in the previous chapter. + +``` +span: + - name: messaging.produced + brief: Defines a span for sending a message via a message brooker such as rabbitmq + note: + attributes + - ref: message.system.name + bundles: + - ref: server + - ref: cloud_events +``` + +In terms of the resolved schema, these bundles are blended seamlessly in to the definition. + +``` +span: + - name: messaging.produced + brief: Defines a span for sending a message via a message brooker such as rabbitmq + note: + attributes + - id: message.system.name + .... + - id: sever.address + .... + - id: sever.port + .... + - id: cloudevents.event_id + bundle: cloud_events + context: Can be used when a cloud event + .... + - id: cloudevents.event_source + bundle: cloud_events + context: Can be used when a cloud event + .... +``` + +By adopting this approach the definition of cloud events can easily be added/extended without needing to touch the usage. + +## Comparison to v1 solution +Attribute bundles are similiar to attribute groups however, +there are some important differences that needs to be called out: + +* **Extends:** Bundles can not extend other bundles which is the case to reduce complexity +and enable streamlining of the resolving process. +* **Referencing:** A signal ie span can now reference multiple bundles, +which removes the need for creating nested bundles. From bc6a044d8f5a4aee3c81c8a524968fac64a02563 Mon Sep 17 00:00:00 2001 From: James Thompson Date: Fri, 8 Aug 2025 11:09:12 +1000 Subject: [PATCH 2/2] Implementation of review feedback Co-authored-by: Nathan L Smith --- docs/proposals/bundles.md | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/proposals/bundles.md b/docs/proposals/bundles.md index bf6f62adb..c0ccf1140 100644 --- a/docs/proposals/bundles.md +++ b/docs/proposals/bundles.md @@ -18,9 +18,9 @@ bundle: - name: server brief: Defines a server note: - attributes - - ref: sever.address - - ref: sever.port + attributes: + - ref: server.address + - ref: server.port ``` Once it is defined, it can then be used on other signals to extend the definition. @@ -28,9 +28,9 @@ Once it is defined, it can then be used on other signals to extend the definitio ``` span: - name: messaging.produced - brief: Defines a span for sending a message via a message brooker such as rabbitmq + brief: Defines a span for sending a message via a message broker such as RabbitMQ note: - attributes + attributes: - ref: message.system.name bundles: - ref: server @@ -41,25 +41,26 @@ In terms of the resolved schema, these bundles are blended seamlessly in to the ``` span: - name: messaging.produced - brief: Defines a span for sending a message via a message brooker such as rabbitmq + brief: Defines a span for sending a message via a message broker such as RabbitMQ note: - attributes + attributes: - id: message.system.name .... - - id: sever.address + - id: server.address .... - - id: sever.port + - id: server.port .... ``` By adopting this approach we are improving the mantainability of the definitions, -by reusing the definition rather than copy and pasting strucutures. +by reusing the definition rather than copying and pasting structures. ### Extending signals This use case is similiar to the previous except it is focussed on offering optional contextual extensions. -An example of this extension would be Cloud Events which are only applicable if the application is using Cloud Events, -hence the usage is contextual based upon cloud events being used. +An example of this extension would be CloudEvents which are only applicable if the application is using CloudEvents, +hence the usage is contextual based upon CloudEvents being used. +The concept of CloudEvents is described in [CloudEvents Primer](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/primer.md). To indicate that a bundle is contextual, this can be done by defining this on the bundle, just like below for `cloud_events`: @@ -69,7 +70,7 @@ bundle: brief: For more information on the concepts, terminology and background of CloudEvents consult the CloudEvents Primer document. context: Can be used when a cloud event payload is being handled (sent/recieved). note: - attributes + attributes: - ref: cloudevents.event_id - ref: cloudevents.event_source ...... @@ -98,9 +99,9 @@ span: attributes - id: message.system.name .... - - id: sever.address + - id: server.address .... - - id: sever.port + - id: server.port .... - id: cloudevents.event_id bundle: cloud_events @@ -112,7 +113,7 @@ span: .... ``` -By adopting this approach the definition of cloud events can easily be added/extended without needing to touch the usage. +By adopting this approach the definition of CloudEvents can easily be added/extended without needing to touch the usage. ## Comparison to v1 solution Attribute bundles are similiar to attribute groups however,