open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Rename Optional attribute requirement level to Opt-In (#3228)

This commit is contained in:
Trask Stalnaker 2023-03-01 15:13:24 -08:00 committed by GitHub
parent f839f1ed9a
commit 47cabcf799
10 changed files with 21 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.vscode/settings.json vendored
View File

@ -10,7 +10,7 @@
"MD040": false, "MD040": false,
}, },
"yaml.schemas": { "yaml.schemas": {
"https://raw.githubusercontent.com/open-telemetry/build-tools/v0.16.0/semantic-conventions/semconv.schema.json": [ "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.17.0/semantic-conventions/semconv.schema.json": [
"semantic_conventions/**/*.yaml" "semantic_conventions/**/*.yaml"
] ]
}, },

2
Makefile
View File

@ -8,7 +8,7 @@ MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY)
# see https://github.com/open-telemetry/build-tools/releases for semconvgen updates # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates
# Keep links in semantic_conventions/README.md and .vscode/settings.json in sync! # Keep links in semantic_conventions/README.md and .vscode/settings.json in sync!
SEMCONVGEN_VERSION=0.16.0 SEMCONVGEN_VERSION=0.17.0
# TODO: add `yamllint` step to `all` after making sure it works on Mac. # TODO: add `yamllint` step to `all` after making sure it works on Mac.
.PHONY: all .PHONY: all

2
internal/tools/schema_check.sh
View File

@ -6,7 +6,7 @@
set -e set -e
BUILD_TOOL_SCHEMAS_VERSION=0.16.0 BUILD_TOOL_SCHEMAS_VERSION=0.17.0
# List of versions that do not require or have a schema. # List of versions that do not require or have a schema.
declare -a skip_versions=("1.0.0" "1.0.1" "1.1.0" "1.2.0" "1.3.0" "1.6.0") declare -a skip_versions=("1.0.0" "1.0.1" "1.1.0" "1.2.0" "1.3.0" "1.6.0")

6
semantic_conventions/README.md
View File

@ -19,12 +19,12 @@ Semantic conventions for the spec MUST adhere to the
[attribute requirement level](../specification/common/attribute-requirement-level.md), [attribute requirement level](../specification/common/attribute-requirement-level.md),
and [metric requirement level](../specification/metrics/metric-requirement-level.md) conventions. and [metric requirement level](../specification/metrics/metric-requirement-level.md) conventions.
Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.16.0/semantic-conventions/syntax.md) Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.17.0/semantic-conventions/syntax.md)
for how to write the YAML files for semantic conventions and what the YAML properties mean. for how to write the YAML files for semantic conventions and what the YAML properties mean.
A schema file for VS code is configured in the `/.vscode/settings.json` of this A schema file for VS code is configured in the `/.vscode/settings.json` of this
repository, enabling auto-completion and additional checks. Refer to repository, enabling auto-completion and additional checks. Refer to
[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.16.0/semantic-conventions/README.md) for what extension you need. [the generator README](https://github.com/open-telemetry/build-tools/tree/v0.17.0/semantic-conventions/README.md) for what extension you need.
## Generating markdown ## Generating markdown
@ -35,7 +35,7 @@ formatted Markdown tables for all semantic conventions in the specification. Run
make table-generation make table-generation
``` ```
For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.16.0/semantic-conventions) For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.17.0/semantic-conventions)
in the OpenTelemetry build tools repository. in the OpenTelemetry build tools repository.
Using this build tool, it is also possible to generate code for use in OpenTelemetry Using this build tool, it is also possible to generate code for use in OpenTelemetry
language projects. language projects.

6
semantic_conventions/resource/cloud_provider/heroku.yaml
View File

@ -10,16 +10,16 @@ groups:
brief: > brief: >
Time and date the release was created Time and date the release was created
examples: [ '2022-10-23T18:00:42Z' ] examples: [ '2022-10-23T18:00:42Z' ]
requirement_level: optional requirement_level: opt_in
- id: release.commit - id: release.commit
type: string type: string
brief: > brief: >
Commit hash for the current release Commit hash for the current release
examples: [ 'e6134959463efd8966b20e75b913cafe3f5ec' ] examples: [ 'e6134959463efd8966b20e75b913cafe3f5ec' ]
requirement_level: optional requirement_level: opt_in
- id: app.id - id: app.id
type: string type: string
brief: > brief: >
Unique identifier for the application Unique identifier for the application
examples: [ '2daa2797-e42b-4624-9322-ec3f968df4da' ] examples: [ '2daa2797-e42b-4624-9322-ec3f968df4da' ]
requirement_level: optional requirement_level: opt_in

2
semantic_conventions/trace/http.yaml
View File

@ -149,5 +149,5 @@ groups:
if it's sent in absolute-form. if it's sent in absolute-form.
- Port identifier of the `Host` header - Port identifier of the `Host` header
- ref: net.sock.host.addr - ref: net.sock.host.addr
requirement_level: optional requirement_level: opt_in
- ref: net.sock.host.port - ref: net.sock.host.port

