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

Adopt attribute requirement levels in semantic conventions (#2594)

This commit is contained in:
Liudmila Molkova 2022-06-14 08:02:55 -07:00 committed by GitHub
parent 48b522e7f3
commit 3f7b7d02f9
46 changed files with 498 additions and 486 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.11.0/semantic-conventions/semconv.schema.json": [
"https://raw.githubusercontent.com/open-telemetry/build-tools/v0.12.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.11.0
SEMCONVGEN_VERSION=0.12.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.11.0
BUILD_TOOL_SCHEMAS_VERSION=0.12.0
# List of vesions 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

@ -17,12 +17,12 @@ i.e.:
Semantic conventions for the spec MUST adhere to the
[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)
Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.12.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.11.0/semantic-conventions/README.md) for what extension you need.
[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.12.0/semantic-conventions/README.md) for what extension you need.
## Generating markdown
@ -33,7 +33,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.11.0/semantic-conventions)
For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.12.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.

2
semantic_conventions/resource/faas.yaml
View File

@ -6,7 +6,7 @@ groups:
attributes:
- id: name
type: string
required: always
requirement_level: required
brief: >
The name of the single function that this runtime instance executes.
note: |

2
semantic_conventions/resource/os.yaml
View File

@ -44,7 +44,7 @@ groups:
- id: z_os
value: 'z_os'
brief: "IBM z/OS"
required: always
requirement_level: required
brief: 'The operating system type.'
- id: description
type: string

28
semantic_conventions/resource/process.yaml
View File

@ -11,8 +11,8 @@ groups:
examples: [1234]
- id: executable.name
type: string
required:
conditional: "See below"
requirement_level:
conditionally_required: See alternative attributes below.
brief: >
The name of the process executable. On Linux based systems, can be set
to the `Name` in `proc/[pid]/status`. On Windows, can be set to the
@ -20,8 +20,8 @@ groups:
examples: ['otelcol']
- id: executable.path
type: string
required:
conditional: "See below"
requirement_level:
conditionally_required: See alternative attributes below.
brief: >
The full path to the process executable. On Linux based systems, can
be set to the target of `proc/[pid]/exe`. On Windows, can be set to the
@ -29,8 +29,8 @@ groups:
examples: ['/usr/bin/cmd/otelcol']
- id: command
type: string
required:
conditional: "See below"
requirement_level:
conditionally_required: See alternative attributes below.
brief: >
The command used to launch the process (i.e. the command name). On Linux
based systems, can be set to the zeroth string in `proc/[pid]/cmdline`.
@ -38,8 +38,8 @@ groups:
examples: ['cmd/otelcol']
- id: command_line
type: string
required:
conditional: "See below"
requirement_level:
conditionally_required: See alternative attributes below.
brief: >
The full command used to launch the process as a single string representing
the full command. On Windows, can be set to the result of `GetCommandLineW`.
@ -48,8 +48,8 @@ groups:
examples: ['C:\cmd\otecol --config="my directory\config.yaml"']
- id: command_args
type: string[]
required:
conditional: "See below"
requirement_level:
conditionally_required: See alternative attributes below.
brief: >
All the command arguments (including the command/executable itself) as
received by the process. On Linux-based systems (and some other Unixoid
@ -62,6 +62,14 @@ groups:
brief: >
The username of the user that owns the process.
examples: 'root'
constraints:
- any_of:
- process.executable.name
- process.executable.path
- process.command
- process.command_line
- process.command_args
- id: process.runtime
prefix: process.runtime
brief: >

2
semantic_conventions/resource/service.yaml
View File

@ -6,7 +6,7 @@ groups:
attributes:
- id: name
type: string
required: always
requirement_level: required
brief: >
Logical name of the service.
note: >

2
semantic_conventions/resource/webengine.yaml
View File

@ -6,7 +6,7 @@ groups:
attributes:
- id: name
type: string
required: always
requirement_level: required
brief: >
The name of the web engine.
examples: ['WildFly']

8
semantic_conventions/trace/cloudevents.yaml
View File

@ -8,25 +8,25 @@ groups:
attributes:
- id: event_id
type: string
required: always
requirement_level: required
brief: >
The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event.
examples: ['123e4567-e89b-12d3-a456-426614174000', '0001']
- id: event_source
type: string
required: always
requirement_level: required
brief: >
The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened.
examples: ['https://github.com/cloudevents', '/cloudevents/spec/pull/123', 'my-service' ]
- id: event_spec_version
type: string
required: always
requirement_level: required
brief: >
The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses.
examples: '1.0'
- id: event_type
type: string
required: always
requirement_level: required
brief: >
The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence.
examples: ['com.github.pull_request.opened', 'com.example.object.deleted.v2']

44
semantic_conventions/trace/database.yaml
View File

@ -8,7 +8,7 @@ groups:
- id: system
tag: connection-level
brief: An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers.
required: always
requirement_level: required
type:
allow_custom_values: true
members:
@ -175,8 +175,8 @@ groups:
- id: name
tag: call-level
type: string
required:
conditional: Required, if applicable.
requirement_level:
conditionally_required: If applicable.
brief: >
This attribute is used to report the name of the database being accessed.
For commands that switch the database, this should be set to the target database
@ -190,9 +190,9 @@ groups:
- id: statement
tag: call-level
type: string
required:
conditional: >
Required if applicable and not explicitly disabled via instrumentation configuration.
requirement_level:
conditionally_required: >
If applicable and not explicitly disabled via instrumentation configuration.
brief: >
The database statement being executed.
note: The value may be sanitized to exclude sensitive information.
@ -200,8 +200,8 @@ groups:
- id: operation
tag: call-level
type: string
required:
conditional: Required, if `db.statement` is not applicable.
requirement_level:
conditionally_required: If `db.statement` is not applicable.
brief: >
The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations)
such as `findAndModify`, or the SQL keyword.
@ -215,20 +215,20 @@ groups:
examples: ['findAndModify', 'HMSET', 'SELECT']
- ref: net.peer.name
tag: connection-level
required:
conditional: See below.
requirement_level:
conditionally_required: See alternative attributes below.
- ref: net.peer.ip
tag: connection-level
required:
conditional: See below.
requirement_level:
conditionally_required: See alternative attributes below.
- ref: net.peer.port
tag: connection-level
required:
conditional: Required if using a port other than the default port for this DBMS.
requirement_level:
conditionally_required: If using a port other than the default port for this DBMS.
- ref: net.transport
tag: connection-level
required:
conditional: Recommended in general, required for in-process databases (`"inproc"`).
requirement_level:
conditionally_required: If database type is in-process (`"inproc"`), recommended for other database types.
constraints:
- any_of:
- 'net.peer.name'
@ -294,8 +294,7 @@ groups:
- id: table
type: string
tag: call-level-tech-specific-cassandra
required:
conditional: Recommended if available.
requirement_level: recommended
brief: The name of the primary table that the operation is acting upon, including the keyspace name (if applicable).
note: >
This mirrors the db.sql.table attribute but references cassandra rather than sql.
@ -337,8 +336,8 @@ groups:
attributes:
- id: database_index
type: int
required:
conditional: Required, if other than the default database (`0`).
requirement_level:
conditionally_required: If other than the default database (`0`).
tag: call-level-tech-specific
brief: >
The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer.
@ -353,7 +352,7 @@ groups:
attributes:
- id: collection
type: string
required: always
requirement_level: required
tag: call-level-tech-specific
brief: >
The collection being accessed within the database stated in `db.name`.
@ -368,8 +367,7 @@ groups:
- id: table
tag: call-level-tech-specific
type: string
required:
conditional: Recommended if available.
requirement_level: recommended
brief: The name of the primary table that the operation is acting upon, including the database name (if applicable).
note: >
It is not recommended to attempt any client-side parsing of

18
semantic_conventions/trace/faas.yaml
View File

@ -50,14 +50,14 @@ groups:
attributes:
- id: collection
type: string
required: always
requirement_level: required
brief: >
The name of the source on which the triggering operation was performed.
For example, in Cloud Storage or S3 corresponds to the bucket name,
and in Cosmos DB to the database name.
examples: ['myBucketName', 'myDbName']
- id: operation
required: always
requirement_level: required
type:
allow_custom_values: true
members:
@ -73,7 +73,7 @@ groups:
brief: 'Describes the type of the operation that was performed on the data.'
- id: time
type: string
required: always
requirement_level: required
brief: >
A string containing the time when the data was accessed in the
[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)
@ -111,7 +111,7 @@ groups:
attributes:
- id: time
type: string
required: always
requirement_level: required
brief: >
A string containing the function invocation time in the
[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)
@ -137,7 +137,7 @@ groups:
A boolean that is true if the serverless function is executed for the
first time (aka cold-start).
- ref: faas.trigger
required: always
requirement_level: required
- id: faas_span.out
extends: faas_span
@ -148,7 +148,7 @@ groups:
attributes:
- id: invoked_name
type: string
required: always
requirement_level: required
brief: >
The name of the invoked function.
note: >
@ -174,7 +174,7 @@ groups:
- id: 'tencent_cloud'
value: 'tencent_cloud'
brief: 'Tencent Cloud'
required: always
requirement_level: required
brief: >
The cloud provider of the invoked function.
note: >
@ -182,8 +182,8 @@ groups:
invoked function.
- id: invoked_region
type: string
required:
conditional: >
requirement_level:
conditionally_required: >
For some cloud providers, like AWS or GCP, the region in which a
function is hosted is essential to uniquely identify the function
and also part of its endpoint. Since it's part of the endpoint

10
semantic_conventions/trace/http.yaml
View File

@ -8,7 +8,7 @@ groups:
attributes:
- id: method
type: string
required: always
requirement_level: required
brief: 'HTTP request method.'
sampling_relevant: true
examples: ["GET", "POST", "HEAD"]
@ -47,8 +47,8 @@ groups:
examples: ["http", "https"]
- id: status_code
type: int
required:
conditional: If and only if one was received/sent.
requirement_level:
conditionally_required: If and only if one was received/sent.
brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).'
examples: [200]
- id: flavor
@ -111,8 +111,8 @@ groups:
type: int
brief: >
The ordinal number of request re-sending attempt.
required:
conditional: If and only if a request was retried.
requirement_level:
recommended: If and only if a request was retried.
examples: 3
- ref: net.peer.ip
sampling_relevant: true

4
semantic_conventions/trace/instrumentation/aws-sdk.yml
View File

@ -12,7 +12,7 @@ groups:
attributes:
- ref: rpc.system
brief: "The value `aws-api`."
required: always
requirement_level: required
examples:
- aws-api
- ref: rpc.service
@ -31,7 +31,7 @@ groups:
attributes:
- ref: db.system
brief: "The value `dynamodb`."
required: always
requirement_level: required
examples:
- dynamodb

34
semantic_conventions/trace/messaging.yaml
View File

@ -7,12 +7,12 @@ groups:
attributes:
- id: system
type: string
required: always
requirement_level: required
brief: 'A string identifying the messaging system.'
examples: ['kafka', 'rabbitmq', 'rocketmq', 'activemq', 'AmazonSQS']
- id: destination
type: string
required: always
requirement_level: required
brief: >
The message destination name. This might be equal to the span name
but is required nevertheless.
@ -27,13 +27,13 @@ groups:
- id: topic
value: "topic"
brief: "A message sent to a topic"
required:
conditional: 'Required only if the message destination is either a `queue` or `topic`.'
requirement_level:
conditionally_required: If the message destination is either a `queue` or `topic`.
brief: 'The kind of message destination'
- id: temp_destination
type: boolean
required:
conditional: 'If missing, it is assumed to be false.'
requirement_level:
conditionally_required: If value is `true`. When missing, the value is assumed to be `false`.
brief: 'A boolean that is true if the message destination is temporary.'
- id: protocol
type: string
@ -70,12 +70,12 @@ groups:
- ref: net.peer.name
note: >
This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from.
required:
conditional: If available.
requirement_level:
conditionally_required: If available.
- ref: net.peer.ip
tag: connection-level
required:
conditional: If available.
requirement_level:
conditionally_required: If available.
constraints:
- include: network
@ -137,8 +137,8 @@ groups:
attributes:
- id: routing_key
type: string
required:
conditional: Unless it is empty.
requirement_level:
conditionally_required: If not empty.
brief: >
RabbitMQ message routing key.
examples: 'myKey'
@ -177,8 +177,8 @@ groups:
examples: 2
- id: tombstone
type: boolean
required:
conditional: 'If missing, it is assumed to be false.'
requirement_level:
conditionally_required: If value is `true`. When missing, the value is assumed to be `false`.
brief: 'A boolean that is true if the message is a tombstone.'
- id: messaging.rocketmq
@ -189,19 +189,19 @@ groups:
attributes:
- id: namespace
type: string
required: always
requirement_level: required
brief: >
Namespace of RocketMQ resources, resources in different namespaces are individual.
examples: 'myNamespace'
- id: client_group
type: string
required: always
requirement_level: required
brief: >
Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind.
examples: 'myConsumerGroup'
- id: client_id
type: string
required: always
requirement_level: required
brief: >
The unique identifier for each client.
examples: 'myhost@8742@s8083jm'

