From 4e773c010f77e6778d9ccd2a7224728d58c9bad0 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 16 May 2022 11:19:03 -0700 Subject: [PATCH] parent bff2cc1365bb81b03f78a732dec822fff787e288 author Liudmila Molkova 1652725143 -0700 committer Liudmila Molkova 1655143447 -0700 parent bff2cc1365bb81b03f78a732dec822fff787e288 author Liudmila Molkova 1652725143 -0700 committer Liudmila Molkova 1655143419 -0700 parent bff2cc1365bb81b03f78a732dec822fff787e288 author Liudmila Molkova 1652725143 -0700 committer Liudmila Molkova 1655143334 -0700 Specify requirement levels in existing conventions --- .vscode/settings.json | 2 +- CHANGELOG.md | 2 + Makefile | 2 +- internal/tools/schema_check.sh | 2 +- semantic_conventions/README.md | 6 +- semantic_conventions/resource/faas.yaml | 2 +- semantic_conventions/resource/os.yaml | 2 +- semantic_conventions/resource/process.yaml | 28 ++-- semantic_conventions/resource/service.yaml | 2 +- semantic_conventions/resource/webengine.yaml | 2 +- semantic_conventions/trace/cloudevents.yaml | 8 +- semantic_conventions/trace/database.yaml | 44 +++-- semantic_conventions/trace/faas.yaml | 18 +-- semantic_conventions/trace/http.yaml | 10 +- .../trace/instrumentation/aws-sdk.yml | 4 +- semantic_conventions/trace/messaging.yaml | 34 ++-- semantic_conventions/trace/rpc.yaml | 28 ++-- .../semantic_conventions/database-metrics.md | 12 +- .../semantic_conventions/faas-metrics.md | 12 +- .../semantic_conventions/http-metrics.md | 16 +- .../metrics/semantic_conventions/rpc.md | 12 +- .../resource/semantic_conventions/README.md | 20 +-- .../resource/semantic_conventions/browser.md | 8 +- .../resource/semantic_conventions/cloud.md | 12 +- .../cloud_provider/aws/ecs.md | 14 +- .../cloud_provider/aws/eks.md | 4 +- .../cloud_provider/aws/logs.md | 10 +- .../semantic_conventions/container.md | 12 +- .../deployment_environment.md | 4 +- .../resource/semantic_conventions/device.md | 10 +- .../resource/semantic_conventions/faas.md | 12 +- .../resource/semantic_conventions/host.md | 16 +- .../resource/semantic_conventions/k8s.md | 62 +++---- .../resource/semantic_conventions/os.md | 10 +- .../resource/semantic_conventions/process.md | 34 ++-- .../semantic_conventions/webengine.md | 8 +- .../trace/semantic_conventions/cloudevents.md | 12 +- .../semantic_conventions/compatibility.md | 4 +- .../trace/semantic_conventions/database.md | 64 ++++---- .../trace/semantic_conventions/exceptions.md | 6 +- .../trace/semantic_conventions/faas.md | 36 ++--- .../trace/semantic_conventions/http.md | 46 +++--- .../instrumentation/aws-lambda.md | 4 +- .../instrumentation/aws-sdk.md | 152 +++++++++--------- .../trace/semantic_conventions/messaging.md | 78 ++++----- .../trace/semantic_conventions/rpc.md | 44 ++--- .../semantic_conventions/span-general.md | 60 +++---- 47 files changed, 502 insertions(+), 488 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 210a6529acf..b9c897ec50b 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -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" ] }, diff --git a/CHANGELOG.md b/CHANGELOG.md index 234ca38ff31..a0072ed47ae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,8 @@ release. - Add `net.app.protocol.*` attributes ([#2602](https://github.com/open-telemetry/opentelemetry-specification/pull/2602)). +- Adopt attribute requirement levels in semantic conventions + ([#2594](https://github.com/open-telemetry/opentelemetry-specification/pull/2594)) ### Compatibility diff --git a/Makefile b/Makefile index c81bdc7c70f..62ed0daa6eb 100644 --- a/Makefile +++ b/Makefile @@ -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 diff --git a/internal/tools/schema_check.sh b/internal/tools/schema_check.sh index 73194d86d91..624a1d6d202 100755 --- a/internal/tools/schema_check.sh +++ b/internal/tools/schema_check.sh @@ -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") diff --git a/semantic_conventions/README.md b/semantic_conventions/README.md index 24d4ab045b1..596e23fce78 100644 --- a/semantic_conventions/README.md +++ b/semantic_conventions/README.md @@ -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. diff --git a/semantic_conventions/resource/faas.yaml b/semantic_conventions/resource/faas.yaml index a610e7276ca..9d3ffbc744e 100644 --- a/semantic_conventions/resource/faas.yaml +++ b/semantic_conventions/resource/faas.yaml @@ -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: | diff --git a/semantic_conventions/resource/os.yaml b/semantic_conventions/resource/os.yaml index 69bc7193eb4..a43db1fc26c 100644 --- a/semantic_conventions/resource/os.yaml +++ b/semantic_conventions/resource/os.yaml @@ -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 diff --git a/semantic_conventions/resource/process.yaml b/semantic_conventions/resource/process.yaml index 93000d52490..9f8b93418f5 100644 --- a/semantic_conventions/resource/process.yaml +++ b/semantic_conventions/resource/process.yaml @@ -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: > diff --git a/semantic_conventions/resource/service.yaml b/semantic_conventions/resource/service.yaml index 0dde11aa2ed..7fdd67caa96 100644 --- a/semantic_conventions/resource/service.yaml +++ b/semantic_conventions/resource/service.yaml @@ -6,7 +6,7 @@ groups: attributes: - id: name type: string - required: always + requirement_level: required brief: > Logical name of the service. note: > diff --git a/semantic_conventions/resource/webengine.yaml b/semantic_conventions/resource/webengine.yaml index cd5d89fc531..421f6a0523d 100644 --- a/semantic_conventions/resource/webengine.yaml +++ b/semantic_conventions/resource/webengine.yaml @@ -6,7 +6,7 @@ groups: attributes: - id: name type: string - required: always + requirement_level: required brief: > The name of the web engine. examples: ['WildFly'] diff --git a/semantic_conventions/trace/cloudevents.yaml b/semantic_conventions/trace/cloudevents.yaml index 6a6f6c9a7fd..dbd1a9a1e47 100644 --- a/semantic_conventions/trace/cloudevents.yaml +++ b/semantic_conventions/trace/cloudevents.yaml @@ -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'] diff --git a/semantic_conventions/trace/database.yaml b/semantic_conventions/trace/database.yaml index 95bb38c3265..31bb41fa28e 100644 --- a/semantic_conventions/trace/database.yaml +++ b/semantic_conventions/trace/database.yaml @@ -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 diff --git a/semantic_conventions/trace/faas.yaml b/semantic_conventions/trace/faas.yaml index d451d9273b4..6dc7bd44196 100644 --- a/semantic_conventions/trace/faas.yaml +++ b/semantic_conventions/trace/faas.yaml @@ -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 diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml index cdff85d9100..e4c4c4adb10 100644 --- a/semantic_conventions/trace/http.yaml +++ b/semantic_conventions/trace/http.yaml @@ -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 diff --git a/semantic_conventions/trace/instrumentation/aws-sdk.yml b/semantic_conventions/trace/instrumentation/aws-sdk.yml index 35abe1f70c7..f33f7e3fe5c 100644 --- a/semantic_conventions/trace/instrumentation/aws-sdk.yml +++ b/semantic_conventions/trace/instrumentation/aws-sdk.yml @@ -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 diff --git a/semantic_conventions/trace/messaging.yaml b/semantic_conventions/trace/messaging.yaml index d83d6e94a6a..1ae44f24c06 100644 --- a/semantic_conventions/trace/messaging.yaml +++ b/semantic_conventions/trace/messaging.yaml @@ -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' diff --git a/semantic_conventions/trace/rpc.yaml b/semantic_conventions/trace/rpc.yaml index 5a6748bdefb..6ca4a990461 100644 --- a/semantic_conventions/trace/rpc.yaml +++ b/semantic_conventions/trace/rpc.yaml @@ -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. diff --git a/specification/metrics/semantic_conventions/database-metrics.md b/specification/metrics/semantic_conventions/database-metrics.md index 9ab0443cfcd..353e748b3e0 100644 --- a/specification/metrics/semantic_conventions/database-metrics.md +++ b/specification/metrics/semantic_conventions/database-metrics.md @@ -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 | diff --git a/specification/metrics/semantic_conventions/faas-metrics.md b/specification/metrics/semantic_conventions/faas-metrics.md index 45d2bdc6225..0d83b0b19f3 100644 --- a/specification/metrics/semantic_conventions/faas-metrics.md +++ b/specification/metrics/semantic_conventions/faas-metrics.md @@ -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). diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 3a72cb02d00..bbb471e96bd 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -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={}"`. | diff --git a/specification/metrics/semantic_conventions/rpc.md b/specification/metrics/semantic_conventions/rpc.md index 85b29abf693..6034f46c0a9 100644 --- a/specification/metrics/semantic_conventions/rpc.md +++ b/specification/metrics/semantic_conventions/rpc.md @@ -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. -| 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). diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md index 4585d17a5f4..31f29611091 100644 --- a/specification/resource/semantic_conventions/README.md +++ b/specification/resource/semantic_conventions/README.md @@ -63,12 +63,12 @@ as specified in the [Resource SDK specification](../sdk.md#sdk-provided-resource **Description:** A service instance. -| 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. -| 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. diff --git a/specification/resource/semantic_conventions/browser.md b/specification/resource/semantic_conventions/browser.md index 0a4a4d1b9bd..ca720c99a48 100644 --- a/specification/resource/semantic_conventions/browser.md +++ b/specification/resource/semantic_conventions/browser.md @@ -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. -| 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). diff --git a/specification/resource/semantic_conventions/cloud.md b/specification/resource/semantic_conventions/cloud.md index 78a2c11de6e..68ce8c3c8c6 100644 --- a/specification/resource/semantic_conventions/cloud.md +++ b/specification/resource/semantic_conventions/cloud.md @@ -7,13 +7,13 @@ **Description:** A cloud infrastructure (e.g. GCP, Azure, AWS). -| 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). diff --git a/specification/resource/semantic_conventions/cloud_provider/aws/ecs.md b/specification/resource/semantic_conventions/cloud_provider/aws/ecs.md index a2b38d2270f..e9b56cc8b17 100644 --- a/specification/resource/semantic_conventions/cloud_provider/aws/ecs.md +++ b/specification/resource/semantic_conventions/cloud_provider/aws/ecs.md @@ -7,14 +7,14 @@ **Description:** Resources used by AWS Elastic Container Service (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: diff --git a/specification/resource/semantic_conventions/cloud_provider/aws/eks.md b/specification/resource/semantic_conventions/cloud_provider/aws/eks.md index d4e36cbd07b..9514c8d56e6 100644 --- a/specification/resource/semantic_conventions/cloud_provider/aws/eks.md +++ b/specification/resource/semantic_conventions/cloud_provider/aws/eks.md @@ -7,7 +7,7 @@ **Description:** Resources used by AWS Elastic Kubernetes Service (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 | diff --git a/specification/resource/semantic_conventions/cloud_provider/aws/logs.md b/specification/resource/semantic_conventions/cloud_provider/aws/logs.md index 5d095599fb2..7acec435a0d 100644 --- a/specification/resource/semantic_conventions/cloud_provider/aws/logs.md +++ b/specification/resource/semantic_conventions/cloud_provider/aws/logs.md @@ -7,12 +7,12 @@ **Description:** Log attributes for Amazon Web Services. -| 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. diff --git a/specification/resource/semantic_conventions/container.md b/specification/resource/semantic_conventions/container.md index 7cf948e8202..64948141d06 100644 --- a/specification/resource/semantic_conventions/container.md +++ b/specification/resource/semantic_conventions/container.md @@ -7,11 +7,11 @@ **Description:** A container instance. -| 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 | diff --git a/specification/resource/semantic_conventions/deployment_environment.md b/specification/resource/semantic_conventions/deployment_environment.md index e838fa11531..35cff71aa97 100644 --- a/specification/resource/semantic_conventions/deployment_environment.md +++ b/specification/resource/semantic_conventions/deployment_environment.md @@ -7,7 +7,7 @@ **Description:** The software 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 | diff --git a/specification/resource/semantic_conventions/device.md b/specification/resource/semantic_conventions/device.md index 26fe7fb5cd0..6f746e76385 100644 --- a/specification/resource/semantic_conventions/device.md +++ b/specification/resource/semantic_conventions/device.md @@ -7,12 +7,12 @@ **Description**: The device on which the process represented by this resource is running. -| 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. diff --git a/specification/resource/semantic_conventions/faas.md b/specification/resource/semantic_conventions/faas.md index 0450bdfc196..6e58c5cadbd 100644 --- a/specification/resource/semantic_conventions/faas.md +++ b/specification/resource/semantic_conventions/faas.md @@ -14,13 +14,13 @@ See also: ## FaaS resource attributes -| 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 diff --git a/specification/resource/semantic_conventions/host.md b/specification/resource/semantic_conventions/host.md index b8b0aa74241..847d58b7f6d 100644 --- a/specification/resource/semantic_conventions/host.md +++ b/specification/resource/semantic_conventions/host.md @@ -7,15 +7,15 @@ **Description:** A host is defined as a general computing instance. -| 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. diff --git a/specification/resource/semantic_conventions/k8s.md b/specification/resource/semantic_conventions/k8s.md index 0092edf1516..2b2387c54c6 100644 --- a/specification/resource/semantic_conventions/k8s.md +++ b/specification/resource/semantic_conventions/k8s.md @@ -22,9 +22,9 @@ Kubernetes object, but "name" is usually more user friendly so can be also set. **Description:** A Kubernetes 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 | ## Node @@ -34,10 +34,10 @@ Kubernetes object, but "name" is usually more user friendly so can be also set. **Description:** A Kubernetes 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 | ## Namespace @@ -50,9 +50,9 @@ a namespace, but not across namespaces. **Description:** A Kubernetes 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 | ## Pod @@ -65,10 +65,10 @@ containers on your cluster. **Description:** A Kubernetes Pod object. -| 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 | ## Container @@ -85,10 +85,10 @@ to a running container. **Description:** A container in a [PodTemplate](https://kubernetes.io/docs/concepts/workloads/pods/#pod-templates). -| 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 | ## ReplicaSet @@ -101,10 +101,10 @@ any given time. **Description:** A Kubernetes ReplicaSet object. -| 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 | ## Deployment @@ -118,10 +118,10 @@ distributed among the nodes of a cluster. **Description:** A Kubernetes Deployment object. -| 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 | ## StatefulSet @@ -134,10 +134,10 @@ about the ordering and uniqueness of these Pods. **Description:** A Kubernetes StatefulSet object. -| 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 | ## DaemonSet @@ -149,10 +149,10 @@ A DaemonSet ensures that all (or some) Nodes run a copy of a Pod. **Description:** A Kubernetes DaemonSet object. -| 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 | ## Job @@ -165,10 +165,10 @@ successfully terminate. **Description:** A Kubernetes Job object. -| 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 | ## CronJob @@ -180,8 +180,8 @@ A CronJob creates Jobs on a repeating schedule. **Description:** A Kubernetes CronJob object. -| 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 | diff --git a/specification/resource/semantic_conventions/os.md b/specification/resource/semantic_conventions/os.md index 1c8bf64a883..c3db6708909 100644 --- a/specification/resource/semantic_conventions/os.md +++ b/specification/resource/semantic_conventions/os.md @@ -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. -| 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. diff --git a/specification/resource/semantic_conventions/process.md b/specification/resource/semantic_conventions/process.md index 025038a9254..dbfa1a7e38f 100644 --- a/specification/resource/semantic_conventions/process.md +++ b/specification/resource/semantic_conventions/process.md @@ -25,15 +25,23 @@ **Description:** An operating system 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` 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. -| 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 | How to set these attributes for particular runtime kinds is described in the following subsections. diff --git a/specification/resource/semantic_conventions/webengine.md b/specification/resource/semantic_conventions/webengine.md index 20274a99c0c..2869d00d388 100644 --- a/specification/resource/semantic_conventions/webengine.md +++ b/specification/resource/semantic_conventions/webengine.md @@ -5,11 +5,11 @@ **Description:** Resource describing the packaged software running the application code. Web engines are typically executed using process.runtime. -| 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 | 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. diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index bddf3ea79a9..306792a00bd 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -194,11 +194,11 @@ in the [table below](#attributes). The following attributes are applicable to creation and processing Spans. -| 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 | diff --git a/specification/trace/semantic_conventions/compatibility.md b/specification/trace/semantic_conventions/compatibility.md index 4c95a52e62b..b5a4f2d0740 100644 --- a/specification/trace/semantic_conventions/compatibility.md +++ b/specification/trace/semantic_conventions/compatibility.md @@ -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). -| 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. diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md index b1ae4e925f6..413589fbf28 100644 --- a/specification/trace/semantic_conventions/database.md +++ b/specification/trace/semantic_conventions/database.md @@ -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. -| 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 -| 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). @@ -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. -| 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. @@ -178,15 +178,13 @@ In **HBase**, `db.name` SHOULD be set to the HBase namespace. ### Call-level attributes for specific technologies -| 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. #### Cassandra @@ -194,15 +192,15 @@ In **HBase**, `db.name` SHOULD be set to the HBase namespace. Separated for clarity. -| 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. diff --git a/specification/trace/semantic_conventions/exceptions.md b/specification/trace/semantic_conventions/exceptions.md index 916b372f7d9..25960ad2c5d 100644 --- a/specification/trace/semantic_conventions/exceptions.md +++ b/specification/trace/semantic_conventions/exceptions.md @@ -42,12 +42,12 @@ their types. 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". diff --git a/specification/trace/semantic_conventions/faas.md b/specification/trace/semantic_conventions/faas.md index f24495830e7..f6b6c65f172 100644 --- a/specification/trace/semantic_conventions/faas.md +++ b/specification/trace/semantic_conventions/faas.md @@ -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). -| 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 -| 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. -| 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. -| 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. -| 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 | ### Other diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 8762a5c68d5..5d6cf79e6d9 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -59,23 +59,23 @@ Don't set the span status description if the reason can be inferred from `http.s ## Common Attributes -| 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.` | string[] | HTTP request headers, `` 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.` | string[] | HTTP response headers, `` 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.` | string[] | HTTP request headers, `` 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.` | string[] | HTTP response headers, `` 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. -| 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. -| 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. diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 8486ec79d82..dc4ad1e47d1 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -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: -| 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. diff --git a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md index a08359e6d02..73bc631638d 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md @@ -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. -| 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. -| 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 | ### 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 | ### 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 | ### 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 | ### 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 | ### 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 | ### 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 | ### 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 | ### 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 | ### 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 | ### 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 | ### 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 | ### 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 | ### 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 | diff --git a/specification/trace/semantic_conventions/messaging.md b/specification/trace/semantic_conventions/messaging.md index 0abaf12d56d..d08fc0fed0c 100644 --- a/specification/trace/semantic_conventions/messaging.md +++ b/specification/trace/semantic_conventions/messaging.md @@ -126,25 +126,27 @@ The following operations related to messages are defined for these semantic conv ## Messaging attributes -| 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. | - -**[1]:** Required only 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. +| `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]:** If the message destination is either a `queue` or `topic`. + +**[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: -| 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. -| 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. | #### 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: -| 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`. 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. -| 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: diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 0acf95ae6bc..6cbee348d7b 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -55,15 +55,15 @@ Examples of span names: ### Common attributes -| 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 -| 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 | ### Events @@ -124,12 +124,12 @@ and one received message will be recorded for both client and server spans. 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 -| 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 -| 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. diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index 885d3921c62..fc0e07185dc 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -32,23 +32,23 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties ### Network transport attributes -| 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. -| 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 | 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. -| 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 | 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. -| 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 | 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. -| 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 |