Skip to content

Commit 08804c8

Browse files
[chore] Describe configurable nature of attributes (#2577)
1 parent 19a8b95 commit 08804c8

File tree

1 file changed

+25
-15
lines changed

1 file changed

+25
-15
lines changed

docs/general/attribute-requirement-level.md

Lines changed: 25 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,11 @@
77

88
<!-- toc -->
99

10-
- [Required](#required)
11-
- [Conditionally Required](#conditionally-required)
12-
- [Recommended](#recommended)
13-
- [Opt-In](#opt-in)
10+
- [Requirement Levels](#requirement-levels)
11+
- [Required](#required)
12+
- [Conditionally Required](#conditionally-required)
13+
- [Recommended](#recommended)
14+
- [Opt-In](#opt-in)
1415
- [Performance suggestions](#performance-suggestions)
1516

1617
<!-- tocstop -->
@@ -23,13 +24,6 @@ requirement levels for attributes defined in semantic conventions._
2324
Attribute requirement levels apply to the
2425
[instrumentation library](https://opentelemetry.io/docs/concepts/glossary/#instrumentation-library).
2526

26-
The following attribute requirement levels are specified:
27-
28-
- [Required](#required)
29-
- [Conditionally Required](#conditionally-required)
30-
- [Recommended](#recommended)
31-
- [Opt-In](#opt-in)
32-
3327
The requirement level for an attribute is specified by semantic conventions
3428
depending on attribute availability across instrumented entities, performance,
3529
security, and other factors. When specifying requirement levels, a semantic
@@ -48,7 +42,23 @@ For example, [Database semantic convention](../database/README.md) references
4842
`network.transport` attribute defined in [General attributes](./README.md) with
4943
`Conditionally Required` level on it.
5044

51-
## Required
45+
## Requirement Levels
46+
47+
The below table details the default inclusion behaviour of attributes on telemetry signals and
48+
if it can be changed via configuration options.
49+
50+
| Level | Included by default | Can be included via config | Can be excluded via Config |
51+
| --- | --- | --- | --- |
52+
| [Required](#required) | Yes | n/a | No |
53+
| [Conditionally Required](#conditionally-required) | Yes [1] | No [1] | No [1] |
54+
| [Recommended](#recommended) | Yes [2] | No [2] | Yes |
55+
| [Opt-In](#opt-in) | No | Yes | Yes |
56+
57+
**[1]:** unless the attribute requirement conditions or instructions are not satisfied.
58+
59+
**[2]:** unless it was excluded for a reason outlined in [Recommended](#recommended) section.
60+
61+
### Required
5262

5363
All instrumentations MUST populate the attribute. A semantic convention defining
5464
a Required attribute expects an absolute majority of instrumentation libraries
@@ -63,7 +73,7 @@ defined by such convention. For example, the presence of the `db.system.name`
6373
attribute on a span can be used as an indication that the span follows database
6474
semantics._
6575

66-
## Conditionally Required
76+
### Conditionally Required
6777

6878
All instrumentations MUST populate the attribute when the given condition is
6979
satisfied. The semantic convention of a `Conditionally Required` attribute MUST
@@ -89,7 +99,7 @@ lookup, cache and populate `server.address`, but only if the user explicitly
8999
enables the instrumentation to do so, considering the performance issues that
90100
DNS lookups introduce.
91101

92-
## Recommended
102+
### Recommended
93103

94104
Instrumentations SHOULD add the attribute by default if it's readily available
95105
and can be [efficiently populated](#performance-suggestions). Instrumentations
@@ -101,7 +111,7 @@ consideration by default, SHOULD allow for users to opt-in to emit them as
101111
defined for the `Opt-In` requirement level (if the attributes are logically
102112
applicable).
103113

104-
## Opt-In
114+
### Opt-In
105115

106116
Instrumentations SHOULD populate the attribute if and only if the user
107117
configures the instrumentation to do so. Instrumentation that doesn't support

0 commit comments

Comments
 (0)