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,
},
"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"
]
},

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
# 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.
.PHONY: all

2
internal/tools/schema_check.sh
View File

@ -6,7 +6,7 @@
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.
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),
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.
A schema file for VS code is configured in the `/.vscode/settings.json` of this
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
@ -35,7 +35,7 @@ formatted Markdown tables for all semantic conventions in the specification. Run
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.
Using this build tool, it is also possible to generate code for use in OpenTelemetry
language projects.

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

@ -10,16 +10,16 @@ groups:
brief: >
Time and date the release was created
examples: [ '2022-10-23T18:00:42Z' ]
requirement_level: optional
requirement_level: opt_in
- id: release.commit
type: string
brief: >
Commit hash for the current release
examples: [ 'e6134959463efd8966b20e75b913cafe3f5ec' ]
requirement_level: optional
requirement_level: opt_in
- id: app.id
type: string
brief: >
Unique identifier for the application
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.
- Port identifier of the `Host` header
- ref: net.sock.host.addr
requirement_level: optional
requirement_level: opt_in
- 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:
| Attribute Key | Description | Example | Requirement Level |
| ------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ----------------- |
| ------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------- |-------------------|
| `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 |
| `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

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

@ -9,9 +9,9 @@
<!-- semconv heroku -->
| 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.commit` | string | Commit hash for the current release | `e6134959463efd8966b20e75b913cafe3f5ec` | Optional |
| `heroku.app.id` | string | Unique identifier for the application | `2daa2797-e42b-4624-9322-ec3f968df4da` | 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` | Opt-In |
| `heroku.app.id` | string | Unique identifier for the application | `2daa2797-e42b-4624-9322-ec3f968df4da` | Opt-In |
<!-- endsemconv -->
**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
| 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.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.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"]` | Opt-In |
**[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.
@ -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 |
| [`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.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] |
**[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 |
|-------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|-------------------|
| `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.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.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"]` | Opt-In |
**[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.