28
semantic_conventions/trace/rpc.yaml
View File

@ -5,7 +5,7 @@ groups:
events: [rpc.message]
attributes:
- id: system
required: always
requirement_level: required
brief: 'A string identifying the remoting system. See below for a list of well-known identifiers.'
type:
allow_custom_values: true
@ -24,8 +24,7 @@ groups:
brief: 'Apache Dubbo'
- id: service
type: string
required:
conditional: "No, but recommended"
requirement_level: recommended
brief: 'The full (logical) name of the service being called, including its package name, if applicable.'
note: >
This is the logical name of the service from the RPC interface perspective,
@ -37,8 +36,7 @@ groups:
examples: "myservice.EchoService"
- id: method
type: string
required:
conditional: "No, but recommended"
requirement_level: recommended
brief: 'The name of the (logical) method being called, must be equal to the $method part in the span name.'
note: >
This is the logical name of the method from the RPC interface perspective,
@ -50,11 +48,11 @@ groups:
- ref: net.peer.ip
- ref: net.peer.name
- ref: net.peer.port
required:
conditional: "See below"
requirement_level:
conditionally_required: See below
- ref: net.transport
required:
conditional: "See below"
requirement_level:
conditionally_required: See below
constraints:
- any_of:
- net.peer.ip
@ -129,7 +127,7 @@ groups:
- id: unauthenticated
brief: UNAUTHENTICATED
value: 16
required: always
requirement_level: required
brief: "The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request."
- id: rpc.jsonrpc
@ -139,8 +137,8 @@ groups:
attributes:
- id: version
type: string
required:
conditional: 'If missing, it is assumed to be "1.0".'
requirement_level:
conditionally_required: If other than the default version (`1.0`)
brief: "Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 does not specify this, the value can be omitted."
examples: ['2.0', '1.0']
- id: request_id
@ -153,8 +151,8 @@ groups:
examples: ['10', 'request-7', '']
- id: error_code
type: int
required:
conditional: 'If missing, response is assumed to be successful.'
requirement_level:
conditionally_required: If response is not successful.
brief: "`error.code` property of response if it is an error response."
examples: [-32700, 100]
- id: error_message
@ -162,7 +160,7 @@ groups:
brief: "`error.message` property of response if it is an error response."
examples: ['Parse error', 'User already exists']
- ref: rpc.method
required: always
requirement_level: required
note: >
This is always required for jsonrpc. See the note in the general
RPC conventions for more information.

12
specification/metrics/semantic_conventions/database-metrics.md
View File

@ -31,9 +31,9 @@ instrumentations:
All `db.client.connections.usage` measurements MUST include the following attribute:
| Name | Type | Description | Examples | Required |
|---------|--------|------------------------------------------------------------------------------|----------|----------|
| `state` | string | The state of a connection in the pool. Valid values include: `idle`, `used`. | `idle` | Yes |
| Name | Type | Description | Examples | Requirement Level |
|---------|--------|------------------------------------------------------------------------------|----------|-------------------|
| `state` | string | The state of a connection in the pool. Valid values include: `idle`, `used`. | `idle` | Required |
Instrumentation libraries for database client connection pools that collect data for the following data MUST use the
following metric instruments. Otherwise, if the instrumentation library does not collect this data, these instruments
@ -52,6 +52,6 @@ MUST NOT be used.
Below is a table of the attributes that MUST be included on all connection pool measurements:
| Name | Type | Description | Examples | Required |
|-------------|--------|------------------------------------------------------------------------------|----------------|----------|
| `pool.name` | string | The name of the connection pool; unique within the instrumented application. | `myDataSource` | Yes |
| Name | Type | Description | Examples | Requirement Level |
|-------------|--------|------------------------------------------------------------------------------|----------------|-------------------|
| `pool.name` | string | The name of the connection pool; unique within the instrumented application. | `myDataSource` | Required |

12
specification/metrics/semantic_conventions/faas-metrics.md
View File

@ -53,12 +53,12 @@ Optionally, when applicable:
Below is a table of the attributes to be included on FaaS metric events.
| Name | Recommended | Notes and examples |
|-------------------------|-------------|--------------------------------------------------------------------------------------------------------------------------|
| `faas.trigger` | Yes | Type of the trigger on which the function is invoked. SHOULD be one of: `datasource`, `http`, `pubsub`, `timer`, `other` |
| `faas.invoked_name` | Yes | Name of the invoked function. Example: `my-function` |
| `faas.invoked_provider` | Yes | Cloud provider of the invoked function. Corresponds to the resource `cloud.provider`. Example: `aws` |
| `faas.invoked_region` | Yes | Cloud provider region of invoked function. Corresponds to resource `cloud.region`. Example: `us-east-1` |
| Name | Requirement Level | Notes and examples |
|-------------------------|-------------------|--------------------------------------------------------------------------------------------------------------------------|
| `faas.trigger` | Required | Type of the trigger on which the function is invoked. SHOULD be one of: `datasource`, `http`, `pubsub`, `timer`, `other` |
| `faas.invoked_name` | Required | Name of the invoked function. Example: `my-function` |
| `faas.invoked_provider` | Required | Cloud provider of the invoked function. Corresponds to the resource `cloud.provider`. Example: `aws` |
| `faas.invoked_region` | Required | Cloud provider region of invoked function. Corresponds to resource `cloud.region`. Example: `us-east-1` |
More details on these attributes, the function name and the difference compared to the faas.invoked_name can be found at the related [FaaS tracing specification](../../trace/semantic_conventions/faas.md).
For incoming FaaS executions, the function for which metrics are reported is already described by its [FaaS resource attributes](../../resource/semantic_conventions/faas.md).

16
specification/metrics/semantic_conventions/http-metrics.md
View File

