Skip to content

Commit fa19325

Browse files
lmolkovatrasktrisch-me
authored
First stab at documenting the art of defining semantic conventions (#1707)
Co-authored-by: Trask Stalnaker <[email protected]> Co-authored-by: Alexandra Konrad <[email protected]>
1 parent 0b3babd commit fa19325

File tree

2 files changed

+167
-0
lines changed

2 files changed

+167
-0
lines changed

‎CONTRIBUTING.md

+13
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ requirements and recommendations.
1414
- [Sign the CLA](#sign-the-cla)
1515
- [How to Contribute](#how-to-contribute)
1616
- [Which semantic conventions belong in this repo](#which-semantic-conventions-belong-in-this-repo)
17+
- [Suggesting conventions for a new area](#suggesting-conventions-for-a-new-area)
1718
- [Prerequisites](#prerequisites)
1819
- [1. Modify the YAML model](#1-modify-the-yaml-model)
1920
- [Code structure](#code-structure)
@@ -81,6 +82,18 @@ and helps to keep conventions consistent and backward compatible.
8182
Want to define your own conventions outside this repo while building on OTel’s?
8283
Come help us [decentralize semantic conventions](https://github.com/open-telemetry/weaver/issues/215).
8384

85+
### Suggesting conventions for a new area
86+
87+
Defining semantic conventions requires a group of people who are familiar with the domain,
88+
are involved with instrumentation efforts, and are committed to be the point of contact for
89+
pull requests, issues, and questions in this area.
90+
91+
Check out [project management](https://github.com/open-telemetry/community/blob/main/project-management.md)
92+
for the details on how to start.
93+
94+
Refer to the [How to define new conventions](/docs/general/how-to-define-semantic-conventions.md)
95+
document for guidance.
96+
8497
### Prerequisites
8598

8699
The Specification uses several tools to check things like style,

‎docs/general/how-to-define-semantic-conventions.md

+154
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
<!--- Hugo front matter used to generate the website version of this page:
2+
linkTitle: How to define new semantic conventions
3+
--->
4+
5+
# How to define new semantic conventions
6+
7+
**Status**: [Development][DocumentStatus]
8+
9+
<!-- toc -->
10+
11+
- [Defining new conventions](#defining-new-conventions)
12+
- [Best practices](#best-practices)
13+
- [Defining attributes](#defining-attributes)
14+
- [Defining spans](#defining-spans)
15+
- [Defining metrics](#defining-metrics)
16+
- [Defining resources](#defining-resources)
17+
- [Defining events](#defining-events)
18+
- [Stabilizing existing conventions](#stabilizing-existing-conventions)
19+
- [Migration plan](#migration-plan)
20+
21+
<!-- tocstop -->
22+
23+
This document describes requirements, recommendations, and best practices on how to define conventions
24+
for new areas or make substantial changes to the existing ones.
25+
26+
## Defining new conventions
27+
28+
- 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.
29+
<!-- TODO: add CI check for CODEOWNERS file (when a new area is added) -->
30+
- New conventions SHOULD be defined in YAML files. See [YAML Model for Semantic Conventions](/model/README.md) for the details.
31+
- New conventions SHOULD be defined with `development` stability level.
32+
- New conventions SHOULD include telemetry signal definitions (spans, metrics, events, resources, profiles) and MAY include new attribute definitions.
33+
34+
### Best practices
35+
36+
> [!NOTE]
37+
>
38+
> This section contains non-normative guidance.
39+
40+
#### Defining attributes
41+
42+
Reuse existing attributes when possible. Look through [existing conventions](/docs/attributes-registry/) for similar areas,
43+
check out [common attributes](/docs/general/attributes.md).
44+
Semantic conventions authors are encouraged to use attributes from different namespaces.
45+
46+
Consider adding a new attribute if all of the following apply:
47+
48+
- It provides a clear benefit to end users by enhancing telemetry.
49+
- There is a clear plan to use the attributes when defining spans, metrics, events, resources, or other telemetry signals in semantic conventions.
50+
- There is a clear plan on how these attributes will be used by instrumentations
51+
52+
Semantic convention maintainers may reject the addition of a new attribute if its benefits
53+
and use-cases are not yet clear.
54+
55+
When defining a new attribute:
56+
57+
- Follow the [naming guidance](/docs/general/naming.md)
58+
- Provide descriptive `brief` and `note` sections to clearly explain what the attribute represents.
59+
- If the attribute represents a common concept documented externally, include relevant links.
60+
For example, always link to concepts defined in RFCs or other standards.
61+
- If the attribute's value might contain PII or other sensitive information, explicitly call this out in
62+
the `note`.
63+
64+
Include a warning similar to the following: <!-- TODO: update existing semconv -->
65+
66+
```yaml
67+
- id: user.full_name
68+
...
69+
note: |
70+
...
71+
72+
> [!WARNING]
73+
>
74+
> This attribute contains sensitive (PII) information.
75+
```
76+
77+
- Use the appropriate [attribute type](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md#type)
78+
- If the value has a reasonably short (open or closed) set of possible values, define it as an enum.
79+
- If the value is a timestamp, record it as a string in ISO 8601 format.
80+
- For arrays of primitives, use the array type. Avoid recording arrays as a single string.
81+
- Use the template type to define attributes with dynamic names (only the last segment of the name should be dynamic).
82+
This is useful for capturing user-defined key-value pairs, such as HTTP headers.
83+
- 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 -->
84+
- Define new attributes with `development` stability.
85+
- Provide realistic examples
86+
- Avoid defining attributes with potentially unbounded values, such as strings longer than
87+
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 -->
88+
89+
Consider the scope of the attribute and how it may evolve in the future:
90+
91+
- When defining an attribute for a narrow use case, think about potential broader use cases.
92+
For example, if creating a system-specific attribute, evaluate whether other systems
93+
in the same domain might need a similar attribute in the future.
94+
95+
Similarly, instead of defining a simple boolean flag indicating a success or failure, consider a
96+
more extensible approach, such as using a `foo.status_code` attribute to include additional details.
97+
98+
- When defining a broad attribute applicable across multiple domains or systems,
99+
check for existing standards or widely accepted best practices in the industry.
100+
Avoid creating generic attributes that are not based on established standards.
101+
102+
> [!NOTE]
103+
>
104+
> When defining conventions for areas with multiple implementations or systems — such as databases,
105+
> or cloud providers — it can take time to strike the right balance between being
106+
> overly generic and not generic enough.
107+
>
108+
> Start with experimental conventions, document how they apply to a diverse range
109+
> of providers, systems, or libraries, and prototype instrumentations.
110+
>
111+
> The end-user experience should serve as the primary guiding principle:
112+
>
113+
> - If the attribute is expected to be used in general-purpose metrics for the area,
114+
> consider introducing a common attribute.
115+
>
116+
> For example, most messaging systems have a concept like a queue or topic.
117+
> Queue or topic names are critical for latency and throughput metrics and
118+
> equally important for spans to debug and visualize message flow.
119+
> This indicates the need for a generic attribute representing any type of messaging destination.
120+
>
121+
> - If the attribute represents something useful in a narrow set of scenarios or
122+
> is specific to certain system metrics, spans, or events, it likely does not need to be generic.
123+
124+
#### Defining spans
125+
126+
TBD
127+
128+
#### Defining metrics
129+
130+
TBD
131+
132+
#### Defining resources
133+
134+
TBD
135+
136+
#### Defining events
137+
138+
TBD
139+
140+
## Stabilizing existing conventions
141+
142+
- All conventions MUST be defined in YAML before they can be declared stable
143+
- Conventions that are not used by instrumentations MUST NOT be declared stable
144+
145+
TODO:
146+
147+
- prototyping/implementation requirements
148+
- migration plan
149+
150+
### Migration plan
151+
152+
TODO
153+
154+
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

0 commit comments

Comments
 (0)