Skip to content

Commit cb69cab

Browse files
Document that *.system.name enums are not exhaustive and should not be added without conventions (#2764)
Co-authored-by: Joao Grassi <[email protected]>
1 parent eb9b53c commit cb69cab

File tree

1 file changed

+33
-0
lines changed

1 file changed

+33
-0
lines changed

docs/how-to-write-conventions/README.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ linkTitle: How to define new semantic conventions
1212
- [Best practices](#best-practices)
1313
- [Prototyping](#prototyping)
1414
- [Defining attributes](#defining-attributes)
15+
- [Defining enum attribute members](#defining-enum-attribute-members)
1516
- [Defining spans](#defining-spans)
1617
- [Defining metrics](#defining-metrics)
1718
- [Defining entities](#defining-entities)
@@ -150,6 +151,38 @@ Consider the scope of the attribute and how it may evolve in the future:
150151
> - If the attribute represents something useful in a narrow set of scenarios or
151152
> is specific to certain system metrics, spans, or events, it likely does not need to be generic.
152153

154+
#### Defining enum attribute members
155+
156+
Enum attributes generally fall into three main categories:
157+
158+
**Complete enums** document all possible values. For example, `cpu.mode` covers
159+
all known CPU modes. Metrics like `system.cpu.time` depend on having all modes
160+
defined. Authors should document all known values upfront, though new values
161+
may be added later to support new operating systems or CPU architectures.
162+
163+
**Open enums** like `error.type` allow conventions and instrumentations to define
164+
their own applicable values.
165+
166+
**System identifier enums** specify a system, project, provider, product, or protocol.
167+
For example, `db.system.name` contains database names like `mongodb` or `mysql`.
168+
169+
System identifier enums help differentiate telemetry signals. MongoDB and MySQL
170+
both follow general database conventions, but populate attributes like `db.collection.name` differently and have system-specific attributes. Each system has its own span
171+
definitions and documentation.
172+
See [MongoDB](/docs/database/mongodb.md) and [MySQL](/docs/database/mysql.md) as examples
173+
and check out [system-specific naming](../general/naming.md#system-specific-attributes)
174+
for naming guidance.
175+
176+
> [!IMPORTANT]
177+
> System identifier enums don't need to list every possible system, component, or technology.
178+
>
179+
> OpenTelemetry instrumentations that use enum attributes SHOULD document their values before releasing **stable** artifacts and MAY support undocumented values in unstable artifacts or behind a feature flag.
180+
181+
Only define new system identifiers when you also document how conventions apply
182+
to that system. For example, when adding a new `db.system.name` value, create
183+
documentation and span definitions that show how generic attributes work for that
184+
database.
185+
153186
#### Defining spans
154187

155188
TBD

0 commit comments

Comments
 (0)