4
specification/metrics/semantic_conventions/hardware-metrics.md
View File

@ -42,10 +42,10 @@ Additionally, it is recommended that all metrics in `hw.` instruments have the
below attributes: below attributes:
| Attribute Key | Description | Example | Requirement Level | | Attribute Key | Description | Example | Requirement Level |
| ------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ----------------- | | ------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------- |-------------------|
| `id` | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | Required | | `id` | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | Required |
| `name` | An easily-recognizable name for the hardware component | `eth0` | Recommended | | `name` | An easily-recognizable name for the hardware component | `eth0` | Recommended |
| `parent` | Unique identifier of the parent component (typically the `id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | Optional | | `parent` | Unique identifier of the parent component (typically the `id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | Opt-In |
## Metric Instruments ## Metric Instruments

6
specification/resource/semantic_conventions/cloud_provider/heroku.md
View File

@ -9,9 +9,9 @@
<!-- semconv heroku --> <!-- semconv heroku -->
| Attribute | Type | Description | Examples | Requirement Level | | Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---| |---|---|---|---|---|
| `heroku.release.creation_timestamp` | string | Time and date the release was created | `2022-10-23T18:00:42Z` | Optional | | `heroku.release.creation_timestamp` | string | Time and date the release was created | `2022-10-23T18:00:42Z` | Opt-In |
| `heroku.release.commit` | string | Commit hash for the current release | `e6134959463efd8966b20e75b913cafe3f5ec` | Optional | | `heroku.release.commit` | string | Commit hash for the current release | `e6134959463efd8966b20e75b913cafe3f5ec` | Opt-In |
| `heroku.app.id` | string | Unique identifier for the application | `2daa2797-e42b-4624-9322-ec3f968df4da` | Optional | | `heroku.app.id` | string | Unique identifier for the application | `2daa2797-e42b-4624-9322-ec3f968df4da` | Opt-In |
<!-- endsemconv --> <!-- endsemconv -->
**Mapping:** **Mapping:**

8
specification/trace/semantic_conventions/http.md
View File

@ -113,9 +113,9 @@ It is recommended to also use the general [socket-level attributes][] - `net.soc
### HTTP request and response headers ### HTTP request and response headers
| Attribute | Type | Description | Examples | Requirement Level | | Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---| |---|---|---|---|-------------------|
| `http.request.header.<key>` | string[] | HTTP request headers, `<key>` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [1] [2] | `http.request.header.content_type=["application/json"]`; `http.request.header.x_forwarded_for=["1.2.3.4", "1.2.3.5"]` | Optional | | `http.request.header.<key>` | string[] | HTTP request headers, `<key>` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [1] [2] | `http.request.header.content_type=["application/json"]`; `http.request.header.x_forwarded_for=["1.2.3.4", "1.2.3.5"]` | Opt-In |
| `http.response.header.<key>` | string[] | HTTP response headers, `<key>` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [1] [2] | `http.response.header.content_type=["application/json"]`; `http.response.header.my_custom_header=["abc", "def"]` | Optional | | `http.response.header.<key>` | string[] | HTTP response headers, `<key>` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [1] [2] | `http.response.header.content_type=["application/json"]`; `http.response.header.my_custom_header=["abc", "def"]` | Opt-In |
**[1]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. **[1]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured.
Including all request/response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. Including all request/response headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
@ -248,7 +248,7 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i
| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | | `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required |
| [`net.host.name`](span-general.md) | string | Name of the local HTTP server that received the request. [3] | `localhost` | Required | | [`net.host.name`](span-general.md) | string | Name of the local HTTP server that received the request. [3] | `localhost` | Required |
| [`net.host.port`](span-general.md) | int | Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | | [`net.host.port`](span-general.md) | int | Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] |
| [`net.sock.host.addr`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host. | `192.168.0.1` | Optional | | [`net.sock.host.addr`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host. | `192.168.0.1` | Opt-In |
| [`net.sock.host.port`](span-general.md) | int | Local socket port number. | `35555` | Recommended: [6] | | [`net.sock.host.port`](span-general.md) | int | Local socket port number. | `35555` | Recommended: [6] |
**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.

4
specification/trace/semantic_conventions/rpc.md
View File

@ -212,8 +212,8 @@ The [Span Status](../api.md#set-status) MUST be left unset for an `OK` gRPC stat
| Attribute | Type | Description | Examples | Requirement Level | | Attribute | Type | Description | Examples | Requirement Level |
|-------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|-------------------| |-------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|-------------------|
| `rpc.grpc.request.metadata.<key>` | string[] | gRPC request metadata, `<key>` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.grpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]` | Optional | | `rpc.grpc.request.metadata.<key>` | string[] | gRPC request metadata, `<key>` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.grpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]` | Opt-In |
| `rpc.grpc.response.metadata.<key>` | string[] | gRPC response metadata, `<key>` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.grpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Optional | | `rpc.grpc.response.metadata.<key>` | string[] | gRPC response metadata, `<key>` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.grpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Opt-In |
**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. **[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured.
Including all request/response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. Including all request/response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.