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._
2324Attribute 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-
3327The requirement level for an attribute is specified by semantic conventions
3428depending on attribute availability across instrumented entities, performance,
3529security, 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
5363All instrumentations MUST populate the attribute. A semantic convention defining
5464a 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`
6373attribute on a span can be used as an indication that the span follows database
6474semantics._
6575
66- ## Conditionally Required
76+ ### Conditionally Required
6777
6878All instrumentations MUST populate the attribute when the given condition is
6979satisfied. 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
8999enables the instrumentation to do so, considering the performance issues that
90100DNS lookups introduce.
91101
92- ## Recommended
102+ ### Recommended
93103
94104Instrumentations SHOULD add the attribute by default if it's readily available
95105and 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
101111defined for the ` Opt-In ` requirement level (if the attributes are logically
102112applicable).
103113
104- ## Opt-In
114+ ### Opt-In
105115
106116Instrumentations SHOULD populate the attribute if and only if the user
107117configures the instrumentation to do so. Instrumentation that doesn't support
0 commit comments