-
Notifications
You must be signed in to change notification settings - Fork 191
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into update-pipeline-url-attributes
- Loading branch information
Showing
5 changed files
with
232 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| # Use this changelog template to create an entry for release notes. | ||
| # | ||
| # If your change doesn't affect end users you should instead start | ||
| # your pull request title with [chore] or use the "Skip Changelog" label. | ||
|
|
||
| # One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' | ||
| change_type: 'enhancement' | ||
|
|
||
| # The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) | ||
| component: user-agent | ||
|
|
||
| # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). | ||
| note: Add `user_agent.os.name` and `user_agent.os.version` attributes | ||
|
|
||
| # 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: [1433] | ||
|
|
||
| # (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: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,154 @@ | ||
| <!--- Hugo front matter used to generate the website version of this page: | ||
| linkTitle: How to define new semantic conventions | ||
| ---> | ||
|
|
||
| # How to define new semantic conventions | ||
|
|
||
| **Status**: [Development][DocumentStatus] | ||
|
|
||
| <!-- toc --> | ||
|
|
||
| - [Defining new conventions](#defining-new-conventions) | ||
| - [Best practices](#best-practices) | ||
| - [Defining attributes](#defining-attributes) | ||
| - [Defining spans](#defining-spans) | ||
| - [Defining metrics](#defining-metrics) | ||
| - [Defining resources](#defining-resources) | ||
| - [Defining events](#defining-events) | ||
| - [Stabilizing existing conventions](#stabilizing-existing-conventions) | ||
| - [Migration plan](#migration-plan) | ||
|
|
||
| <!-- tocstop --> | ||
|
|
||
| This document describes requirements, recommendations, and best practices on how to define conventions | ||
| for new areas or make substantial changes to the existing ones. | ||
|
|
||
| ## Defining new conventions | ||
|
|
||
| - New conventions MUST have a group of codeowners. See [project management](https://github.com/open-telemetry/community/blob/main/project-management.md) for more details. | ||
| <!-- TODO: add CI check for CODEOWNERS file (when a new area is added) --> | ||
| - New conventions SHOULD be defined in YAML files. See [YAML Model for Semantic Conventions](/model/README.md) for the details. | ||
| - New conventions SHOULD be defined with `development` stability level. | ||
| - New conventions SHOULD include telemetry signal definitions (spans, metrics, events, resources, profiles) and MAY include new attribute definitions. | ||
|
|
||
| ### Best practices | ||
|
|
||
| > [!NOTE] | ||
| > | ||
| > This section contains non-normative guidance. | ||
| #### Defining attributes | ||
|
|
||
| Reuse existing attributes when possible. Look through [existing conventions](/docs/attributes-registry/) for similar areas, | ||
| check out [common attributes](/docs/general/attributes.md). | ||
| Semantic conventions authors are encouraged to use attributes from different namespaces. | ||
|
|
||
| Consider adding a new attribute if all of the following apply: | ||
|
|
||
| - It provides a clear benefit to end users by enhancing telemetry. | ||
| - There is a clear plan to use the attributes when defining spans, metrics, events, resources, or other telemetry signals in semantic conventions. | ||
| - There is a clear plan on how these attributes will be used by instrumentations | ||
|
|
||
| Semantic convention maintainers may reject the addition of a new attribute if its benefits | ||
| and use-cases are not yet clear. | ||
|
|
||
| When defining a new attribute: | ||
|
|
||
| - Follow the [naming guidance](/docs/general/naming.md) | ||
| - Provide descriptive `brief` and `note` sections to clearly explain what the attribute represents. | ||
| - If the attribute represents a common concept documented externally, include relevant links. | ||
| For example, always link to concepts defined in RFCs or other standards. | ||
| - If the attribute's value might contain PII or other sensitive information, explicitly call this out in | ||
| the `note`. | ||
|
|
||
| Include a warning similar to the following: <!-- TODO: update existing semconv --> | ||
|
|
||
| ```yaml | ||
| - id: user.full_name | ||
| ... | ||
| note: | | ||
| ... | ||
| > [!WARNING] | ||
| > | ||
| > This attribute contains sensitive (PII) information. | ||
| ``` | ||
| - Use the appropriate [attribute type](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md#type) | ||
| - If the value has a reasonably short (open or closed) set of possible values, define it as an enum. | ||
| - If the value is a timestamp, record it as a string in ISO 8601 format. | ||
| - For arrays of primitives, use the array type. Avoid recording arrays as a single string. | ||
| - Use the template type to define attributes with dynamic names (only the last segment of the name should be dynamic). | ||
| This is useful for capturing user-defined key-value pairs, such as HTTP headers. | ||
| - Represent complex values as a set of flat attributes. <!-- This may change, check out https://github.com/open-telemetry/semantic-conventions/issues/1669 to monitor the progress --> | ||
| - Define new attributes with `development` stability. | ||
| - Provide realistic examples | ||
| - Avoid defining attributes with potentially unbounded values, such as strings longer than | ||
| 1 KB or arrays with more than 1,000 elements. Such values should be recorded in the log or event body instead. <!-- This may change, check out https://github.com/open-telemetry/semantic-conventions/issues/1651 to monitor the progress --> | ||
|
|
||
| Consider the scope of the attribute and how it may evolve in the future: | ||
|
|
||
| - When defining an attribute for a narrow use case, think about potential broader use cases. | ||
| For example, if creating a system-specific attribute, evaluate whether other systems | ||
| in the same domain might need a similar attribute in the future. | ||
|
|
||
| Similarly, instead of defining a simple boolean flag indicating a success or failure, consider a | ||
| more extensible approach, such as using a `foo.status_code` attribute to include additional details. | ||
|
|
||
| - When defining a broad attribute applicable across multiple domains or systems, | ||
| check for existing standards or widely accepted best practices in the industry. | ||
| Avoid creating generic attributes that are not based on established standards. | ||
|
|
||
| > [!NOTE] | ||
| > | ||
| > When defining conventions for areas with multiple implementations or systems — such as databases, | ||
| > or cloud providers — it can take time to strike the right balance between being | ||
| > overly generic and not generic enough. | ||
| > | ||
| > Start with experimental conventions, document how they apply to a diverse range | ||
| > of providers, systems, or libraries, and prototype instrumentations. | ||
| > | ||
| > The end-user experience should serve as the primary guiding principle: | ||
| > | ||
| > - If the attribute is expected to be used in general-purpose metrics for the area, | ||
| > consider introducing a common attribute. | ||
| > | ||
| > For example, most messaging systems have a concept like a queue or topic. | ||
| > Queue or topic names are critical for latency and throughput metrics and | ||
| > equally important for spans to debug and visualize message flow. | ||
| > This indicates the need for a generic attribute representing any type of messaging destination. | ||
| > | ||
| > - If the attribute represents something useful in a narrow set of scenarios or | ||
| > is specific to certain system metrics, spans, or events, it likely does not need to be generic. | ||
|
|
||
| #### Defining spans | ||
|
|
||
| TBD | ||
|
|
||
| #### Defining metrics | ||
|
|
||
| TBD | ||
|
|
||
| #### Defining resources | ||
|
|
||
| TBD | ||
|
|
||
| #### Defining events | ||
|
|
||
| TBD | ||
|
|
||
| ## Stabilizing existing conventions | ||
|
|
||
| - All conventions MUST be defined in YAML before they can be declared stable | ||
| - Conventions that are not used by instrumentations MUST NOT be declared stable | ||
|
|
||
| TODO: | ||
|
|
||
| - prototyping/implementation requirements | ||
| - migration plan | ||
|
|
||
| ### Migration plan | ||
|
|
||
| TODO | ||
|
|
||
| [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters