Skip to content

Commit

Permalink
Remove local stubs of semantic conventions. (#3711)
Browse files Browse the repository at this point in the history
  • Loading branch information
jsuereth authored Oct 3, 2023
1 parent c1343ce commit a3090b3
Show file tree
Hide file tree
Showing 2 changed files with 7 additions and 13 deletions.
14 changes: 3 additions & 11 deletions attribute-naming.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ Names SHOULD follow these rules:
values: the executable name and command arguments.

- When an attribute represents a measurement,
[Metric Name Pluralization Guidelines](../metrics/semantic_conventions/README.md#pluralization)
[Metric Name Pluralization Guidelines](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/metrics.md#pluralization)
SHOULD be followed for the attribute name.

## Name Reuse Prohibition
Expand All @@ -83,11 +83,7 @@ denote old attribute names in rename operations).
of a namespace.

- When coming up with a new semantic convention make sure to check existing
namespaces for
[Resources](../resource/semantic_conventions/README.md),
[Spans](../trace/semantic_conventions/README.md),
and
[Metrics](../metrics/semantic_conventions/README.md)
namespaces ([Semantic Conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md))
to see if the new name fits.

- When a new namespace is necessary consider whether it should be a top-level
Expand All @@ -111,11 +107,7 @@ denote old attribute names in rename operations).
## Recommendations for Application Developers

As an application developer when you need to record an attribute first consult
existing semantic conventions for
[Resources](../resource/semantic_conventions/README.md),
[Spans](../trace/semantic_conventions/README.md),
and
[Metrics](../metrics/semantic_conventions/README.md).
existing [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md).
If an appropriate name does not exists you will need to come up with a new name.
To do that consider a few options:

Expand Down
6 changes: 4 additions & 2 deletions attribute-requirement-level.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,8 @@ For example, Metric attributes that may have high cardinality can only be define

A semantic convention that refers to an attribute from another semantic convention MAY modify the requirement level within its own scope. Otherwise, requirement level from the referred semantic convention applies.

For example, [Database semantic convention](../trace/semantic_conventions/database.md) references `network.transport` attribute defined in [General attributes](../trace/semantic_conventions/span-general.md) with `Conditionally Required` level on it.
<!-- TODO(jsuereth) - make examples not break on changes to semconv -->
For example, [Database semantic convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/README.md) references `network.transport` attribute defined in [General attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/README.md) with `Conditionally Required` level on it.

## Required

Expand All @@ -50,7 +51,8 @@ All instrumentations MUST populate the attribute when the given condition is sat

When a `Conditionally Required` attribute's condition is not satisfied, and there is no requirement to populate the attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Opt-In` requirement level on the attribute.

For example, `server.address` is `Conditionally Required` by the [Database convention](../trace/semantic_conventions/database.md) when available. When `server.socket.address` is available instead, instrumentation can do a DNS lookup, cache and populate `server.address`, but only if the user explicitly enables the instrumentation to do so, considering the performance issues that DNS lookups introduce.
<!-- TODO(jsuereth) - make examples not break on changes to semconv -->
For example, `server.address` is `Conditionally Required` by the [Database convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/README.md) when available. When `server.socket.address` is available instead, instrumentation can do a DNS lookup, cache and populate `server.address`, but only if the user explicitly enables the instrumentation to do so, considering the performance issues that DNS lookups introduce.

## Recommended

Expand Down

0 comments on commit a3090b3

Please sign in to comment.