Skip to content

Commit

Permalink
nits
Browse files Browse the repository at this point in the history
  • Loading branch information
lmolkova committed May 3, 2022
1 parent 3ab80ea commit b9a95b0
Show file tree
Hide file tree
Showing 3 changed files with 46 additions and 1 deletion.
2 changes: 1 addition & 1 deletion semantic_conventions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ i.e.:
## Writing semantic conventions

Semantic conventions for the spec MUST adhere to the
[attribute naming conventions](../specification/common/attribute-naming.md).
[attribute naming](../specification/common/attribute-naming.md) and [requirement level](../specification/common/attribute-requirement-level.md) conventions.

Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.11.0/semantic-conventions/syntax.md)
for how to write the YAML files for semantic conventions and what the YAML properties mean.
Expand Down
2 changes: 2 additions & 0 deletions specification/common/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,8 @@ both containing an array of strings to represent a mapping

See [Attribute Naming](attribute-naming.md) for naming guidelines.

See [Requirement Level](attribute-requirement-level.md) for requirement levels guidelines.

See [this document](attribute-type-mapping.md) to find out how to map values obtained
outside OpenTelemetry into OpenTelemetry attribute values.

Expand Down
43 changes: 43 additions & 0 deletions specification/common/attribute-requirement-level.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Attribute Requirement Level

**Status**: [Experimental](../document-status.md)

<details>
<summary>Table of Contents</summary>

<!-- toc -->

- [Performance considerations](#performance-considerations)

<!-- tocstop -->

</details>

_This section applies to Resource, Span, Log, and Metric and describes requirement levels for attributes._

Following attribute requirement levels are specified:

- **Required**. All instrumentations MUST populate the attribute. Semantic convention defining required attribute expects that an absolute majority instrumentation libraries and applications are able to efficiently retrieve and populate it, can ensure cardinality, security, and other requirements specific to signal defined by the convention. `http.method` is an example of required attribute.

- **Conditional**. All instrumentations MUST add the attribute when instrumented entity supports corresponding feature and the attribute value can be efficiently retrieved and populated (see [Performance Considerations](#performance-considerations)).
For example, `http.route` is widely supported by HTTP web frameworks, but some low-level HTTP server implementations do not support it.
_Note: For producers of telemetry `Required` and `Conditional` levels are semantically the same (under the assumption that `Required` attributes are always available). However, consumers may use this distinction to identify conventions or validate telemetry._
< TODO need a better name, took 'conditional' from schema definition>

- **Recommended**. Instrumentations SHOULD add the attribute by default if it's readily available and can be efficiently populated. Instrumentation MAY allow explicit configuration to disable recommended attributes.

- **Opt-in**. Instrumentations SHOULD NOT add the attribute by default. Instrumentation SHOULD populate the attribute if and only if user configures instrumentation to do so. Instrumentation that doesn't support configuration MUST NOT populate **Opt-in** attributes.

The requirement level for attribute is defined by semantic conventions depending on attribute availability across instrumented entities, performance, security, and other factors. When defining requirement levels, semantic conventions MUST take into account signal-specific requirements. For example, Metric attributes that may have high cardinality can only be defined with **Opt-in** level.

Semantic convention that refers to attribute from another (e.g. general) semantic convention defaults to initial requirement level and MAY modify the requirement level in scope of a child convention.

Instrumentation that cannot populate attribute according to defined requirement level due to performance, security, privacy, or other consideration, MUST use **Opt-in** requirement level on it.

## Performance considerations

In some cases instrumented entities do not have attribute value readily available and retrieval can be expensive. For example, `net.peer.name` may require DNS lookup if only IP address is available to the instrumentation.

Instrumentations MUST NOT perform expensive resource-consuming operation to obtain attribute values. Corresponding attributes MUST NOT be populated by default.

Basic local operations such as string formatting, escaping or arithmetic operations are allowed.

0 comments on commit b9a95b0

Please sign in to comment.