@ -35,13 +35,13 @@ Below is a table of HTTP client metric instruments.
Below is a table of the attributes that SHOULD be included on `duration` metric events
and whether they should be on server, client, or both types of HTTP metric events:
| Name | Type | Recommended | Notes and examples |
| Name | Type | Requirement Level | Notes and examples |
|--------------------|---------------------|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `http.method` | `client` & `server` | Yes | The HTTP request method. E.g. `"GET"` |
| `http.method` | `client` & `server` | Required | The HTTP request method. E.g. `"GET"` |
| `http.host` | `client` & `server` | see [attribute alternatives](#attribute-alternatives) | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same. |
| `http.scheme` | `client` & `server` | see [attribute alternatives](#attribute-alternatives) | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"` |
| `http.status_code` | `client` & `server` | Optional | [HTTP response status code][]. E.g. `200` (String) |
| `http.flavor` | `client` & `server` | Optional | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. |
| `http.status_code` | `client` & `server` | Conditionally required | [HTTP response status code][]. E.g. `200` (String) |
| `http.flavor` | `client` & `server` | Recommended | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. |
| `net.peer.name` | `client` | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) |
| `net.peer.port` | `client` | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) |
| `net.peer.ip` | `client` | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) |
@ -51,12 +51,12 @@ and whether they should be on server, client, or both types of HTTP metric event
The following attributes SHOULD be included in the `http.server.active_requests` observation:
| Name | Recommended | Notes and examples |
| Name | Requirement Level | Notes and examples |
|--------------------|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `http.method` | Yes | The HTTP request method. E.g. `"GET"` |
| `http.method` | Required | The HTTP request method. E.g. `"GET"` |
| `http.host` | see [attribute alternatives](#attribute-alternatives) | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same |
| `http.scheme` | see [attribute alternatives](#attribute-alternatives) | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"` |
| `http.flavor` | Optional | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"` |
| `http.flavor` | Recommended | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"` |
| `http.server_name` | see [2] in [attribute alternatives](#attribute-alternatives) | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). |
[HTTP host header]: https://tools.ietf.org/html/rfc7230#section-5.4
@ -67,7 +67,7 @@ The following attributes SHOULD be included in the `http.server.active_requests`
To avoid high cardinality the following attributes SHOULD substitute any parameters when added as attributes to http metric events as described below:
| Attribute name | Type | Recommended | Notes and examples |
| Attribute name | Type | Requirement Level | Notes and examples |
|----------------|---------------------|-------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
| `http.url` | `client` & `server` | see [attribute alternatives](#attribute-alternatives) | The originally requested URL |
| `http.target` | `client` & `server` | see [attribute alternatives](#attribute-alternatives) | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/{id}/?q={}"`. |

12
specification/metrics/semantic_conventions/rpc.md
View File

@ -58,15 +58,15 @@ Below is a table of attributes that SHOULD be included on metric events and whet
or not they should be on the server, client or both.
<!-- semconv rpc -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| [`rpc.system`](../../trace/semantic_conventions/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Yes |
| [`rpc.service`](../../trace/semantic_conventions/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | No, but recommended |
| [`rpc.method`](../../trace/semantic_conventions/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | No, but recommended |
| [`rpc.system`](../../trace/semantic_conventions/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required |
| [`rpc.service`](../../trace/semantic_conventions/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended |
| [`rpc.method`](../../trace/semantic_conventions/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended |
| [`net.peer.ip`](../../trace/semantic_conventions/span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | See below |
| [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Remote hostname or similar, see note below. [3] | `example.com` | See below |
| [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Remote port number. | `80`; `8080`; `443` | See below |
| [`net.transport`](../../trace/semantic_conventions/span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | See below |
| [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Remote port number. | `80`; `8080`; `443` | Conditionally Required: See below |
| [`net.transport`](../../trace/semantic_conventions/span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: See below |
**[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).

20
specification/resource/semantic_conventions/README.md
View File

@ -63,12 +63,12 @@ as specified in the [Resource SDK specification](../sdk.md#sdk-provided-resource
**Description:** A service instance.
<!-- semconv service -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `service.name` | string | Logical name of the service. [1] | `shoppingcart` | Yes |
| `service.namespace` | string | A namespace for `service.name`. [2] | `Shop` | No |
| `service.instance.id` | string | The string ID of the service instance. [3] | `627cc493-f310-47de-96bd-71410b7dec09` | No |
| `service.version` | string | The version string of the service API or implementation. | `2.0.0` | No |
| `service.name` | string | Logical name of the service. [1] | `shoppingcart` | Required |
| `service.namespace` | string | A namespace for `service.name`. [2] | `Shop` | Recommended |
| `service.instance.id` | string | The string ID of the service instance. [3] | `627cc493-f310-47de-96bd-71410b7dec09` | Recommended |
| `service.version` | string | The version string of the service API or implementation. | `2.0.0` | Recommended |
**[1]:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md#process), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`.
@ -107,12 +107,12 @@ The identifier `opentelemetry` is reserved and MUST NOT be used in this case.
The identifier SHOULD be stable across different versions of an implementation.
<!-- semconv telemetry -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. | `opentelemetry` | No |
| `telemetry.sdk.language` | string | The language of the telemetry SDK. | `cpp` | No |
| `telemetry.sdk.version` | string | The version string of the telemetry SDK. | `1.2.3` | No |
| `telemetry.auto.version` | string | The version string of the auto instrumentation agent, if used. | `1.2.3` | No |
| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. | `opentelemetry` | Recommended |
| `telemetry.sdk.language` | string | The language of the telemetry SDK. | `cpp` | Recommended |
| `telemetry.sdk.version` | string | The version string of the telemetry SDK. | `1.2.3` | Recommended |
| `telemetry.auto.version` | string | The version string of the auto instrumentation agent, if used. | `1.2.3` | Recommended |
`telemetry.sdk.language` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

8
specification/resource/semantic_conventions/browser.md
View File

@ -9,11 +9,11 @@
All of these attributes can be provided by the user agent itself in the form of an HTTP header (e.g. Sec-CH-UA, Sec-CH-Platform, User-Agent). However, the headers could be removed by proxy servers, and are tied to calls from individual clients. In order to support batching through services like the Collector and to prevent loss of data (e.g. due to proxy servers removing headers), these attributes should be used when possible.
<!-- semconv browser -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `browser.brands` | string[] | Array of brand name and version separated by a space [1] | `[ Not A;Brand 99, Chromium 99, Chrome 99]` | No |
| `browser.platform` | string | The platform on which the browser is running [2] | `Windows`; `macOS`; `Android` | No |
| `browser.user_agent` | string | Full user-agent string provided by the browser [3] | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36` | No |
| `browser.brands` | string[] | Array of brand name and version separated by a space [1] | `[ Not A;Brand 99, Chromium 99, Chrome 99]` | Recommended |
| `browser.platform` | string | The platform on which the browser is running [2] | `Windows`; `macOS`; `Android` | Recommended |
| `browser.user_agent` | string | Full user-agent string provided by the browser [3] | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36` | Recommended |
**[1]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (navigator.userAgentData.brands).

12
specification/resource/semantic_conventions/cloud.md
View File

@ -7,13 +7,13 @@
**Description:** A cloud infrastructure (e.g. GCP, Azure, AWS).
<!-- semconv cloud -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `cloud.provider` | string | Name of the cloud provider. | `alibaba_cloud` | No |
| `cloud.account.id` | string | The cloud account ID the resource is assigned to. | `111111111111`; `opentelemetry` | No |
| `cloud.region` | string | The geographical region the resource is running. [1] | `us-central1`; `us-east-1` | No |
| `cloud.availability_zone` | string | Cloud regions often have multiple, isolated locations known as zones to increase availability. Availability zone represents the zone where the resource is running. [2] | `us-east-1c` | No |
| `cloud.platform` | string | The cloud platform in use. [3] | `alibaba_cloud_ecs` | No |
| `cloud.provider` | string | Name of the cloud provider. | `alibaba_cloud` | Recommended |
| `cloud.account.id` | string | The cloud account ID the resource is assigned to. | `111111111111`; `opentelemetry` | Recommended |
| `cloud.region` | string | The geographical region the resource is running. [1] | `us-central1`; `us-east-1` | Recommended |
| `cloud.availability_zone` | string | Cloud regions often have multiple, isolated locations known as zones to increase availability. Availability zone represents the zone where the resource is running. [2] | `us-east-1c` | Recommended |
| `cloud.platform` | string | The cloud platform in use. [3] | `alibaba_cloud_ecs` | Recommended |
**[1]:** Refer to your provider's docs to see the available regions, for example [Alibaba Cloud regions](https://www.alibabacloud.com/help/doc-detail/40654.htm), [AWS regions](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/), [Azure regions](https://azure.microsoft.com/en-us/global-infrastructure/geographies/), [Google Cloud regions](https://cloud.google.com/about/locations), or [Tencent Cloud regions](https://intl.cloud.tencent.com/document/product/213/6091).

14
specification/resource/semantic_conventions/cloud_provider/aws/ecs.md
View File

@ -7,14 +7,14 @@
**Description:** Resources used by AWS Elastic Container Service (ECS).
<!-- semconv aws.ecs -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.ecs.container.arn` | string | The Amazon Resource Name (ARN) of an [ECS container instance](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_instances.html). | `arn:aws:ecs:us-west-1:123456789123:container/32624152-9086-4f0e-acae-1a75b14fe4d9` | No |
| `aws.ecs.cluster.arn` | string | The ARN of an [ECS cluster](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/clusters.html). | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | No |
| `aws.ecs.launchtype` | string | The [launch type](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_types.html) for an ECS task. | `ec2` | No |
| `aws.ecs.task.arn` | string | The ARN of an [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html). | `arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b` | No |
| `aws.ecs.task.family` | string | The task definition family this task definition is a member of. | `opentelemetry-family` | No |
| `aws.ecs.task.revision` | string | The revision for this task definition. | `8`; `26` | No |
| `aws.ecs.container.arn` | string | The Amazon Resource Name (ARN) of an [ECS container instance](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_instances.html). | `arn:aws:ecs:us-west-1:123456789123:container/32624152-9086-4f0e-acae-1a75b14fe4d9` | Recommended |
| `aws.ecs.cluster.arn` | string | The ARN of an [ECS cluster](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/clusters.html). | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | Recommended |
| `aws.ecs.launchtype` | string | The [launch type](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_types.html) for an ECS task. | `ec2` | Recommended |
| `aws.ecs.task.arn` | string | The ARN of an [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html). | `arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b` | Recommended |
| `aws.ecs.task.family` | string | The task definition family this task definition is a member of. | `opentelemetry-family` | Recommended |
| `aws.ecs.task.revision` | string | The revision for this task definition. | `8`; `26` | Recommended |
`aws.ecs.launchtype` MUST be one of the following:

4
specification/resource/semantic_conventions/cloud_provider/aws/eks.md
View File

@ -7,7 +7,7 @@
**Description:** Resources used by AWS Elastic Kubernetes Service (EKS).
<!-- semconv aws.eks -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.eks.cluster.arn` | string | The ARN of an EKS cluster. | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | No |
| `aws.eks.cluster.arn` | string | The ARN of an EKS cluster. | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | Recommended |
<!-- endsemconv -->

10
specification/resource/semantic_conventions/cloud_provider/aws/logs.md
View File

@ -7,12 +7,12 @@
**Description:** Log attributes for Amazon Web Services.
<!-- semconv aws.log -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.log.group.names` | string[] | The name(s) of the AWS log group(s) an application is writing to. [1] | `[/aws/lambda/my-function, opentelemetry-service]` | No |
| `aws.log.group.arns` | string[] | The Amazon Resource Name(s) (ARN) of the AWS log group(s). [2] | `[arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:*]` | No |
| `aws.log.stream.names` | string[] | The name(s) of the AWS log stream(s) an application is writing to. | `[logs/main/10838bed-421f-43ef-870a-f43feacbbb5b]` | No |
| `aws.log.stream.arns` | string[] | The ARN(s) of the AWS log stream(s). [3] | `[arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:log-stream:logs/main/10838bed-421f-43ef-870a-f43feacbbb5b]` | No |
| `aws.log.group.names` | string[] | The name(s) of the AWS log group(s) an application is writing to. [1] | `[/aws/lambda/my-function, opentelemetry-service]` | Recommended |
| `aws.log.group.arns` | string[] | The Amazon Resource Name(s) (ARN) of the AWS log group(s). [2] | `[arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:*]` | Recommended |
| `aws.log.stream.names` | string[] | The name(s) of the AWS log stream(s) an application is writing to. | `[logs/main/10838bed-421f-43ef-870a-f43feacbbb5b]` | Recommended |
| `aws.log.stream.arns` | string[] | The ARN(s) of the AWS log stream(s). [3] | `[arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:log-stream:logs/main/10838bed-421f-43ef-870a-f43feacbbb5b]` | Recommended |
**[1]:** Multiple log groups must be supported for cases like multi-container applications, where a single application has sidecar containers, and each write to their own log group.

12
specification/resource/semantic_conventions/container.md
View File

@ -7,11 +7,11 @@
**Description:** A container instance.
<!-- semconv container -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `container.name` | string | Container name used by container runtime. | `opentelemetry-autoconf` | No |
| `container.id` | string | Container ID. Usually a UUID, as for example used to [identify Docker containers](https://docs.docker.com/engine/reference/run/#container-identification). The UUID might be abbreviated. | `a3bf90e006b2` | No |
| `container.runtime` | string | The container runtime managing this container. | `docker`; `containerd`; `rkt` | No |
| `container.image.name` | string | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` | No |
| `container.image.tag` | string | Container image tag. | `0.1` | No |
| `container.name` | string | Container name used by container runtime. | `opentelemetry-autoconf` | Recommended |
| `container.id` | string | Container ID. Usually a UUID, as for example used to [identify Docker containers](https://docs.docker.com/engine/reference/run/#container-identification). The UUID might be abbreviated. | `a3bf90e006b2` | Recommended |
| `container.runtime` | string | The container runtime managing this container. | `docker`; `containerd`; `rkt` | Recommended |
| `container.image.name` | string | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` | Recommended |
| `container.image.tag` | string | Container image tag. | `0.1` | Recommended |
<!-- endsemconv -->

4
specification/resource/semantic_conventions/deployment_environment.md
View File

@ -7,7 +7,7 @@
**Description:** The software deployment.
<!-- semconv deployment -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `deployment.environment` | string | Name of the [deployment environment](https://en.wikipedia.org/wiki/Deployment_environment) (aka deployment tier). | `staging`; `production` | No |
| `deployment.environment` | string | Name of the [deployment environment](https://en.wikipedia.org/wiki/Deployment_environment) (aka deployment tier). | `staging`; `production` | Recommended |
<!-- endsemconv -->

10
specification/resource/semantic_conventions/device.md
View File

@ -7,12 +7,12 @@
**Description**: The device on which the process represented by this resource is running.
<!-- semconv device -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `device.id` | string | A unique identifier representing the device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | No |
| `device.model.identifier` | string | The model identifier for the device [2] | `iPhone3,4`; `SM-G920F` | No |
| `device.model.name` | string | The marketing name for the device model [3] | `iPhone 6s Plus`; `Samsung Galaxy S6` | No |
| `device.manufacturer` | string | The name of the device manufacturer [4] | `Apple`; `Samsung` | No |
| `device.id` | string | A unique identifier representing the device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | Recommended |
| `device.model.identifier` | string | The model identifier for the device [2] | `iPhone3,4`; `SM-G920F` | Recommended |
| `device.model.name` | string | The marketing name for the device model [3] | `iPhone 6s Plus`; `Samsung Galaxy S6` | Recommended |
| `device.manufacturer` | string | The name of the device manufacturer [4] | `Apple`; `Samsung` | Recommended |
**[1]:** The device identifier MUST only be defined using the values outlined below. This value is not an advertising identifier and MUST NOT be used as such. On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor). On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids) on best practices and exact implementation details. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence.

12
specification/resource/semantic_conventions/faas.md
View File

@ -14,13 +14,13 @@ See also:
## FaaS resource attributes
<!-- semconv faas_resource -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `faas.name` | string | The name of the single function that this runtime instance executes. [1] | `my-function`; `myazurefunctionapp/some-function-name` | Yes |
| `faas.id` | string | The unique ID of the single function that this runtime instance executes. [2] | `arn:aws:lambda:us-west-2:123456789012:function:my-function` | No |
| `faas.version` | string | The immutable version of the function being executed. [3] | `26`; `pinkfroid-00002` | No |
| `faas.instance` | string | The execution environment ID as a string, that will be potentially reused for other invocations to the same function/function version. [4] | `2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de` | No |
| `faas.max_memory` | int | The amount of memory available to the serverless function in MiB. [5] | `128` | No |
| `faas.name` | string | The name of the single function that this runtime instance executes. [1] | `my-function`; `myazurefunctionapp/some-function-name` | Required |
| `faas.id` | string | The unique ID of the single function that this runtime instance executes. [2] | `arn:aws:lambda:us-west-2:123456789012:function:my-function` | Recommended |
| `faas.version` | string | The immutable version of the function being executed. [3] | `26`; `pinkfroid-00002` | Recommended |
| `faas.instance` | string | The execution environment ID as a string, that will be potentially reused for other invocations to the same function/function version. [4] | `2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de` | Recommended |
| `faas.max_memory` | int | The amount of memory available to the serverless function in MiB. [5] | `128` | Recommended |
**[1]:** This is the name of the function as configured/deployed on the FaaS
platform and is usually different from the name of the callback

16
specification/resource/semantic_conventions/host.md
View File

@ -7,15 +7,15 @@
**Description:** A host is defined as a general computing instance.
<!-- semconv host -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `host.id` | string | Unique host ID. For Cloud, this must be the instance_id assigned by the cloud provider. | `opentelemetry-test` | No |
| `host.name` | string | Name of the host. On Unix systems, it may contain what the hostname command returns, or the fully qualified hostname, or another name specified by the user. | `opentelemetry-test` | No |
| `host.type` | string | Type of host. For Cloud, this must be the machine type. | `n1-standard-1` | No |
| `host.arch` | string | The CPU architecture the host system is running on. | `amd64` | No |
| `host.image.name` | string | Name of the VM image or OS install the host was instantiated from. | `infra-ami-eks-worker-node-7d4ec78312`; `CentOS-8-x86_64-1905` | No |
| `host.image.id` | string | VM image ID. For Cloud, this value is from the provider. | `ami-07b06b442921831e5` | No |
| `host.image.version` | string | The version string of the VM image as defined in [Version Attributes](README.md#version-attributes). | `0.1` | No |
| `host.id` | string | Unique host ID. For Cloud, this must be the instance_id assigned by the cloud provider. | `opentelemetry-test` | Recommended |
| `host.name` | string | Name of the host. On Unix systems, it may contain what the hostname command returns, or the fully qualified hostname, or another name specified by the user. | `opentelemetry-test` | Recommended |
| `host.type` | string | Type of host. For Cloud, this must be the machine type. | `n1-standard-1` | Recommended |
| `host.arch` | string | The CPU architecture the host system is running on. | `amd64` | Recommended |
| `host.image.name` | string | Name of the VM image or OS install the host was instantiated from. | `infra-ami-eks-worker-node-7d4ec78312`; `CentOS-8-x86_64-1905` | Recommended |
| `host.image.id` | string | VM image ID. For Cloud, this value is from the provider. | `ami-07b06b442921831e5` | Recommended |
| `host.image.version` | string | The version string of the VM image as defined in [Version Attributes](README.md#version-attributes). | `0.1` | Recommended |
`host.arch` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

62
specification/resource/semantic_conventions/k8s.md
View File

@ -22,9 +22,9 @@ Kubernetes object, but "name" is usually more user friendly so can be also set.
**Description:** A Kubernetes Cluster.
<!-- semconv k8s.cluster -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `k8s.cluster.name` | string | The name of the cluster. | `opentelemetry-cluster` | No |
| `k8s.cluster.name` | string | The name of the cluster. | `opentelemetry-cluster` | Recommended |
<!-- endsemconv -->
## Node
@ -34,10 +34,10 @@ Kubernetes object, but "name" is usually more user friendly so can be also set.
**Description:** A Kubernetes Node.
<!-- semconv k8s.node -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `k8s.node.name` | string | The name of the Node. | `node-1` | No |
| `k8s.node.uid` | string | The UID of the Node. | `1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2` | No |
| `k8s.node.name` | string | The name of the Node. | `node-1` | Recommended |
| `k8s.node.uid` | string | The UID of the Node. | `1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2` | Recommended |
<!-- endsemconv -->
## Namespace
@ -50,9 +50,9 @@ a namespace, but not across namespaces.
**Description:** A Kubernetes Namespace.
<!-- semconv k8s.namespace -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `k8s.namespace.name` | string | The name of the namespace that the pod is running in. | `default` | No |
| `k8s.namespace.name` | string | The name of the namespace that the pod is running in. | `default` | Recommended |
<!-- endsemconv -->
## Pod
@ -65,10 +65,10 @@ containers on your cluster.
**Description:** A Kubernetes Pod object.
<!-- semconv k8s.pod -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `k8s.pod.uid` | string | The UID of the Pod. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | No |
| `k8s.pod.name` | string | The name of the Pod. | `opentelemetry-pod-autoconf` | No |
| `k8s.pod.uid` | string | The UID of the Pod. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended |
| `k8s.pod.name` | string | The name of the Pod. | `opentelemetry-pod-autoconf` | Recommended |
<!-- endsemconv -->
## Container
@ -85,10 +85,10 @@ to a running container.
**Description:** A container in a [PodTemplate](https://kubernetes.io/docs/concepts/workloads/pods/#pod-templates).
<!-- semconv k8s.container -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `k8s.container.name` | string | The name of the Container from Pod specification, must be unique within a Pod. Container runtime usually uses different globally unique name (`container.name`). | `redis` | No |
| `k8s.container.restart_count` | int | Number of times the container was restarted. This attribute can be used to identify a particular container (running or stopped) within a container spec. | `0`; `2` | No |
| `k8s.container.name` | string | The name of the Container from Pod specification, must be unique within a Pod. Container runtime usually uses different globally unique name (`container.name`). | `redis` | Recommended |
| `k8s.container.restart_count` | int | Number of times the container was restarted. This attribute can be used to identify a particular container (running or stopped) within a container spec. | `0`; `2` | Recommended |
<!-- endsemconv -->
## ReplicaSet
@ -101,10 +101,10 @@ any given time.
**Description:** A Kubernetes ReplicaSet object.
<!-- semconv k8s.replicaset -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `k8s.replicaset.uid` | string | The UID of the ReplicaSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | No |
| `k8s.replicaset.name` | string | The name of the ReplicaSet. | `opentelemetry` | No |
| `k8s.replicaset.uid` | string | The UID of the ReplicaSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended |
| `k8s.replicaset.name` | string | The name of the ReplicaSet. | `opentelemetry` | Recommended |
<!-- endsemconv -->
## Deployment
@ -118,10 +118,10 @@ distributed among the nodes of a cluster.
**Description:** A Kubernetes Deployment object.
<!-- semconv k8s.deployment -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `k8s.deployment.uid` | string | The UID of the Deployment. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | No |
| `k8s.deployment.name` | string | The name of the Deployment. | `opentelemetry` | No |
| `k8s.deployment.uid` | string | The UID of the Deployment. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended |
| `k8s.deployment.name` | string | The name of the Deployment. | `opentelemetry` | Recommended |
<!-- endsemconv -->
## StatefulSet
@ -134,10 +134,10 @@ about the ordering and uniqueness of these Pods.
**Description:** A Kubernetes StatefulSet object.
<!-- semconv k8s.statefulset -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `k8s.statefulset.uid` | string | The UID of the StatefulSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | No |
| `k8s.statefulset.name` | string | The name of the StatefulSet. | `opentelemetry` | No |
| `k8s.statefulset.uid` | string | The UID of the StatefulSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended |
| `k8s.statefulset.name` | string | The name of the StatefulSet. | `opentelemetry` | Recommended |
<!-- endsemconv -->
## DaemonSet
@ -149,10 +149,10 @@ A DaemonSet ensures that all (or some) Nodes run a copy of a Pod.
**Description:** A Kubernetes DaemonSet object.
<!-- semconv k8s.daemonset -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `k8s.daemonset.uid` | string | The UID of the DaemonSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | No |
| `k8s.daemonset.name` | string | The name of the DaemonSet. | `opentelemetry` | No |
| `k8s.daemonset.uid` | string | The UID of the DaemonSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended |
| `k8s.daemonset.name` | string | The name of the DaemonSet. | `opentelemetry` | Recommended |
<!-- endsemconv -->
## Job
@ -165,10 +165,10 @@ successfully terminate.
**Description:** A Kubernetes Job object.
<!-- semconv k8s.job -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `k8s.job.uid` | string | The UID of the Job. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | No |
| `k8s.job.name` | string | The name of the Job. | `opentelemetry` | No |
| `k8s.job.uid` | string | The UID of the Job. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended |
| `k8s.job.name` | string | The name of the Job. | `opentelemetry` | Recommended |
<!-- endsemconv -->
## CronJob
@ -180,8 +180,8 @@ A CronJob creates Jobs on a repeating schedule.
**Description:** A Kubernetes CronJob object.
<!-- semconv k8s.cronjob -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `k8s.cronjob.uid` | string | The UID of the CronJob. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | No |
| `k8s.cronjob.name` | string | The name of the CronJob. | `opentelemetry` | No |
| `k8s.cronjob.uid` | string | The UID of the CronJob. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended |
| `k8s.cronjob.name` | string | The name of the CronJob. | `opentelemetry` | Recommended |
<!-- endsemconv -->

10
specification/resource/semantic_conventions/os.md
View File

@ -9,12 +9,12 @@
In case of virtualized environments, this is the operating system as it is observed by the process, i.e., the virtualized guest rather than the underlying host.
<!-- semconv os -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `os.type` | string | The operating system type. | `windows` | Yes |
| `os.description` | string | Human readable (not intended to be parsed) OS version information, like e.g. reported by `ver` or `lsb_release -a` commands. | `Microsoft Windows [Version 10.0.18363.778]`; `Ubuntu 18.04.1 LTS` | No |
| `os.name` | string | Human readable operating system name. | `iOS`; `Android`; `Ubuntu` | No |
| `os.version` | string | The version string of the operating system as defined in [Version Attributes](../../resource/semantic_conventions/README.md#version-attributes). | `14.2.1`; `18.04.1` | No |
| `os.type` | string | The operating system type. | `windows` | Required |
| `os.description` | string | Human readable (not intended to be parsed) OS version information, like e.g. reported by `ver` or `lsb_release -a` commands. | `Microsoft Windows [Version 10.0.18363.778]`; `Ubuntu 18.04.1 LTS` | Recommended |
| `os.name` | string | Human readable operating system name. | `iOS`; `Android`; `Ubuntu` | Recommended |
| `os.version` | string | The version string of the operating system as defined in [Version Attributes](../../resource/semantic_conventions/README.md#version-attributes). | `14.2.1`; `18.04.1` | Recommended |
`os.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

34
specification/resource/semantic_conventions/process.md
View File

@ -25,15 +25,23 @@
**Description:** An operating system process.
<!-- semconv process -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `process.pid` | int | Process identifier (PID). | `1234` | No |
| `process.executable.name` | string | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | See below |
| `process.executable.path` | string | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | See below |
| `process.command` | string | The command used to launch the process (i.e. the command name). On Linux based systems, can be set to the zeroth string in `proc/[pid]/cmdline`. On Windows, can be set to the first parameter extracted from `GetCommandLineW`. | `cmd/otelcol` | See below |
| `process.command_line` | string | The full command used to launch the process as a single string representing the full command. On Windows, can be set to the result of `GetCommandLineW`. Do not set this if you have to assemble it just for monitoring; use `process.command_args` instead. | `C:\cmd\otecol --config="my directory\config.yaml"` | See below |
| `process.command_args` | string[] | All the command arguments (including the command/executable itself) as received by the process. On Linux-based systems (and some other Unixoid systems supporting procfs), can be set according to the list of null-delimited strings extracted from `proc/[pid]/cmdline`. For libc-based executables, this would be the full argv vector passed to `main`. | `[cmd/otecol, --config=config.yaml]` | See below |
| `process.owner` | string | The username of the user that owns the process. | `root` | No |
| `process.pid` | int | Process identifier (PID). | `1234` | Recommended |
| `process.executable.name` | string | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | Conditionally Required: See alternative attributes below. |
| `process.executable.path` | string | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | Conditionally Required: See alternative attributes below. |
| `process.command` | string | The command used to launch the process (i.e. the command name). On Linux based systems, can be set to the zeroth string in `proc/[pid]/cmdline`. On Windows, can be set to the first parameter extracted from `GetCommandLineW`. | `cmd/otelcol` | Conditionally Required: See alternative attributes below. |
| `process.command_line` | string | The full command used to launch the process as a single string representing the full command. On Windows, can be set to the result of `GetCommandLineW`. Do not set this if you have to assemble it just for monitoring; use `process.command_args` instead. | `C:\cmd\otecol --config="my directory\config.yaml"` | Conditionally Required: See alternative attributes below. |
| `process.command_args` | string[] | All the command arguments (including the command/executable itself) as received by the process. On Linux-based systems (and some other Unixoid systems supporting procfs), can be set according to the list of null-delimited strings extracted from `proc/[pid]/cmdline`. For libc-based executables, this would be the full argv vector passed to `main`. | `[cmd/otecol, --config=config.yaml]` | Conditionally Required: See alternative attributes below. |
| `process.owner` | string | The username of the user that owns the process. | `root` | Recommended |
**Additional attribute requirements:** At least one of the following sets of attributes is required:
* `process.executable.name`
* `process.executable.path`
* `process.command`
* `process.command_line`
* `process.command_args`
<!-- endsemconv -->
Between `process.command_args` and `process.command_line`, usually `process.command_args` should be preferred.
@ -44,8 +52,6 @@ For backwards compatibility with older versions of this semantic convention,
it is possible but deprecated to use an array as type for `process.command_line`.
In that case it MUST be interpreted as if it was `process.command_args`.
At least one of `process.executable.name`, `process.executable.path`, `process.command`, `process.command_line` or `process.command_args` is required to allow back ends to identify the executable.
## Process runtimes
**type:** `process.runtime`
@ -53,11 +59,11 @@ At least one of `process.executable.name`, `process.executable.path`, `process.c
**Description:** The single (language) runtime instance which is monitored.
<!-- semconv process.runtime -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `process.runtime.name` | string | The name of the runtime of this process. For compiled native binaries, this SHOULD be the name of the compiler. | `OpenJDK Runtime Environment` | No |
| `process.runtime.version` | string | The version of the runtime of this process, as returned by the runtime without modification. | `14.0.2` | No |
| `process.runtime.description` | string | An additional description about the runtime of the process, for example a specific vendor customization of the runtime environment. | `Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0` | No |
| `process.runtime.name` | string | The name of the runtime of this process. For compiled native binaries, this SHOULD be the name of the compiler. | `OpenJDK Runtime Environment` | Recommended |
| `process.runtime.version` | string | The version of the runtime of this process, as returned by the runtime without modification. | `14.0.2` | Recommended |
| `process.runtime.description` | string | An additional description about the runtime of the process, for example a specific vendor customization of the runtime environment. | `Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0` | Recommended |
<!-- endsemconv -->
How to set these attributes for particular runtime kinds is described in the following subsections.

8
specification/resource/semantic_conventions/webengine.md
View File

@ -5,11 +5,11 @@
**Description:** Resource describing the packaged software running the application code. Web engines are typically executed using process.runtime.
<!-- semconv webengine_resource -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `webengine.name` | string | The name of the web engine. | `WildFly` | Yes |
| `webengine.version` | string | The version of the web engine. | `21.0.0` | No |
| `webengine.description` | string | Additional description of the web engine (e.g. detailed version and edition information). | `WildFly Full 21.0.0.Final (WildFly Core 13.0.1.Final) - 2.2.2.Final` | No |
| `webengine.name` | string | The name of the web engine. | `WildFly` | Required |
| `webengine.version` | string | The version of the web engine. | `21.0.0` | Recommended |
| `webengine.description` | string | Additional description of the web engine (e.g. detailed version and edition information). | `WildFly Full 21.0.0.Final (WildFly Core 13.0.1.Final) - 2.2.2.Final` | Recommended |
<!-- endsemconv -->
Information describing the web engine SHOULD be captured using the values acquired from the API provided by the web engine, preferably during runtime, to avoid maintenance burden on engine version upgrades. As an example - Java engines are often but not always packaged as application servers. For Java application servers supporting Servlet API the required information MAY be captured by invoking `ServletContext.getServerInfo()` during runtime and parsing the result.

12
specification/trace/semantic_conventions/cloudevents.md
View File

@ -194,11 +194,11 @@ in the [table below](#attributes).
The following attributes are applicable to creation and processing Spans.
<!-- semconv cloudevents -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event. | `123e4567-e89b-12d3-a456-426614174000`; `0001` | Yes |
| `cloudevents.event_source` | string | The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | Yes |
| `cloudevents.event_spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses. | `1.0` | Yes |
| `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | Yes |
| `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | No |
| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event. | `123e4567-e89b-12d3-a456-426614174000`; `0001` | Required |
| `cloudevents.event_source` | string | The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | Required |
| `cloudevents.event_spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses. | `1.0` | Required |
| `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | Required |
| `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | Recommended |
<!-- endsemconv -->

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

@ -21,9 +21,9 @@ between a child Span and a parent Span, as defined by
[OpenTracing](https://github.com/opentracing/specification/blob/master/specification.md).
<!-- semconv opentracing -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `opentracing.ref_type` | string | Parent-child Reference type [1] | `child_of` | No |
| `opentracing.ref_type` | string | Parent-child Reference type [1] | `child_of` | Recommended |
**[1]:** The causal relationship between a child Span and a parent Span.

64
specification/trace/semantic_conventions/database.md
View File

@ -37,21 +37,21 @@ These attributes will usually be the same for all operations performed over the
Some database systems may allow a connection to switch to a different `db.user`, for example, and other database systems may not even have the concept of a connection at all.
<!-- semconv db(tag=connection-level) -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Yes |
| `db.connection_string` | string | The connection string used to connect to the database. It is recommended to remove embedded credentials. | `Server=(localdb)\v11.0;Integrated Security=true;` | No |
| `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | No |
| [`net.peer.ip`](span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | See below. |
| [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. [1] | `example.com` | See below. |
| [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | Conditional [2] |
| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditional [3] |
| `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required |
| `db.connection_string` | string | The connection string used to connect to the database. It is recommended to remove embedded credentials. | `Server=(localdb)\v11.0;Integrated Security=true;` | Recommended |
| `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended |
| [`net.peer.ip`](span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | Conditionally Required: See alternative attributes below. |
| [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. [1] | `example.com` | Conditionally Required: See alternative attributes below. |
| [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | Conditionally Required: [2] |
| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: [3] |
**[1]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup.
**[2]:** Required if using a port other than the default port for this DBMS.
**[2]:** If using a port other than the default port for this DBMS.
**[3]:** Recommended in general, required for in-process databases (`"inproc"`).
**[3]:** If database type is in-process (`"inproc"`), recommended for other database types.
**Additional attribute requirements:** At least one of the following sets of attributes is required:
@ -132,10 +132,10 @@ When additional attributes are added that only apply to a specific DBMS, its ide
### Connection-level attributes for specific technologies
<!-- semconv db.mssql(tag=connection-level-tech-specific,remove_constraints) -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.jdbc.driver_classname` | string | The fully-qualified class name of the [Java Database Connectivity (JDBC)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) driver used to connect. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | No |
| `db.mssql.instance_name` | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. [1] | `MSSQLSERVER` | No |
| `db.jdbc.driver_classname` | string | The fully-qualified class name of the [Java Database Connectivity (JDBC)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) driver used to connect. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | Recommended |
| `db.mssql.instance_name` | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. [1] | `MSSQLSERVER` | Recommended |
**[1]:** If setting a `db.mssql.instance_name`, `net.peer.port` is no longer required (but still recommended if non-standard).
<!-- endsemconv -->
@ -146,17 +146,17 @@ These attributes may be different for each operation performed, even if the same
Usually only one `db.name` will be used per connection though.
<!-- semconv db(tag=call-level,remove_constraints) -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.name` | string | This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | Required, if applicable. |
| `db.statement` | string | The database statement being executed. [2] | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | Conditional [3] |
| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. [4] | `findAndModify`; `HMSET`; `SELECT` | Required, if `db.statement` is not applicable. |
| `db.name` | string | This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | Conditionally Required: If applicable. |
| `db.statement` | string | The database statement being executed. [2] | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | Conditionally Required: [3] |
| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. [4] | `findAndModify`; `HMSET`; `SELECT` | Conditionally Required: If `db.statement` is not applicable. |
**[1]:** In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name).
**[2]:** The value may be sanitized to exclude sensitive information.
**[3]:** Required if applicable and not explicitly disabled via instrumentation configuration.
**[3]:** If applicable and not explicitly disabled via instrumentation configuration.
**[4]:** When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted.
<!-- endsemconv -->
@ -178,15 +178,13 @@ In **HBase**, `db.name` SHOULD be set to the HBase namespace.
### Call-level attributes for specific technologies
<!-- semconv db.tech(tag=call-level-tech-specific) -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.redis.database_index` | int | The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. To be used instead of the generic `db.name` attribute. | `0`; `1`; `15` | Conditional [1] |
| `db.mongodb.collection` | string | The collection being accessed within the database stated in `db.name`. | `customers`; `products` | Yes |
| `db.sql.table` | string | The name of the primary table that the operation is acting upon, including the database name (if applicable). [2] | `public.users`; `customers` | Recommended if available. |
| `db.redis.database_index` | int | The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. To be used instead of the generic `db.name` attribute. | `0`; `1`; `15` | Conditionally Required: If other than the default database (`0`). |
| `db.mongodb.collection` | string | The collection being accessed within the database stated in `db.name`. | `customers`; `products` | Required |
| `db.sql.table` | string | The name of the primary table that the operation is acting upon, including the database name (if applicable). [1] | `public.users`; `customers` | Recommended |
**[1]:** Required, if other than the default database (`0`).
**[2]:** It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set.
**[1]:** It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set.
<!-- endsemconv -->
#### Cassandra
@ -194,15 +192,15 @@ In **HBase**, `db.name` SHOULD be set to the HBase namespace.
Separated for clarity.
<!-- semconv db.tech(tag=call-level-tech-specific-cassandra) -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `db.cassandra.page_size` | int | The fetch size used for paging, i.e. how many rows will be returned at once. | `5000` | No |
| `db.cassandra.consistency_level` | string | The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). | `all` | No |
| `db.cassandra.table` | string | The name of the primary table that the operation is acting upon, including the keyspace name (if applicable). [1] | `mytable` | Recommended if available. |
| `db.cassandra.idempotence` | boolean | Whether or not the query is idempotent. | | No |
| `db.cassandra.speculative_execution_count` | int | The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. | `0`; `2` | No |
| `db.cassandra.coordinator.id` | string | The ID of the coordinating node for a query. | `be13faa2-8574-4d71-926d-27f16cf8a7af` | No |
| `db.cassandra.coordinator.dc` | string | The data center of the coordinating node for a query. | `us-west-2` | No |
| `db.cassandra.page_size` | int | The fetch size used for paging, i.e. how many rows will be returned at once. | `5000` | Recommended |
| `db.cassandra.consistency_level` | string | The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). | `all` | Recommended |
| `db.cassandra.table` | string | The name of the primary table that the operation is acting upon, including the keyspace name (if applicable). [1] | `mytable` | Recommended |
| `db.cassandra.idempotence` | boolean | Whether or not the query is idempotent. | | Recommended |
| `db.cassandra.speculative_execution_count` | int | The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. | `0`; `2` | Recommended |
| `db.cassandra.coordinator.id` | string | The ID of the coordinating node for a query. | `be13faa2-8574-4d71-926d-27f16cf8a7af` | Recommended |
| `db.cassandra.coordinator.dc` | string | The data center of the coordinating node for a query. | `us-west-2` | Recommended |
**[1]:** This mirrors the db.sql.table attribute but references cassandra rather than sql. It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set.
<!-- endsemconv -->

6
specification/trace/semantic_conventions/exceptions.md
View File

@ -42,12 +42,12 @@ their types.
<!-- semconv exception -->
The event name MUST be `exception`.
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | See below |
| `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below |
| `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | No |
| `exception.escaped` | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] | | No |
| `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | Recommended |
| `exception.escaped` | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] | | Recommended |
**[1]:** An exception is considered to have escaped (or left) the scope of a span,
if that span is ended while the exception is still logically "in flight".

36
specification/trace/semantic_conventions/faas.md
View File

@ -35,10 +35,10 @@ Span `name` should be set to the function name being executed. Depending on the
If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../../resource/semantic_conventions/faas.md#function-as-a-service).
<!-- semconv faas_span -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `faas.trigger` | string | Type of the trigger which caused this function execution. [1] | `datasource` | No |
| `faas.execution` | string | The execution ID of the current function execution. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | No |
| `faas.trigger` | string | Type of the trigger which caused this function execution. [1] | `datasource` | Recommended |
| `faas.execution` | string | The execution ID of the current function execution. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | Recommended |
**[1]:** For the server/consumer span on the incoming side,
`faas.trigger` MUST be set.
@ -97,10 +97,10 @@ For incoming FaaS spans, the span kind MUST be `Server`.
### Incoming FaaS Span attributes
<!-- semconv faas_span.in -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `faas.coldstart` | boolean | A boolean that is true if the serverless function is executed for the first time (aka cold-start). | | No |
| `faas.trigger` | string | Type of the trigger which caused this function execution. [1] | `datasource` | Yes |
| `faas.coldstart` | boolean | A boolean that is true if the serverless function is executed for the first time (aka cold-start). | | Recommended |
| `faas.trigger` | string | Type of the trigger which caused this function execution. [1] | `datasource` | Required |
**[1]:** For the server/consumer span on the incoming side,
`faas.trigger` MUST be set.
@ -136,11 +136,11 @@ the corresponding [FaaS resource attributes][] and [Cloud resource attributes][]
which the invoked FaaS instance reports about itself, if it's instrumented.
<!-- semconv faas_span.out -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `faas.invoked_name` | string | The name of the invoked function. [1] | `my-function` | Yes |
| `faas.invoked_provider` | string | The cloud provider of the invoked function. [2] | `alibaba_cloud` | Yes |
| `faas.invoked_region` | string | The cloud region of the invoked function. [3] | `eu-central-1` | Conditional [4] |
| `faas.invoked_name` | string | The name of the invoked function. [1] | `my-function` | Required |
| `faas.invoked_provider` | string | The cloud provider of the invoked function. [2] | `alibaba_cloud` | Required |
| `faas.invoked_region` | string | The cloud region of the invoked function. [3] | `eu-central-1` | Conditionally Required: [4] |
**[1]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function.
@ -174,12 +174,12 @@ A datasource function is triggered as a response to some data source operation s
For `faas` spans with trigger `datasource`, it is recommended to set the following attributes.
<!-- semconv faas_span.datasource -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `faas.document.collection` | string | The name of the source on which the triggering operation was performed. For example, in Cloud Storage or S3 corresponds to the bucket name, and in Cosmos DB to the database name. | `myBucketName`; `myDbName` | Yes |
| `faas.document.operation` | string | Describes the type of the operation that was performed on the data. | `insert` | Yes |
| `faas.document.time` | string | A string containing the time when the data was accessed in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | Yes |
| `faas.document.name` | string | The document name/table subjected to the operation. For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the table name. | `myFile.txt`; `myTableName` | No |
| `faas.document.collection` | string | The name of the source on which the triggering operation was performed. For example, in Cloud Storage or S3 corresponds to the bucket name, and in Cosmos DB to the database name. | `myBucketName`; `myDbName` | Required |
| `faas.document.operation` | string | Describes the type of the operation that was performed on the data. | `insert` | Required |
| `faas.document.time` | string | A string containing the time when the data was accessed in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | Required |
| `faas.document.name` | string | The document name/table subjected to the operation. For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the table name. | `myFile.txt`; `myTableName` | Recommended |
`faas.document.operation` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
@ -206,10 +206,10 @@ This way, it is possible to correlate each individual message with its execution
A function is scheduled to be executed regularly. The following additional attributes are recommended.
<!-- semconv faas_span.timer -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `faas.time` | string | A string containing the function invocation time in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | Yes |
| `faas.cron` | string | A string containing the schedule period as [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). | `0/5 * * * ? *` | No |
| `faas.time` | string | A string containing the function invocation time in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | Required |
| `faas.cron` | string | A string containing the schedule period as [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). | `0/5 * * * ? *` | Recommended |
<!-- endsemconv -->
### Other

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

@ -59,23 +59,23 @@ Don't set the span status description if the reason can be inferred from `http.s
## Common Attributes
<!-- semconv http -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Yes |
| `http.url` | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | No |
| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | No |
| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). An empty Host header should also be reported, see note. [2] | `www.example.org` | No |
| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | No |
| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | If and only if one was received/sent. |
| `http.flavor` | string | Kind of HTTP protocol used. [3] | `1.0` | No |
| `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | No |
| `http.request_content_length` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests using transport encoding, this should be the compressed size. | `3495` | No |
| `http.request_content_length_uncompressed` | int | The size of the uncompressed request payload body after transport decoding. Not set if transport encoding not used. | `5493` | No |
| `http.response_content_length` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests using transport encoding, this should be the compressed size. | `3495` | No |
| `http.response_content_length_uncompressed` | int | The size of the uncompressed response payload body after transport decoding. Not set if transport encoding not used. | `5493` | No |
| `http.retry_count` | int | The ordinal number of request re-sending attempt. | `3` | If and only if a request was retried. |
| [`net.peer.ip`](span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | No |
| [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | No |
| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `http.url` | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | Recommended |
| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | Recommended |
| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). An empty Host header should also be reported, see note. [2] | `www.example.org` | Recommended |
| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Recommended |
| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
| `http.flavor` | string | Kind of HTTP protocol used. [3] | `1.0` | Recommended |
| `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended |
| `http.request_content_length` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended |
| `http.request_content_length_uncompressed` | int | The size of the uncompressed request payload body after transport decoding. Not set if transport encoding not used. | `5493` | Recommended |
| `http.response_content_length` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended |
| `http.response_content_length_uncompressed` | int | The size of the uncompressed response payload body after transport decoding. Not set if transport encoding not used. | `5493` | Recommended |
| `http.retry_count` | int | The ordinal number of request re-sending attempt. | `3` | Recommended: If and only if a request was retried. |
| [`net.peer.ip`](span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | Recommended |
| [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | Recommended |
**[1]:** `http.url` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case the attribute's value should be `https://www.example.com/`.
@ -109,10 +109,10 @@ It is recommended to also use the general [network attributes][], especially `ne
### HTTP request and response headers
| Attribute | Type | Description | Examples | Required |
| 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"]` | No |
| `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"]` | No |
| `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 |
**[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.
@ -145,7 +145,7 @@ If set, `http.url` must be the originally requested URL,
before any HTTP-redirects that may happen when executing the request.
<!-- semconv http.client -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. [1] | `example.com` | See below |
@ -229,11 +229,11 @@ If the route does not include the application root, it SHOULD be prepended to th
If the route cannot be determined, the `name` attribute MUST be set as defined in the general semantic conventions for HTTP.
<!-- semconv http.server -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `http.server_name` | string | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). [1] | `example.com` | See below |
| `http.route` | string | The matched route (path template). | `/users/:userID?` | No |
| `http.client_ip` | string | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [2] | `83.164.160.102` | No |
| `http.route` | string | The matched route (path template). | `/users/:userID?` | Recommended |
| `http.client_ip` | string | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [2] | `83.164.160.102` | Recommended |
**[1]:** `http.url` is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. open-telemetry/opentelemetry-python/pull/148). It is thus preferred to supply the raw data that is available.

4
specification/trace/semantic_conventions/instrumentation/aws-lambda.md
View File

@ -50,9 +50,9 @@ Also consider setting other attributes of the [`faas` resource][faasres] and [tr
and the [cloud resource conventions][cloud]. The following AWS Lambda-specific attribute MAY also be set:
<!-- semconv aws.lambda -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.lambda.invoked_arn` | string | The full invoked ARN as provided on the `Context` passed to the function (`Lambda-Runtime-Invoked-Function-Arn` header on the `/runtime/invocation/next` applicable). [1] | `arn:aws:lambda:us-east-1:123456:function:myfunction:myalias` | No |
| `aws.lambda.invoked_arn` | string | The full invoked ARN as provided on the `Context` passed to the function (`Lambda-Runtime-Invoked-Function-Arn` header on the `/runtime/invocation/next` applicable). [1] | `arn:aws:lambda:us-east-1:123456:function:myfunction:myalias` | Recommended |
**[1]:** This may be different from `faas.id` if an alias is involved.
<!-- endsemconv -->

152
specification/trace/semantic_conventions/instrumentation/aws-sdk.md
View File

@ -16,11 +16,11 @@ The span name MUST be of the format `Service.Operation` as per the AWS HTTP API,
with the naming guidelines for RPC client spans.
<!-- semconv aws -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| [`rpc.method`](../rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | No |
| [`rpc.service`](../rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | No |
| [`rpc.system`](../rpc.md) | string | The value `aws-api`. | `aws-api` | Yes |
| [`rpc.method`](../rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | Recommended |
| [`rpc.service`](../rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | Recommended |
| [`rpc.system`](../rpc.md) | string | The value `aws-api`. | `aws-api` | Required |
**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
@ -34,155 +34,155 @@ with the naming guidelines for RPC client spans.
These attributes are filled in for all DynamoDB request types.
<!-- semconv dynamodb.all -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| [`db.system`](../database.md) | string | The value `dynamodb`. | `dynamodb` | Yes |
| [`db.system`](../database.md) | string | The value `dynamodb`. | `dynamodb` | Required |
<!-- endsemconv -->
### DynamoDB.BatchGetItem
<!-- semconv dynamodb.batchgetitem -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | No |
| `aws.dynamodb.table_names` | string[] | The keys in the `RequestItems` object field. | `[Users, Cats]` | No |
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended |
| `aws.dynamodb.table_names` | string[] | The keys in the `RequestItems` object field. | `[Users, Cats]` | Recommended |
<!-- endsemconv -->
### DynamoDB.BatchWriteItem
<!-- semconv dynamodb.batchwriteitem -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | No |
| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | No |
| `aws.dynamodb.table_names` | string[] | The keys in the `RequestItems` object field. | `[Users, Cats]` | No |
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended |
| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | Recommended |
| `aws.dynamodb.table_names` | string[] | The keys in the `RequestItems` object field. | `[Users, Cats]` | Recommended |
<!-- endsemconv -->
### DynamoDB.CreateTable
<!-- semconv dynamodb.createtable -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.dynamodb.global_secondary_indexes` | string[] | The JSON-serialized value of each item of the `GlobalSecondaryIndexes` request field | `[{ "IndexName": "string", "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" }, "ProvisionedThroughput": { "ReadCapacityUnits": number, "WriteCapacityUnits": number } }]` | No |
| `aws.dynamodb.local_secondary_indexes` | string[] | The JSON-serialized value of each item of the `LocalSecondaryIndexes` request field. | `[{ "IndexArn": "string", "IndexName": "string", "IndexSizeBytes": number, "ItemCount": number, "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" } }]` | No |
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | No |
| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | No |
| `aws.dynamodb.provisioned_read_capacity` | double | The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter. | `1.0`; `2.0` | No |
| `aws.dynamodb.provisioned_write_capacity` | double | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. | `1.0`; `2.0` | No |
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | No |
| `aws.dynamodb.global_secondary_indexes` | string[] | The JSON-serialized value of each item of the `GlobalSecondaryIndexes` request field | `[{ "IndexName": "string", "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" }, "ProvisionedThroughput": { "ReadCapacityUnits": number, "WriteCapacityUnits": number } }]` | Recommended |
| `aws.dynamodb.local_secondary_indexes` | string[] | The JSON-serialized value of each item of the `LocalSecondaryIndexes` request field. | `[{ "IndexArn": "string", "IndexName": "string", "IndexSizeBytes": number, "ItemCount": number, "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" } }]` | Recommended |
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended |
| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | Recommended |
| `aws.dynamodb.provisioned_read_capacity` | double | The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter. | `1.0`; `2.0` | Recommended |
| `aws.dynamodb.provisioned_write_capacity` | double | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. | `1.0`; `2.0` | Recommended |
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
<!-- endsemconv -->
### DynamoDB.DeleteItem
<!-- semconv dynamodb.deleteitem -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | No |
| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | No |
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | No |
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended |
| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | Recommended |
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
<!-- endsemconv -->
### DynamoDB.DeleteTable
<!-- semconv dynamodb.deletetable -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | No |
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
<!-- endsemconv -->
### DynamoDB.DescribeTable
<!-- semconv dynamodb.describetable -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | No |
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
<!-- endsemconv -->
### DynamoDB.GetItem
<!-- semconv dynamodb.getitem -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.dynamodb.consistent_read` | boolean | The value of the `ConsistentRead` request parameter. | | No |
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | No |
| `aws.dynamodb.projection` | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | No |
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | No |
| `aws.dynamodb.consistent_read` | boolean | The value of the `ConsistentRead` request parameter. | | Recommended |
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended |
| `aws.dynamodb.projection` | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | Recommended |
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
<!-- endsemconv -->
### DynamoDB.ListTables
<!-- semconv dynamodb.listtables -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.dynamodb.exclusive_start_table` | string | The value of the `ExclusiveStartTableName` request parameter. | `Users`; `CatsTable` | No |
| `aws.dynamodb.table_count` | int | The the number of items in the `TableNames` response parameter. | `20` | No |
| `aws.dynamodb.limit` | int | The value of the `Limit` request parameter. | `10` | No |
| `aws.dynamodb.exclusive_start_table` | string | The value of the `ExclusiveStartTableName` request parameter. | `Users`; `CatsTable` | Recommended |
| `aws.dynamodb.table_count` | int | The the number of items in the `TableNames` response parameter. | `20` | Recommended |
| `aws.dynamodb.limit` | int | The value of the `Limit` request parameter. | `10` | Recommended |
<!-- endsemconv -->
### DynamoDB.PutItem
<!-- semconv dynamodb.putitem -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | No |
| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | No |
| `aws.dynamodb.table_names` | string[] | The keys in the `RequestItems` object field. | `[Users, Cats]` | No |
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended |
| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | Recommended |
| `aws.dynamodb.table_names` | string[] | The keys in the `RequestItems` object field. | `[Users, Cats]` | Recommended |
<!-- endsemconv -->
### DynamoDB.Query
<!-- semconv dynamodb.query -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.dynamodb.scan_forward` | boolean | The value of the `ScanIndexForward` request parameter. | | No |
| `aws.dynamodb.attributes_to_get` | string[] | The value of the `AttributesToGet` request parameter. | `[lives, id]` | No |
| `aws.dynamodb.consistent_read` | boolean | The value of the `ConsistentRead` request parameter. | | No |
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | No |
| `aws.dynamodb.index_name` | string | The value of the `IndexName` request parameter. | `name_to_group` | No |
| `aws.dynamodb.limit` | int | The value of the `Limit` request parameter. | `10` | No |
| `aws.dynamodb.projection` | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | No |
| `aws.dynamodb.select` | string | The value of the `Select` request parameter. | `ALL_ATTRIBUTES`; `COUNT` | No |
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | No |
| `aws.dynamodb.scan_forward` | boolean | The value of the `ScanIndexForward` request parameter. | | Recommended |
| `aws.dynamodb.attributes_to_get` | string[] | The value of the `AttributesToGet` request parameter. | `[lives, id]` | Recommended |
| `aws.dynamodb.consistent_read` | boolean | The value of the `ConsistentRead` request parameter. | | Recommended |
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended |
| `aws.dynamodb.index_name` | string | The value of the `IndexName` request parameter. | `name_to_group` | Recommended |
| `aws.dynamodb.limit` | int | The value of the `Limit` request parameter. | `10` | Recommended |
| `aws.dynamodb.projection` | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | Recommended |
| `aws.dynamodb.select` | string | The value of the `Select` request parameter. | `ALL_ATTRIBUTES`; `COUNT` | Recommended |
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
<!-- endsemconv -->
### DynamoDB.Scan
<!-- semconv dynamodb.scan -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.dynamodb.segment` | int | The value of the `Segment` request parameter. | `10` | No |
| `aws.dynamodb.total_segments` | int | The value of the `TotalSegments` request parameter. | `100` | No |
| `aws.dynamodb.count` | int | The value of the `Count` response parameter. | `10` | No |
| `aws.dynamodb.scanned_count` | int | The value of the `ScannedCount` response parameter. | `50` | No |
| `aws.dynamodb.attributes_to_get` | string[] | The value of the `AttributesToGet` request parameter. | `[lives, id]` | No |
| `aws.dynamodb.consistent_read` | boolean | The value of the `ConsistentRead` request parameter. | | No |
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | No |
| `aws.dynamodb.index_name` | string | The value of the `IndexName` request parameter. | `name_to_group` | No |
| `aws.dynamodb.limit` | int | The value of the `Limit` request parameter. | `10` | No |
| `aws.dynamodb.projection` | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | No |
| `aws.dynamodb.select` | string | The value of the `Select` request parameter. | `ALL_ATTRIBUTES`; `COUNT` | No |
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | No |
| `aws.dynamodb.segment` | int | The value of the `Segment` request parameter. | `10` | Recommended |
| `aws.dynamodb.total_segments` | int | The value of the `TotalSegments` request parameter. | `100` | Recommended |
| `aws.dynamodb.count` | int | The value of the `Count` response parameter. | `10` | Recommended |
| `aws.dynamodb.scanned_count` | int | The value of the `ScannedCount` response parameter. | `50` | Recommended |
| `aws.dynamodb.attributes_to_get` | string[] | The value of the `AttributesToGet` request parameter. | `[lives, id]` | Recommended |
| `aws.dynamodb.consistent_read` | boolean | The value of the `ConsistentRead` request parameter. | | Recommended |
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended |
| `aws.dynamodb.index_name` | string | The value of the `IndexName` request parameter. | `name_to_group` | Recommended |
| `aws.dynamodb.limit` | int | The value of the `Limit` request parameter. | `10` | Recommended |
| `aws.dynamodb.projection` | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | Recommended |
| `aws.dynamodb.select` | string | The value of the `Select` request parameter. | `ALL_ATTRIBUTES`; `COUNT` | Recommended |
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
<!-- endsemconv -->
### DynamoDB.UpdateItem
<!-- semconv dynamodb.updateitem -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | No |
| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | No |
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | No |
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended |
| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | Recommended |
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
<!-- endsemconv -->
### DynamoDB.UpdateTable
<!-- semconv dynamodb.updatetable -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aws.dynamodb.attribute_definitions` | string[] | The JSON-serialized value of each item in the `AttributeDefinitions` request field. | `[{ "AttributeName": "string", "AttributeType": "string" }]` | No |
| `aws.dynamodb.global_secondary_index_updates` | string[] | The JSON-serialized value of each item in the the `GlobalSecondaryIndexUpdates` request field. | `[{ "Create": { "IndexName": "string", "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" }, "ProvisionedThroughput": { "ReadCapacityUnits": number, "WriteCapacityUnits": number } }]` | No |
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | No |
| `aws.dynamodb.provisioned_read_capacity` | double | The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter. | `1.0`; `2.0` | No |
| `aws.dynamodb.provisioned_write_capacity` | double | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. | `1.0`; `2.0` | No |
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | No |
| `aws.dynamodb.attribute_definitions` | string[] | The JSON-serialized value of each item in the `AttributeDefinitions` request field. | `[{ "AttributeName": "string", "AttributeType": "string" }]` | Recommended |
| `aws.dynamodb.global_secondary_index_updates` | string[] | The JSON-serialized value of each item in the the `GlobalSecondaryIndexUpdates` request field. | `[{ "Create": { "IndexName": "string", "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" }, "ProvisionedThroughput": { "ReadCapacityUnits": number, "WriteCapacityUnits": number } }]` | Recommended |
| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended |
| `aws.dynamodb.provisioned_read_capacity` | double | The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter. | `1.0`; `2.0` | Recommended |
| `aws.dynamodb.provisioned_write_capacity` | double | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. | `1.0`; `2.0` | Recommended |
| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
<!-- endsemconv -->

74
specification/trace/semantic_conventions/messaging.md
View File

@ -126,25 +126,27 @@ The following operations related to messages are defined for these semantic conv
## Messaging attributes
<!-- semconv messaging -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Yes |
| `messaging.destination` | string | The message destination name. This might be equal to the span name but is required nevertheless. | `MyQueue`; `MyTopic` | Yes |
| `messaging.destination_kind` | string | The kind of message destination | `queue` | Conditional [1] |
| `messaging.temp_destination` | boolean | A boolean that is true if the message destination is temporary. | | If missing, it is assumed to be false. |
| `messaging.protocol` | string | The name of the transport protocol. | `AMQP`; `MQTT` | No |
| `messaging.protocol_version` | string | The version of the transport protocol. | `0.9.1` | No |
| `messaging.url` | string | Connection string. | `tibjmsnaming://localhost:7222`; `https://queue.amazonaws.com/80398EXAMPLE/MyQueue` | No |
| `messaging.message_id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | No |
| `messaging.conversation_id` | string | The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | No |
| `messaging.message_payload_size_bytes` | int | The (uncompressed) size of the message payload in bytes. Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. | `2738` | No |
| `messaging.message_payload_compressed_size_bytes` | int | The compressed size of the message payload in bytes. | `2048` | No |
| [`net.peer.ip`](span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | If available. |
| [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. [2] | `example.com` | If available. |
| `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required |
| `messaging.destination` | string | The message destination name. This might be equal to the span name but is required nevertheless. | `MyQueue`; `MyTopic` | Required |
| `messaging.destination_kind` | string | The kind of message destination | `queue` | Conditionally Required: [1] |
| `messaging.temp_destination` | boolean | A boolean that is true if the message destination is temporary. | | Conditionally Required: [2] |
| `messaging.protocol` | string | The name of the transport protocol. | `AMQP`; `MQTT` | Recommended |
| `messaging.protocol_version` | string | The version of the transport protocol. | `0.9.1` | Recommended |
| `messaging.url` | string | Connection string. | `tibjmsnaming://localhost:7222`; `https://queue.amazonaws.com/80398EXAMPLE/MyQueue` | Recommended |
| `messaging.message_id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended |
| `messaging.conversation_id` | string | The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended |
| `messaging.message_payload_size_bytes` | int | The (uncompressed) size of the message payload in bytes. Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. | `2738` | Recommended |
| `messaging.message_payload_compressed_size_bytes` | int | The compressed size of the message payload in bytes. | `2048` | Recommended |
| [`net.peer.ip`](span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | Conditionally Required: If available. |
| [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. [3] | `example.com` | Conditionally Required: If available. |
**[1]:** Required only if the message destination is either a `queue` or `topic`.
**[1]:** If the message destination is either a `queue` or `topic`.
**[2]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from.
**[2]:** If value is `true`. When missing, the value is assumed to be `false`.
**[3]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from.
`messaging.destination_kind` MUST be one of the following:
@ -165,10 +167,10 @@ These attributes should be set to the broker to which the message is sent/from w
For message consumers, the following additional attributes may be set:
<!-- semconv messaging.consumer -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `messaging.operation` | string | A string identifying the kind of message consumption as defined in the [Operation names](#operation-names) section above. If the operation is "send", this attribute MUST NOT be set, since the operation can be inferred from the span kind in that case. | `receive` | No |
| `messaging.consumer_id` | string | The identifier for the consumer receiving a message. For Kafka, set it to `{messaging.kafka.consumer_group} - {messaging.kafka.client_id}`, if both are present, or only `messaging.kafka.consumer_group`. For brokers, such as RabbitMQ and Artemis, set it to the `client_id` of the client consuming the message. | `mygroup - client-6` | No |
| `messaging.operation` | string | A string identifying the kind of message consumption as defined in the [Operation names](#operation-names) section above. If the operation is "send", this attribute MUST NOT be set, since the operation can be inferred from the span kind in that case. | `receive` | Recommended |
| `messaging.consumer_id` | string | The identifier for the consumer receiving a message. For Kafka, set it to `{messaging.kafka.consumer_group} - {messaging.kafka.client_id}`, if both are present, or only `messaging.kafka.consumer_group`. For brokers, such as RabbitMQ and Artemis, set it to the `client_id` of the client consuming the message. | `mygroup - client-6` | Recommended |
`messaging.operation` MUST be one of the following:
@ -193,9 +195,9 @@ In RabbitMQ, the destination is defined by an *exchange* and a *routing key*.
`messaging.destination` MUST be set to the name of the exchange. This will be an empty string if the default exchange is used.
<!-- semconv messaging.rabbitmq -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `messaging.rabbitmq.routing_key` | string | RabbitMQ message routing key. | `myKey` | Unless it is empty. |
| `messaging.rabbitmq.routing_key` | string | RabbitMQ message routing key. | `myKey` | Conditionally Required: If not empty. |
<!-- endsemconv -->
#### Apache Kafka
@ -203,15 +205,17 @@ In RabbitMQ, the destination is defined by an *exchange* and a *routing key*.
For Apache Kafka, the following additional attributes are defined:
<!-- semconv messaging.kafka -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `messaging.kafka.message_key` | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message_id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [1] | `myKey` | No |
| `messaging.kafka.consumer_group` | string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. | `my-group` | No |
| `messaging.kafka.client_id` | string | Client Id for the Consumer or Producer that is handling the message. | `client-5` | No |
| `messaging.kafka.partition` | int | Partition the message is sent to. | `2` | No |
| `messaging.kafka.tombstone` | boolean | A boolean that is true if the message is a tombstone. | | If missing, it is assumed to be false. |
| `messaging.kafka.message_key` | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message_id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [1] | `myKey` | Recommended |
| `messaging.kafka.consumer_group` | string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. | `my-group` | Recommended |
| `messaging.kafka.client_id` | string | Client Id for the Consumer or Producer that is handling the message. | `client-5` | Recommended |
| `messaging.kafka.partition` | int | Partition the message is sent to. | `2` | Recommended |
| `messaging.kafka.tombstone` | boolean | A boolean that is true if the message is a tombstone. | | Conditionally Required: [2] |
**[1]:** If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value.
**[2]:** If value is `true`. When missing, the value is assumed to be `false`.
<!-- endsemconv -->
For Apache Kafka producers, [`peer.service`](./span-general.md#general-remote-service-attributes) SHOULD be set to the name of the broker or service the message will be sent to.
@ -223,15 +227,15 @@ If an intermediary broker is present, `service.name` and `peer.service` will not
Specific attributes for Apache RocketMQ are defined below.
<!-- semconv messaging.rocketmq -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `messaging.rocketmq.namespace` | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` | Yes |
| `messaging.rocketmq.client_group` | string | Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. | `myConsumerGroup` | Yes |
| `messaging.rocketmq.client_id` | string | The unique identifier for each client. | `myhost@8742@s8083jm` | Yes |
| `messaging.rocketmq.message_type` | string | Type of message. | `normal` | No |
| `messaging.rocketmq.message_tag` | string | The secondary classifier of message besides topic. | `tagA` | No |
| `messaging.rocketmq.message_keys` | string[] | Key(s) of message, another way to mark message besides message id. | `[keyA, keyB]` | No |
| `messaging.rocketmq.consumption_model` | string | Model of message consumption. This only applies to consumer spans. | `clustering` | No |
| `messaging.rocketmq.namespace` | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` | Required |
| `messaging.rocketmq.client_group` | string | Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. | `myConsumerGroup` | Required |
| `messaging.rocketmq.client_id` | string | The unique identifier for each client. | `myhost@8742@s8083jm` | Required |
| `messaging.rocketmq.message_type` | string | Type of message. | `normal` | Recommended |
| `messaging.rocketmq.message_tag` | string | The secondary classifier of message besides topic. | `tagA` | Recommended |
| `messaging.rocketmq.message_keys` | string[] | Key(s) of message, another way to mark message besides message id. | `[keyA, keyB]` | Recommended |
| `messaging.rocketmq.consumption_model` | string | Model of message consumption. This only applies to consumer spans. | `clustering` | Recommended |
`messaging.rocketmq.message_type` MUST be one of the following:

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

@ -55,15 +55,15 @@ Examples of span names:
### Common attributes
<!-- semconv rpc -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Yes |
| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | No, but recommended |
| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | No, but recommended |
| `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required |
| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended |
| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended |
| [`net.peer.ip`](span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | See below |
| [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. [3] | `example.com` | See below |
| [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | See below |
| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | See below |
| [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | Conditionally Required: See below |
| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: See below |
**[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
@ -109,10 +109,10 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service
### Server attributes
<!-- semconv rpc.server -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| [`net.host.ip`](span-general.md) | string | Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. | `192.168.0.1` | No |
| [`net.host.name`](span-general.md) | string | Local hostname or similar, see note below. | `localhost` | No |
| [`net.host.ip`](span-general.md) | string | Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. | `192.168.0.1` | Recommended |
| [`net.host.name`](span-general.md) | string | Local hostname or similar, see note below. | `localhost` | Recommended |
<!-- endsemconv -->
### Events
@ -124,12 +124,12 @@ and one received message will be recorded for both client and server spans.
<!-- semconv rpc.message -->
The event name MUST be `message`.
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `message.type` | string | Whether this is a received or sent message. | `SENT` | No |
| `message.id` | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | | No |
| `message.compressed_size` | int | Compressed size of the message in bytes. | | No |
| `message.uncompressed_size` | int | Uncompressed size of the message in bytes. | | No |
| `message.type` | string | Whether this is a received or sent message. | `SENT` | Recommended |
| `message.id` | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | | Recommended |
| `message.compressed_size` | int | Compressed size of the message in bytes. | | Recommended |
| `message.uncompressed_size` | int | Uncompressed size of the message in bytes. | | Recommended |
**[1]:** This way we guarantee that the values will be consistent between different implementations.
@ -156,9 +156,9 @@ For remote procedure calls via [gRPC][], additional conventions are described in
### gRPC Attributes
<!-- semconv rpc.grpc -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `rpc.grpc.status_code` | int | The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. | `0` | Yes |
| `rpc.grpc.status_code` | int | The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. | `0` | Required |
`rpc.grpc.status_code` MUST be one of the following:
@ -198,13 +198,13 @@ Conventions specific to [JSON RPC](https://www.jsonrpc.org/).
### JSON RPC Attributes
<!-- semconv rpc.jsonrpc -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `rpc.jsonrpc.version` | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 does not specify this, the value can be omitted. | `2.0`; `1.0` | If missing, it is assumed to be "1.0". |
| `rpc.jsonrpc.request_id` | string | `id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. | `10`; `request-7`; `` | No |
| `rpc.jsonrpc.error_code` | int | `error.code` property of response if it is an error response. | `-32700`; `100` | If missing, response is assumed to be successful. |
| `rpc.jsonrpc.error_message` | string | `error.message` property of response if it is an error response. | `Parse error`; `User already exists` | No |
| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [1] | `exampleMethod` | Yes |
| `rpc.jsonrpc.version` | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 does not specify this, the value can be omitted. | `2.0`; `1.0` | Conditionally Required: If other than the default version (`1.0`) |
| `rpc.jsonrpc.request_id` | string | `id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. | `10`; `request-7`; `` | Recommended |
| `rpc.jsonrpc.error_code` | int | `error.code` property of response if it is an error response. | `-32700`; `100` | Conditionally Required: If response is not successful. |
| `rpc.jsonrpc.error_message` | string | `error.message` property of response if it is an error response. | `Parse error`; `User already exists` | Recommended |
| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [1] | `exampleMethod` | Required |
**[1]:** This is always required for jsonrpc. See the note in the general RPC conventions for more information.
<!-- endsemconv -->

60
specification/trace/semantic_conventions/span-general.md
View File

@ -32,23 +32,23 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties
### Network transport attributes
<!-- semconv network -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `net.transport` | string | Transport protocol used. See note below. | `ip_tcp` | No |
| `net.app.protocol.name` | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | No |
| `net.app.protocol.version` | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | No |
| `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | No |
| `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | No |
| `net.peer.name` | string | Remote hostname or similar, see note below. [2] | `example.com` | No |
| `net.host.ip` | string | Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. | `192.168.0.1` | No |
| `net.host.port` | int | Like `net.peer.port` but for the host port. | `35555` | No |
| `net.host.name` | string | Local hostname or similar, see note below. | `localhost` | No |
| `net.host.connection.type` | string | The internet connection type currently being used by the host. | `wifi` | No |
| `net.host.connection.subtype` | string | This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. | `LTE` | No |
| `net.host.carrier.name` | string | The name of the mobile carrier. | `sprint` | No |
| `net.host.carrier.mcc` | string | The mobile carrier country code. | `310` | No |
| `net.host.carrier.mnc` | string | The mobile carrier network code. | `001` | No |
| `net.host.carrier.icc` | string | The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. | `DE` | No |
| `net.transport` | string | Transport protocol used. See note below. | `ip_tcp` | Recommended |
| `net.app.protocol.name` | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| `net.app.protocol.version` | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended |
| `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | Recommended |
| `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | Recommended |
| `net.peer.name` | string | Remote hostname or similar, see note below. [2] | `example.com` | Recommended |
| `net.host.ip` | string | Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. | `192.168.0.1` | Recommended |
| `net.host.port` | int | Like `net.peer.port` but for the host port. | `35555` | Recommended |
| `net.host.name` | string | Local hostname or similar, see note below. | `localhost` | Recommended |
| `net.host.connection.type` | string | The internet connection type currently being used by the host. | `wifi` | Recommended |
| `net.host.connection.subtype` | string | This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. | `LTE` | Recommended |
| `net.host.carrier.name` | string | The name of the mobile carrier. | `sprint` | Recommended |
| `net.host.carrier.mcc` | string | The mobile carrier country code. | `310` | Recommended |
| `net.host.carrier.mnc` | string | The mobile carrier network code. | `001` | Recommended |
| `net.host.carrier.icc` | string | The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. | `DE` | Recommended |
**[1]:** `net.app.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
@ -130,9 +130,9 @@ Users can define what the name of a service is based on their particular semanti
Instrumentations SHOULD provide a way for users to configure this name.
<!-- semconv peer -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `peer.service` | string | The [`service.name`](../../resource/semantic_conventions/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. | `AuthTokenCache` | No |
| `peer.service` | string | The [`service.name`](../../resource/semantic_conventions/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. | `AuthTokenCache` | Recommended |
<!-- endsemconv -->
Examples of `peer.service` that users may specify:
@ -145,11 +145,11 @@ Examples of `peer.service` that users may specify:
These attributes may be used for any operation with an authenticated and/or authorized enduser.
<!-- semconv identity -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `enduser.id` | string | Username or client_id extracted from the access token or [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) header in the inbound request from outside the system. | `username` | No |
| `enduser.role` | string | Actual/assumed role the client is making the request under extracted from token or application security context. | `admin` | No |
| `enduser.scope` | string | Scopes or granted authorities the client currently possesses extracted from token or application security context. The value would come from the scope associated with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3) or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). | `read:message, write:files` | No |
| `enduser.id` | string | Username or client_id extracted from the access token or [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) header in the inbound request from outside the system. | `username` | Recommended |
| `enduser.role` | string | Actual/assumed role the client is making the request under extracted from token or application security context. | `admin` | Recommended |
| `enduser.scope` | string | Scopes or granted authorities the client currently possesses extracted from token or application security context. The value would come from the scope associated with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3) or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). | `read:message, write:files` | Recommended |
<!-- endsemconv -->
These attributes describe the authenticated user driving the user agent making requests to the instrumented
@ -194,10 +194,10 @@ These attributes may be used for any operation to store information about
a thread that started a span.
<!-- semconv thread -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `thread.id` | int | Current "managed" thread ID (as opposed to OS thread ID). | `42` | No |
| `thread.name` | string | Current thread name. | `main` | No |
| `thread.id` | int | Current "managed" thread ID (as opposed to OS thread ID). | `42` | Recommended |
| `thread.name` | string | Current thread name. | `main` | Recommended |
<!-- endsemconv -->
Examples of where `thread.id` and `thread.name` can be extracted from:
@ -220,10 +220,10 @@ The attributes listed below allow to report this unit of code and therefore to p
about the span.
<!-- semconv code -->
| Attribute | Type | Description | Examples | Required |
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `code.function` | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` | No |
| `code.namespace` | string | The "namespace" within which `code.function` is defined. Usually the qualified class or module name, such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. | `com.example.MyHttpService` | No |
| `code.filepath` | string | The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). | `/usr/local/MyApplication/content_root/app/index.php` | No |
| `code.lineno` | int | The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `42` | No |
| `code.function` | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` | Recommended |
| `code.namespace` | string | The "namespace" within which `code.function` is defined. Usually the qualified class or module name, such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. | `com.example.MyHttpService` | Recommended |
| `code.filepath` | string | The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). | `/usr/local/MyApplication/content_root/app/index.php` | Recommended |
| `code.lineno` | int | The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `42` | Recommended |
<!-- endsemconv -->