From e043c71dd57d87bf14b004780753935dc91fb2f4 Mon Sep 17 00:00:00 2001 From: liudmila molkova Date: Thu, 11 Dec 2025 17:09:28 -0800 Subject: [PATCH 1/9] Merge rpc.method and rpc.service into one attribute, clarify cardinality concerns --- docs/cloud-providers/aws-sdk.md | 4 +- docs/db/dynamodb.md | 52 ++-- docs/object-stores/s3.md | 4 +- docs/registry/attributes/rpc.md | 36 ++- docs/rpc/connect-rpc.md | 126 +++++--- docs/rpc/grpc.md | 118 ++++--- docs/rpc/json-rpc.md | 40 ++- docs/rpc/rpc-metrics.md | 294 ++++++++++++------ docs/rpc/rpc-spans.md | 163 +++++----- model/rpc/common.yaml | 3 +- model/rpc/deprecated/registry-deprecated.yaml | 20 ++ model/rpc/metrics.yaml | 9 +- model/rpc/registry.yaml | 50 ++- model/rpc/spans.yaml | 69 ++-- 14 files changed, 645 insertions(+), 343 deletions(-) diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md index 34d2db5ef9..cee7e2fc32 100644 --- a/docs/cloud-providers/aws-sdk.md +++ b/docs/cloud-providers/aws-sdk.md @@ -44,8 +44,8 @@ interesting conventions are found. | [`aws.extended_request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If available. | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). diff --git a/docs/db/dynamodb.md b/docs/db/dynamodb.md index f49277f6f6..d2f357bc84 100644 --- a/docs/db/dynamodb.md +++ b/docs/db/dynamodb.md @@ -60,8 +60,8 @@ This span represents a `DynamoDB.BatchGetItem` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | The keys in the `RequestItems` object field. | `["Users", "Cats"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -111,8 +111,8 @@ This span represents a `DynamoDB.BatchWriteItem` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | The keys in the `RequestItems` object field. | `["Users", "Cats"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -166,8 +166,8 @@ This span represents a `DynamoDB.CreateTable` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -217,8 +217,8 @@ This span represents a `DynamoDB.DeleteItem` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -266,8 +266,8 @@ This span represents a `DynamoDB.DeleteTable` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -315,8 +315,8 @@ This span represents a `DynamoDB.DescribeTable` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -367,8 +367,8 @@ This span represents a `DynamoDB.GetItem` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -418,8 +418,8 @@ This span represents a `DynamoDB.ListTables` call. | [`aws.dynamodb.table_count`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | The number of items in the `TableNames` response parameter. | `20` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -469,8 +469,8 @@ This span represents a `DynamoDB.PutItem` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | The keys in the `RequestItems` object field. | `["Users", "Cats"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -526,8 +526,8 @@ This span represents a `DynamoDB.Query` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -586,8 +586,8 @@ This span represents a `DynamoDB.Scan` call. | [`aws.dynamodb.total_segments`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | The value of the `TotalSegments` request parameter. | `100` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -637,8 +637,8 @@ This span represents a `DynamoDB.UpdateItem` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -691,8 +691,8 @@ This span represents a `DynamoDB.UpdateTable` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). diff --git a/docs/object-stores/s3.md b/docs/object-stores/s3.md index 4f353ebfcd..7a942f3beb 100644 --- a/docs/object-stores/s3.md +++ b/docs/object-stores/s3.md @@ -33,8 +33,8 @@ Semantic Conventions for AWS S3 client spans extend the general [AWS SDK Semanti | [`aws.s3.part_number`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000. [5] | `3456` | | [`aws.s3.upload_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Upload ID that identifies the multipart upload. [6] | `dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [7] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `aws.s3.bucket`:** The `bucket` attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter. This applies to almost all S3 operations except `list-buckets`. diff --git a/docs/registry/attributes/rpc.md b/docs/registry/attributes/rpc.md index 37fc8f6944..937f886928 100644 --- a/docs/registry/attributes/rpc.md +++ b/docs/registry/attributes/rpc.md @@ -18,16 +18,38 @@ This document defines attributes for remote procedure calls. | `rpc.message.id` | ![Development](https://img.shields.io/badge/-development-blue) | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | | | `rpc.message.type` | ![Development](https://img.shields.io/badge/-development-blue) | string | Whether this is a received or sent message. | `SENT`; `RECEIVED` | | `rpc.message.uncompressed_size` | ![Development](https://img.shields.io/badge/-development-blue) | int | Uncompressed size of the message in bytes. | | -| `rpc.method` | ![Development](https://img.shields.io/badge/-development-blue) | string | This is the logical name of the method from the RPC interface perspective. [2] | `exampleMethod` | +| `rpc.method.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | The fully-qualified logical name of the method from the RPC interface perspective. [2] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| `rpc.method.name_original` | ![Development](https://img.shields.io/badge/-development-blue) | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | | `rpc.request.metadata.` | ![Development](https://img.shields.io/badge/-development-blue) | string[] | RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [3] | `["1.2.3.4", "1.2.3.5"]` | | `rpc.response.metadata.` | ![Development](https://img.shields.io/badge/-development-blue) | string[] | RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [4] | `["attribute_value"]` | | `rpc.response.status_code` | ![Development](https://img.shields.io/badge/-development-blue) | string | Status code of the RPC returned by the RPC server or generated by the client [5] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| `rpc.service` | ![Development](https://img.shields.io/badge/-development-blue) | string | The full (logical) name of the service being called, including its package name, if applicable. [6] | `myservice.EchoService` | -| `rpc.system.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | The Remote Procedure Call (RPC) system. [7] | `grpc`; `dubbo`; `connectrpc` | +| `rpc.system.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | The Remote Procedure Call (RPC) system. [6] | `grpc`; `dubbo`; `connectrpc` | **[1] `rpc.message.id`:** This way we guarantee that the values will be consistent between different implementations. -**[2] `rpc.method`:** 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.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. +**[2] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. + +Some RPC frameworks or libraries provide a fixed set of recognized methods +for client stubs and server implementations. Instrumentations for such +frameworks MUST set this attribute to the original method name only +when the method is recognized by the framework or library. + +When the method is not recognized, for example, when the server receives +a request for a method that is not predefined on the server, or when +instrumentation is not able to reliably detect if the method is predefined, +the attribute MUST be set to `_OTHER`. In such cases, tracing +instrumentations MUST also set `rpc.method.name_original` attribute to +the original method value. + +If the RPC instrumentation could end up converting valid RPC methods to +`_OTHER`, then it SHOULD provide a way to configure the list of recognized +RPC methods. + +The `rpc.method.name` can be different from the name of any implementing +method/function. +The `code.function.name` attribute may be used to record the fully-qualified +method actually executing the call on the server side, or the +RPC client stub method on the client side. **[3] `rpc.request.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. @@ -44,9 +66,7 @@ the `rpc.response.metadata.my-custom-key` attribute with value `["attribute_valu **[5] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. -**[6] `rpc.service`:** 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.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub class on the client side. - -**[7] `rpc.system.name`:** The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. +**[6] `rpc.system.name`:** The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. --- @@ -90,6 +110,8 @@ Deprecated rpc message attributes. | `rpc.jsonrpc.error_message` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Use the span status description or `error.message` attribute on other signals. | string | Deprecated, use span status description or `error.message` attribute on other signals. | `Parse error`; `User already exists` | | `rpc.jsonrpc.request_id` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `jsonrpc.request.id`. | string | Deprecated, use `jsonrpc.request.id` instead. | `10`; `request-7`; `` | | `rpc.jsonrpc.version` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `jsonrpc.protocol.version`. | string | Deprecated, use `jsonrpc.protocol.version` instead. | `2.0`; `1.0` | +| `rpc.method` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | string | Deprecated, use fully-qualified `rpc.method.name` instead. | `exampleMethod` | +| `rpc.service` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | string | Deprecated, usefully-qualified `rpc.method.name` instead. | `myservice.EchoService` | | `rpc.system` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `rpc.system.name`. | string | Deprecated, use `rpc.system.name` attribute instead. | `grpc`; `java_rmi`; `dotnet_wcf` | --- diff --git a/docs/rpc/connect-rpc.md b/docs/rpc/connect-rpc.md index a0cb253e48..3620b58a0e 100644 --- a/docs/rpc/connect-rpc.md +++ b/docs/rpc/connect-rpc.md @@ -36,15 +36,15 @@ document for details on how to record span status. | --- | --- | --- | --- | --- | --- | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The [error code](https://connectrpc.com//docs/protocol/#error-codes) of the Connect response. [3] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [4] | int | Server port number. [5] | `80`; `8080`; `443` | +| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.method.name_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [4] | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | +| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The [error code](https://connectrpc.com//docs/protocol/#error-codes) of the Connect response. [5] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | +| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [6] | int | Server port number. [7] | `80`; `8080`; `443` | | [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [6] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [7] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [8] | `tcp`; `udp` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | This is the logical name of the method from the RPC interface perspective. [9] | `exampleMethod` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The full (logical) name of the service being called, including its package name, if applicable. [10] | `myservice.EchoService` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [8] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [9] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [10] | `tcp`; `udp` | | [`rpc.request.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [11] | `["1.2.3.4", "1.2.3.5"]` | | [`rpc.response.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [12] | `["attribute_value"]` | @@ -64,26 +64,48 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[3] `rpc.response.status_code`:** All error codes except `OK` SHOULD be considered errors. +**[3] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. + +Some RPC frameworks or libraries provide a fixed set of recognized methods +for client stubs and server implementations. Instrumentations for such +frameworks MUST set this attribute to the original method name only +when the method is recognized by the framework or library. + +When the method is not recognized, for example, when the server receives +a request for a method that is not predefined on the server, or when +instrumentation is not able to reliably detect if the method is predefined, +the attribute MUST be set to `_OTHER`. In such cases, tracing +instrumentations MUST also set `rpc.method.name_original` attribute to +the original method value. + +If the RPC instrumentation could end up converting valid RPC methods to +`_OTHER`, then it SHOULD provide a way to configure the list of recognized +RPC methods. + +The `rpc.method.name` can be different from the name of any implementing +method/function. +The `code.function.name` attribute may be used to record the fully-qualified +method actually executing the call on the server side, or the +RPC client stub method on the client side. -**[4] `server.port`:** if the port is supported by the network transport used for communication. +**[4] `rpc.method.name_original`:** If and only if it's different than `rpc.method.name`. -**[5] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[5] `rpc.response.status_code`:** All error codes except `OK` SHOULD be considered errors. -**[6] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[6] `server.port`:** if the port is supported by the network transport used for communication. -**[7] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. +**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[8] `network.transport`:** The value SHOULD be normalized to lowercase. +**[8] `network.protocol.name`:** The value SHOULD be normalized to lowercase. + +**[9] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. + +**[10] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[9] `rpc.method`:** 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.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - -**[10] `rpc.service`:** 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.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub class on the client side. - **[11] `rpc.request.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. @@ -99,8 +121,7 @@ the `rpc.response.metadata.my-custom-key` attribute with value `["attribute_valu The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* [`rpc.method`](/docs/registry/attributes/rpc.md) -* [`rpc.service`](/docs/registry/attributes/rpc.md) +* [`rpc.method.name`](/docs/registry/attributes/rpc.md) * [`server.address`](/docs/registry/attributes/server.md) * [`server.port`](/docs/registry/attributes/server.md) @@ -154,17 +175,17 @@ document for details on how to record span status. | --- | --- | --- | --- | --- | --- | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The [error code](https://connectrpc.com/docs/protocol/#error-codes) of the Connect response. [3] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [4] | int | Server port number. [5] | `80`; `8080`; `443` | -| [`client.address`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [6] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | -| [`client.port`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | Client port number. [7] | `65123` | +| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.method.name_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [4] | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | +| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The [error code](https://connectrpc.com/docs/protocol/#error-codes) of the Connect response. [5] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | +| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [6] | int | Server port number. [7] | `80`; `8080`; `443` | +| [`client.address`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [8] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | +| [`client.port`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | Client port number. [9] | `65123` | | [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [8] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [9] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [10] | `tcp`; `udp` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | This is the logical name of the method from the RPC interface perspective. [11] | `exampleMethod` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The full (logical) name of the service being called, including its package name, if applicable. [12] | `myservice.EchoService` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [10] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [11] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [12] | `tcp`; `udp` | | [`rpc.request.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [13] | `["1.2.3.4", "1.2.3.5"]` | | [`rpc.response.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [14] | `["attribute_value"]` | @@ -184,7 +205,33 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[3] `rpc.response.status_code`:** The following error codes SHOULD be considered errors: +**[3] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. + +Some RPC frameworks or libraries provide a fixed set of recognized methods +for client stubs and server implementations. Instrumentations for such +frameworks MUST set this attribute to the original method name only +when the method is recognized by the framework or library. + +When the method is not recognized, for example, when the server receives +a request for a method that is not predefined on the server, or when +instrumentation is not able to reliably detect if the method is predefined, +the attribute MUST be set to `_OTHER`. In such cases, tracing +instrumentations MUST also set `rpc.method.name_original` attribute to +the original method value. + +If the RPC instrumentation could end up converting valid RPC methods to +`_OTHER`, then it SHOULD provide a way to configure the list of recognized +RPC methods. + +The `rpc.method.name` can be different from the name of any implementing +method/function. +The `code.function.name` attribute may be used to record the fully-qualified +method actually executing the call on the server side, or the +RPC client stub method on the client side. + +**[4] `rpc.method.name_original`:** If and only if it's different than `rpc.method.name`. + +**[5] `rpc.response.status_code`:** The following error codes SHOULD be considered errors: - `unknown` - `deadline_exceeded` @@ -193,28 +240,24 @@ If the request has completed successfully, instrumentations SHOULD NOT set - `unavailable` - `data_loss` -**[4] `server.port`:** if the port is supported by the network transport used for communication. +**[6] `server.port`:** if the port is supported by the network transport used for communication. -**[5] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[6] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. +**[8] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. -**[7] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. +**[9] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. -**[8] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[10] `network.protocol.name`:** The value SHOULD be normalized to lowercase. -**[9] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. +**[11] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[10] `network.transport`:** The value SHOULD be normalized to lowercase. +**[12] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[11] `rpc.method`:** 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.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - -**[12] `rpc.service`:** 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.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub class on the client side. - **[13] `rpc.request.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. @@ -230,8 +273,7 @@ the `rpc.response.metadata.my-custom-key` attribute with value `["attribute_valu The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* [`rpc.method`](/docs/registry/attributes/rpc.md) -* [`rpc.service`](/docs/registry/attributes/rpc.md) +* [`rpc.method.name`](/docs/registry/attributes/rpc.md) * [`server.address`](/docs/registry/attributes/server.md) * [`server.port`](/docs/registry/attributes/server.md) diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md index 245e5e6b65..539c529a0a 100644 --- a/docs/rpc/grpc.md +++ b/docs/rpc/grpc.md @@ -35,11 +35,11 @@ for the details on which values classify as errors. | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | This is the logical name of the method from the RPC interface perspective. [1] | `exampleMethod` | +| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The fully-qualified logical name of the method from the RPC interface perspective. [1] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | | [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The string representation of the [status code](https://github.com/grpc/grpc/blob/v1.75.0/doc/statuscodes.md) returned by the server or generated by the client. [2] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The full (logical) name of the service being called, including its package name, if applicable. [3] | `myservice.EchoService` | -| [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | -| [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [5] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | +| [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | +| [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [4] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | +| [`rpc.method.name_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [5] | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | | [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [6] | int | Server port number. [7] | `80`; `8080`; `443` | | [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | @@ -49,15 +49,35 @@ for the details on which values classify as errors. | [`rpc.request.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [11] | `["1.2.3.4", "1.2.3.5"]` | | [`rpc.response.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [12] | `["attribute_value"]` | -**[1] `rpc.method`:** 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.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. +**[1] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. -**[2] `rpc.response.status_code`:** All status codes except `OK` SHOULD be considered errors. +Some RPC frameworks or libraries provide a fixed set of recognized methods +for client stubs and server implementations. Instrumentations for such +frameworks MUST set this attribute to the original method name only +when the method is recognized by the framework or library. + +When the method is not recognized, for example, when the server receives +a request for a method that is not predefined on the server, or when +instrumentation is not able to reliably detect if the method is predefined, +the attribute MUST be set to `_OTHER`. In such cases, tracing +instrumentations MUST also set `rpc.method.name_original` attribute to +the original method value. + +If the RPC instrumentation could end up converting valid RPC methods to +`_OTHER`, then it SHOULD provide a way to configure the list of recognized +RPC methods. -**[3] `rpc.service`:** 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.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub class on the client side. +The `rpc.method.name` can be different from the name of any implementing +method/function. +The `code.function.name` attribute may be used to record the fully-qualified +method actually executing the call on the server side, or the +RPC client stub method on the client side. -**[4] `server.address`:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. +**[2] `rpc.response.status_code`:** All status codes except `OK` SHOULD be considered errors. + +**[3] `server.address`:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. -**[5] `error.type`:** If the RPC fails with an error before status code is returned, +**[4] `error.type`:** If the RPC fails with an error before status code is returned, `error.type` SHOULD be set to the exception type (its fully-qualified class name, if applicable) or a component-specific, low cardinality error identifier. @@ -71,6 +91,8 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. +**[5] `rpc.method.name_original`:** If and only if it's different than `rpc.method.name`. + **[6] `server.port`:** if the port is supported by the network transport used for communication. **[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. @@ -100,8 +122,7 @@ the `rpc.response.metadata.my-custom-key` attribute with value `["attribute_valu The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* [`rpc.method`](/docs/registry/attributes/rpc.md) -* [`rpc.service`](/docs/registry/attributes/rpc.md) +* [`rpc.method.name`](/docs/registry/attributes/rpc.md) * [`server.address`](/docs/registry/attributes/server.md) * [`server.port`](/docs/registry/attributes/server.md) @@ -154,23 +175,47 @@ for the details on which values classify as errors. | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The string representation of the [status code](https://github.com/grpc/grpc/blob/v1.75.0/doc/statuscodes.md) returned by the server. [1] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | -| [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [4] | int | Server port number. [5] | `80`; `8080`; `443` | -| [`client.address`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [6] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | -| [`client.port`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | Client port number. [7] | `65123` | +| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The fully-qualified logical name of the method from the RPC interface perspective. [1] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The string representation of the [status code](https://github.com/grpc/grpc/blob/v1.75.0/doc/statuscodes.md) returned by the server. [2] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | +| [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | +| [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [4] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | +| [`rpc.method.name_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [5] | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | +| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [6] | int | Server port number. [7] | `80`; `8080`; `443` | +| [`client.address`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [8] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | +| [`client.port`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | Client port number. [9] | `65123` | | [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [8] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [9] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [10] | `tcp`; `udp` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | This is the logical name of the method from the RPC interface perspective. [11] | `exampleMethod` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The full (logical) name of the service being called, including its package name, if applicable. [12] | `myservice.EchoService` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [10] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [11] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [12] | `tcp`; `udp` | | [`rpc.request.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [13] | `["1.2.3.4", "1.2.3.5"]` | | [`rpc.response.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [14] | `["attribute_value"]` | -**[1] `rpc.response.status_code`:** The following status codes SHOULD be considered errors: +**[1] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. + +Some RPC frameworks or libraries provide a fixed set of recognized methods +for client stubs and server implementations. Instrumentations for such +frameworks MUST set this attribute to the original method name only +when the method is recognized by the framework or library. + +When the method is not recognized, for example, when the server receives +a request for a method that is not predefined on the server, or when +instrumentation is not able to reliably detect if the method is predefined, +the attribute MUST be set to `_OTHER`. In such cases, tracing +instrumentations MUST also set `rpc.method.name_original` attribute to +the original method value. + +If the RPC instrumentation could end up converting valid RPC methods to +`_OTHER`, then it SHOULD provide a way to configure the list of recognized +RPC methods. + +The `rpc.method.name` can be different from the name of any implementing +method/function. +The `code.function.name` attribute may be used to record the fully-qualified +method actually executing the call on the server side, or the +RPC client stub method on the client side. + +**[2] `rpc.response.status_code`:** The following status codes SHOULD be considered errors: - `UNKNOWN` - `DEADLINE_EXCEEDED` @@ -179,9 +224,9 @@ for the details on which values classify as errors. - `UNAVAILABLE` - `DATA_LOSS` -**[2] `server.address`:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. +**[3] `server.address`:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. -**[3] `error.type`:** If the RPC fails with an error before status code is returned, +**[4] `error.type`:** If the RPC fails with an error before status code is returned, `error.type` SHOULD be set to the exception type (its fully-qualified class name, if applicable) or a component-specific, low cardinality error identifier. @@ -195,28 +240,26 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[4] `server.port`:** if the port is supported by the network transport used for communication. +**[5] `rpc.method.name_original`:** If and only if it's different than `rpc.method.name`. -**[5] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[6] `server.port`:** if the port is supported by the network transport used for communication. -**[6] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. +**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[7] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. +**[8] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. -**[8] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[9] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. -**[9] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. +**[10] `network.protocol.name`:** The value SHOULD be normalized to lowercase. -**[10] `network.transport`:** The value SHOULD be normalized to lowercase. +**[11] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. + +**[12] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[11] `rpc.method`:** 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.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - -**[12] `rpc.service`:** 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.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub class on the client side. - **[13] `rpc.request.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. @@ -232,8 +275,7 @@ the `rpc.response.metadata.my-custom-key` attribute with value `["attribute_valu The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* [`rpc.method`](/docs/registry/attributes/rpc.md) -* [`rpc.service`](/docs/registry/attributes/rpc.md) +* [`rpc.method.name`](/docs/registry/attributes/rpc.md) * [`server.address`](/docs/registry/attributes/server.md) * [`server.port`](/docs/registry/attributes/server.md) diff --git a/docs/rpc/json-rpc.md b/docs/rpc/json-rpc.md index 5dd6ae0d23..f42f0b076d 100644 --- a/docs/rpc/json-rpc.md +++ b/docs/rpc/json-rpc.md @@ -36,10 +36,10 @@ are considered errors. | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | This is the logical name of the method from the RPC interface perspective. [1] | `exampleMethod` | -| [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | -| [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | +| [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | +| [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | | [`jsonrpc.protocol.version`](/docs/registry/attributes/jsonrpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If other than the default version (`1.0`) | string | Protocol version, as specified in the `jsonrpc` property of the request and its corresponding response. | `2.0`; `1.0` | +| [`rpc.method.name_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [3] | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | | [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` when available | string | The [`error.code`](https://www.jsonrpc.org/specification#error_object) property of response if it is an error response recorded as a string. [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | | [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [5] | int | Server port number. [6] | `80`; `8080`; `443` | | [`jsonrpc.request.id`](/docs/registry/attributes/jsonrpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | A string representation of the `id` property of the request and its corresponding response. [7] | `10`; `request-7` | @@ -48,12 +48,11 @@ are considered errors. | [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [8] | `http` | | [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [9] | `1.1`; `2` | | [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [10] | `tcp`; `udp` | +| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | JSON-RPC method name provided in the request. [11] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | -**[1] `rpc.method`:** 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.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. +**[1] `server.address`:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. -**[2] `server.address`:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. - -**[3] `error.type`:** If the RPC fails with an error before status code is returned, +**[2] `error.type`:** If the RPC fails with an error before status code is returned, `error.type` SHOULD be set to the exception type (its fully-qualified class name, if applicable) or a component-specific, low cardinality error identifier. @@ -67,6 +66,8 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. +**[3] `rpc.method.name_original`:** If and only if it's different than `rpc.method.name`. + **[4] `rpc.response.status_code`:** All JSON RPC error codes SHOULD be considered errors. **[5] `server.port`:** if the port is supported by the network transport used for communication. @@ -86,10 +87,13 @@ Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. +**[11] `rpc.method.name`:** JSON-RPC supports sending and receiving arbitrary method names without prior registration or definition. As a result, the method name MAY have unbounded cardinality in edge or error cases. +General-purpose JSON-RPC instrumentations therefore SHOULD NOT set this attribute by default and SHOULD provide a way to configure the list of recognized RPC methods. When tracing instrumentation converts RPC method to `_OTHER`, it MUST also set `rpc.method.name_original` span attribute to the original value. + The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* [`rpc.method`](/docs/registry/attributes/rpc.md) +* [`rpc.method.name`](/docs/registry/attributes/rpc.md) * [`server.address`](/docs/registry/attributes/server.md) * [`server.port`](/docs/registry/attributes/server.md) @@ -143,10 +147,10 @@ are considered errors. | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | This is the logical name of the method from the RPC interface perspective. [1] | `exampleMethod` | -| [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | -| [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | +| [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | +| [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | | [`jsonrpc.protocol.version`](/docs/registry/attributes/jsonrpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If other than the default version (`1.0`) | string | Protocol version, as specified in the `jsonrpc` property of the request and its corresponding response. | `2.0`; `1.0` | +| [`rpc.method.name_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [3] | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | | [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` when available | string | The [`error.code`](https://www.jsonrpc.org/specification#error_object) property of response recorded as a string. [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | | [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [5] | int | Server port number. [6] | `80`; `8080`; `443` | | [`client.address`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [7] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | @@ -157,12 +161,11 @@ are considered errors. | [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [10] | `http` | | [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [11] | `1.1`; `2` | | [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [12] | `tcp`; `udp` | +| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | JSON-RPC method name provided in the request. [13] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | -**[1] `rpc.method`:** 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.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. +**[1] `server.address`:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. -**[2] `server.address`:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. - -**[3] `error.type`:** If the RPC fails with an error before status code is returned, +**[2] `error.type`:** If the RPC fails with an error before status code is returned, `error.type` SHOULD be set to the exception type (its fully-qualified class name, if applicable) or a component-specific, low cardinality error identifier. @@ -176,6 +179,8 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. +**[3] `rpc.method.name_original`:** If and only if it's different than `rpc.method.name`. + **[4] `rpc.response.status_code`:** All JSON RPC error codes SHOULD be considered errors. **[5] `server.port`:** if the port is supported by the network transport used for communication. @@ -199,10 +204,13 @@ Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. +**[13] `rpc.method.name`:** JSON-RPC supports sending and receiving arbitrary method names without prior registration or definition. As a result, the method name MAY have unbounded cardinality in edge or error cases. +General-purpose JSON-RPC instrumentations therefore SHOULD NOT set this attribute by default and SHOULD provide a way to configure the list of recognized RPC methods. When tracing instrumentation converts RPC method to `_OTHER`, it MUST also set `rpc.method.name_original` span attribute to the original value. + The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* [`rpc.method`](/docs/registry/attributes/rpc.md) +* [`rpc.method.name`](/docs/registry/attributes/rpc.md) * [`server.address`](/docs/registry/attributes/server.md) * [`server.port`](/docs/registry/attributes/server.md) diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index 67f7353433..7ee10ec94f 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -89,12 +89,11 @@ SHOULD be the same as the RPC server span duration. | --- | --- | --- | --- | --- | --- | | [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [3] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [4] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [5] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [6] | `tcp`; `udp` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | This is the logical name of the method from the RPC interface perspective. [7] | `exampleMethod` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The full (logical) name of the service being called, including its package name, if applicable. [8] | `myservice.EchoService` | +| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [5] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [6] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [7] | `tcp`; `udp` | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | int | Server port number. | `80`; `8080`; `443` | @@ -114,23 +113,43 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[3] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. +**[3] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. + +Some RPC frameworks or libraries provide a fixed set of recognized methods +for client stubs and server implementations. Instrumentations for such +frameworks MUST set this attribute to the original method name only +when the method is recognized by the framework or library. + +When the method is not recognized, for example, when the server receives +a request for a method that is not predefined on the server, or when +instrumentation is not able to reliably detect if the method is predefined, +the attribute MUST be set to `_OTHER`. In such cases, tracing +instrumentations MUST also set `rpc.method.name_original` attribute to +the original method value. + +If the RPC instrumentation could end up converting valid RPC methods to +`_OTHER`, then it SHOULD provide a way to configure the list of recognized +RPC methods. + +The `rpc.method.name` can be different from the name of any implementing +method/function. +The `code.function.name` attribute may be used to record the fully-qualified +method actually executing the call on the server side, or the +RPC client stub method on the client side. + +**[4] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. -**[4] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase. -**[5] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. +**[6] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[6] `network.transport`:** The value SHOULD be normalized to lowercase. +**[7] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[7] `rpc.method`:** 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.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - -**[8] `rpc.service`:** 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.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub class on the client side. - --- `error.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. @@ -187,12 +206,11 @@ This metric is [recommended][MetricRecommended]. | --- | --- | --- | --- | --- | --- | | [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [3] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [4] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [5] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [6] | `tcp`; `udp` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | This is the logical name of the method from the RPC interface perspective. [7] | `exampleMethod` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The full (logical) name of the service being called, including its package name, if applicable. [8] | `myservice.EchoService` | +| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [5] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [6] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [7] | `tcp`; `udp` | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | int | Server port number. | `80`; `8080`; `443` | @@ -212,23 +230,43 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[3] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. +**[3] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. + +Some RPC frameworks or libraries provide a fixed set of recognized methods +for client stubs and server implementations. Instrumentations for such +frameworks MUST set this attribute to the original method name only +when the method is recognized by the framework or library. + +When the method is not recognized, for example, when the server receives +a request for a method that is not predefined on the server, or when +instrumentation is not able to reliably detect if the method is predefined, +the attribute MUST be set to `_OTHER`. In such cases, tracing +instrumentations MUST also set `rpc.method.name_original` attribute to +the original method value. + +If the RPC instrumentation could end up converting valid RPC methods to +`_OTHER`, then it SHOULD provide a way to configure the list of recognized +RPC methods. + +The `rpc.method.name` can be different from the name of any implementing +method/function. +The `code.function.name` attribute may be used to record the fully-qualified +method actually executing the call on the server side, or the +RPC client stub method on the client side. + +**[4] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. -**[4] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase. -**[5] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. +**[6] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[6] `network.transport`:** The value SHOULD be normalized to lowercase. +**[7] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[7] `rpc.method`:** 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.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - -**[8] `rpc.service`:** 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.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub class on the client side. - --- `error.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. @@ -285,12 +323,11 @@ This metric is [recommended][MetricRecommended]. | --- | --- | --- | --- | --- | --- | | [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [3] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [4] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [5] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [6] | `tcp`; `udp` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | This is the logical name of the method from the RPC interface perspective. [7] | `exampleMethod` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The full (logical) name of the service being called, including its package name, if applicable. [8] | `myservice.EchoService` | +| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [5] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [6] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [7] | `tcp`; `udp` | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | int | Server port number. | `80`; `8080`; `443` | @@ -310,23 +347,43 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[3] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. +**[3] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. + +Some RPC frameworks or libraries provide a fixed set of recognized methods +for client stubs and server implementations. Instrumentations for such +frameworks MUST set this attribute to the original method name only +when the method is recognized by the framework or library. + +When the method is not recognized, for example, when the server receives +a request for a method that is not predefined on the server, or when +instrumentation is not able to reliably detect if the method is predefined, +the attribute MUST be set to `_OTHER`. In such cases, tracing +instrumentations MUST also set `rpc.method.name_original` attribute to +the original method value. + +If the RPC instrumentation could end up converting valid RPC methods to +`_OTHER`, then it SHOULD provide a way to configure the list of recognized +RPC methods. + +The `rpc.method.name` can be different from the name of any implementing +method/function. +The `code.function.name` attribute may be used to record the fully-qualified +method actually executing the call on the server side, or the +RPC client stub method on the client side. + +**[4] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. -**[4] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase. -**[5] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. +**[6] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[6] `network.transport`:** The value SHOULD be normalized to lowercase. +**[7] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[7] `rpc.method`:** 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.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - -**[8] `rpc.service`:** 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.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub class on the client side. - --- `error.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. @@ -393,13 +450,12 @@ SHOULD be the same as the RPC client span duration. | [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If applicable. | int | Server port number. [5] | `80`; `8080`; `443` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [6] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [7] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [8] | `tcp`; `udp` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | This is the logical name of the method from the RPC interface perspective. [9] | `exampleMethod` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The full (logical) name of the service being called, including its package name, if applicable. [10] | `myservice.EchoService` | +| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [5] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | +| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If applicable. | int | Server port number. [6] | `80`; `8080`; `443` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [7] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [8] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [9] | `tcp`; `udp` | **[1] `rpc.system.name`:** The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. @@ -419,25 +475,45 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[4] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. +**[4] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. + +Some RPC frameworks or libraries provide a fixed set of recognized methods +for client stubs and server implementations. Instrumentations for such +frameworks MUST set this attribute to the original method name only +when the method is recognized by the framework or library. + +When the method is not recognized, for example, when the server receives +a request for a method that is not predefined on the server, or when +instrumentation is not able to reliably detect if the method is predefined, +the attribute MUST be set to `_OTHER`. In such cases, tracing +instrumentations MUST also set `rpc.method.name_original` attribute to +the original method value. + +If the RPC instrumentation could end up converting valid RPC methods to +`_OTHER`, then it SHOULD provide a way to configure the list of recognized +RPC methods. + +The `rpc.method.name` can be different from the name of any implementing +method/function. +The `code.function.name` attribute may be used to record the fully-qualified +method actually executing the call on the server side, or the +RPC client stub method on the client side. + +**[5] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. -**[5] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[6] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[7] `network.protocol.name`:** The value SHOULD be normalized to lowercase. -**[7] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. +**[8] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[8] `network.transport`:** The value SHOULD be normalized to lowercase. +**[9] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[9] `rpc.method`:** 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.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - -**[10] `rpc.service`:** 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.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub class on the client side. - --- `error.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. @@ -495,13 +571,12 @@ This metric is [recommended][MetricRecommended]. | [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If applicable. | int | Server port number. [5] | `80`; `8080`; `443` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [6] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [7] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [8] | `tcp`; `udp` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | This is the logical name of the method from the RPC interface perspective. [9] | `exampleMethod` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The full (logical) name of the service being called, including its package name, if applicable. [10] | `myservice.EchoService` | +| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [5] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | +| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If applicable. | int | Server port number. [6] | `80`; `8080`; `443` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [7] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [8] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [9] | `tcp`; `udp` | **[1] `rpc.system.name`:** The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. @@ -521,25 +596,45 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[4] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. +**[4] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. + +Some RPC frameworks or libraries provide a fixed set of recognized methods +for client stubs and server implementations. Instrumentations for such +frameworks MUST set this attribute to the original method name only +when the method is recognized by the framework or library. + +When the method is not recognized, for example, when the server receives +a request for a method that is not predefined on the server, or when +instrumentation is not able to reliably detect if the method is predefined, +the attribute MUST be set to `_OTHER`. In such cases, tracing +instrumentations MUST also set `rpc.method.name_original` attribute to +the original method value. + +If the RPC instrumentation could end up converting valid RPC methods to +`_OTHER`, then it SHOULD provide a way to configure the list of recognized +RPC methods. + +The `rpc.method.name` can be different from the name of any implementing +method/function. +The `code.function.name` attribute may be used to record the fully-qualified +method actually executing the call on the server side, or the +RPC client stub method on the client side. + +**[5] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. -**[5] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[6] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[7] `network.protocol.name`:** The value SHOULD be normalized to lowercase. -**[7] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. +**[8] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[8] `network.transport`:** The value SHOULD be normalized to lowercase. +**[9] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[9] `rpc.method`:** 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.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - -**[10] `rpc.service`:** 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.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub class on the client side. - --- `error.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. @@ -597,13 +692,12 @@ This metric is [recommended][MetricRecommended]. | [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If applicable. | int | Server port number. [5] | `80`; `8080`; `443` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [6] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [7] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [8] | `tcp`; `udp` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | This is the logical name of the method from the RPC interface perspective. [9] | `exampleMethod` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The full (logical) name of the service being called, including its package name, if applicable. [10] | `myservice.EchoService` | +| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [5] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | +| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If applicable. | int | Server port number. [6] | `80`; `8080`; `443` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [7] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [8] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [9] | `tcp`; `udp` | **[1] `rpc.system.name`:** The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. @@ -623,25 +717,45 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[4] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. +**[4] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. + +Some RPC frameworks or libraries provide a fixed set of recognized methods +for client stubs and server implementations. Instrumentations for such +frameworks MUST set this attribute to the original method name only +when the method is recognized by the framework or library. + +When the method is not recognized, for example, when the server receives +a request for a method that is not predefined on the server, or when +instrumentation is not able to reliably detect if the method is predefined, +the attribute MUST be set to `_OTHER`. In such cases, tracing +instrumentations MUST also set `rpc.method.name_original` attribute to +the original method value. + +If the RPC instrumentation could end up converting valid RPC methods to +`_OTHER`, then it SHOULD provide a way to configure the list of recognized +RPC methods. + +The `rpc.method.name` can be different from the name of any implementing +method/function. +The `code.function.name` attribute may be used to record the fully-qualified +method actually executing the call on the server side, or the +RPC client stub method on the client side. + +**[5] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. -**[5] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[6] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[7] `network.protocol.name`:** The value SHOULD be normalized to lowercase. -**[7] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. +**[8] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[8] `network.transport`:** The value SHOULD be normalized to lowercase. +**[9] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[9] `rpc.method`:** 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.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - -**[10] `rpc.service`:** 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.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub class on the client side. - --- `error.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/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index c7d7b9331d..904cfc0432 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -13,7 +13,6 @@ This document defines how to describe remote procedure calls - [Common remote procedure call conventions](#common-remote-procedure-call-conventions) - [Span name](#span-name) - - [Service name](#service-name) - [RPC client span](#rpc-client-span) - [RPC server span](#rpc-server-span) - [Events](#events) @@ -52,37 +51,15 @@ This document defines how to describe remote procedure calls ### Span name -The *span name* MUST be the full RPC method name formatted as: +RPC spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.51.0/specification/trace/api.md#span). -``` -$package.$service/$method -``` +RPC span names SHOULD be `{rpc.method.name}` if there is `rpc.method.name` +available and it's not set to `_OTHER`. +In other cases (when `{rpc.method.name}` is set to `_OTHER` or is not available), +span name span name SHOULD be `{rpc.system.name}`. -(where $service MUST NOT contain dots and $method MUST NOT contain slashes) - -If there is no package name or if it is unknown, the `$package.` part (including the period) is omitted. - -Examples of span names: - -- `grpc.test.EchoService/Echo` -- `com.example.ExampleRmiService/exampleMethod` -- `MyCalcService.Calculator/Add` reported by the server and - `MyServiceReference.ICalculator/Add` reported by the client for .NET WCF calls -- `MyServiceWithNoPackage/theMethod` - -### Service name - -On the server process receiving and handling the remote procedure call, the service name provided in `rpc.service` does not necessarily have to match the [`service.name`][] resource attribute. -One process can expose multiple RPC endpoints and thus have multiple RPC service names. From a deployment perspective, as expressed by the `service.*` resource attributes, it will be treated as one deployed service with one `service.name`. -Likewise, on clients sending RPC requests to a server, the service name provided in `rpc.service` does not have to match the [`peer.service`][] span attribute. - -As an example, given a process deployed as `QuoteService`, this would be the name that goes into the `service.name` resource attribute which applies to the entire process. -This process could expose two RPC endpoints, one called `CurrencyQuotes` (= `rpc.service`) with a method called `getMeanRate` (= `rpc.method`) and the other endpoint called `StockQuotes` (= `rpc.service`) with two methods `getCurrentBid` and `getLastClose` (= `rpc.method`). -In this example, spans representing client request should have their `peer.service` attribute set to `QuoteService` as well to match the server's `service.name` resource attribute. -Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service name. - -[`service.name`]: /docs/resource/README.md#service -[`peer.service`]: /docs/general/attributes.md#general-remote-service-attributes +Semantic conventions for individual RPC systems MAY specify different span name +format. ### RPC client span @@ -119,15 +96,15 @@ document for details on how to record span status. | [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [5] | int | Server port number. [6] | `80`; `8080`; `443` | +| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.method.name_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [5] | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | +| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [6] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | +| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [7] | int | Server port number. [8] | `80`; `8080`; `443` | | [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [7] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [8] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [9] | `tcp`; `udp` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | This is the logical name of the method from the RPC interface perspective. [10] | `exampleMethod` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The full (logical) name of the service being called, including its package name, if applicable. [11] | `myservice.EchoService` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [9] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [10] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [11] | `tcp`; `udp` | **[1] `rpc.system.name`:** The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. @@ -147,32 +124,53 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[4] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. +**[4] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. + +Some RPC frameworks or libraries provide a fixed set of recognized methods +for client stubs and server implementations. Instrumentations for such +frameworks MUST set this attribute to the original method name only +when the method is recognized by the framework or library. + +When the method is not recognized, for example, when the server receives +a request for a method that is not predefined on the server, or when +instrumentation is not able to reliably detect if the method is predefined, +the attribute MUST be set to `_OTHER`. In such cases, tracing +instrumentations MUST also set `rpc.method.name_original` attribute to +the original method value. + +If the RPC instrumentation could end up converting valid RPC methods to +`_OTHER`, then it SHOULD provide a way to configure the list of recognized +RPC methods. + +The `rpc.method.name` can be different from the name of any implementing +method/function. +The `code.function.name` attribute may be used to record the fully-qualified +method actually executing the call on the server side, or the +RPC client stub method on the client side. + +**[5] `rpc.method.name_original`:** If and only if it's different than `rpc.method.name`. + +**[6] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. -**[5] `server.port`:** if the port is supported by the network transport used for communication. +**[7] `server.port`:** if the port is supported by the network transport used for communication. -**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[7] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[9] `network.protocol.name`:** The value SHOULD be normalized to lowercase. -**[8] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. +**[10] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[9] `network.transport`:** The value SHOULD be normalized to lowercase. +**[11] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[10] `rpc.method`:** 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.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - -**[11] `rpc.service`:** 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.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub class on the client side. - The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* [`rpc.method`](/docs/registry/attributes/rpc.md) -* [`rpc.service`](/docs/registry/attributes/rpc.md) +* [`rpc.method.name`](/docs/registry/attributes/rpc.md) * [`rpc.system.name`](/docs/registry/attributes/rpc.md) * [`server.address`](/docs/registry/attributes/server.md) * [`server.port`](/docs/registry/attributes/server.md) @@ -244,17 +242,17 @@ document for details on how to record span status. | [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [5] | int | Server port number. [6] | `80`; `8080`; `443` | -| [`client.address`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [7] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | -| [`client.port`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | Client port number. [8] | `65123` | +| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.method.name_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [5] | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | +| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [6] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | +| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [7] | int | Server port number. [8] | `80`; `8080`; `443` | +| [`client.address`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [9] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | +| [`client.port`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | Client port number. [10] | `65123` | | [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [9] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [10] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [11] | `tcp`; `udp` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | This is the logical name of the method from the RPC interface perspective. [12] | `exampleMethod` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The full (logical) name of the service being called, including its package name, if applicable. [13] | `myservice.EchoService` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [11] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [12] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [13] | `tcp`; `udp` | **[1] `rpc.system.name`:** The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. @@ -274,36 +272,57 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[4] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. +**[4] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. + +Some RPC frameworks or libraries provide a fixed set of recognized methods +for client stubs and server implementations. Instrumentations for such +frameworks MUST set this attribute to the original method name only +when the method is recognized by the framework or library. + +When the method is not recognized, for example, when the server receives +a request for a method that is not predefined on the server, or when +instrumentation is not able to reliably detect if the method is predefined, +the attribute MUST be set to `_OTHER`. In such cases, tracing +instrumentations MUST also set `rpc.method.name_original` attribute to +the original method value. + +If the RPC instrumentation could end up converting valid RPC methods to +`_OTHER`, then it SHOULD provide a way to configure the list of recognized +RPC methods. + +The `rpc.method.name` can be different from the name of any implementing +method/function. +The `code.function.name` attribute may be used to record the fully-qualified +method actually executing the call on the server side, or the +RPC client stub method on the client side. + +**[5] `rpc.method.name_original`:** If and only if it's different than `rpc.method.name`. + +**[6] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. -**[5] `server.port`:** if the port is supported by the network transport used for communication. +**[7] `server.port`:** if the port is supported by the network transport used for communication. -**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[7] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. +**[9] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. -**[8] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. +**[10] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. -**[9] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[11] `network.protocol.name`:** The value SHOULD be normalized to lowercase. -**[10] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. +**[12] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[11] `network.transport`:** The value SHOULD be normalized to lowercase. +**[13] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[12] `rpc.method`:** 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.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - -**[13] `rpc.service`:** 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.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub class on the client side. - The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* [`rpc.method`](/docs/registry/attributes/rpc.md) -* [`rpc.service`](/docs/registry/attributes/rpc.md) +* [`rpc.method.name`](/docs/registry/attributes/rpc.md) * [`rpc.system.name`](/docs/registry/attributes/rpc.md) * [`server.address`](/docs/registry/attributes/server.md) * [`server.port`](/docs/registry/attributes/server.md) diff --git a/model/rpc/common.yaml b/model/rpc/common.yaml index 2d34805920..84cd31feda 100644 --- a/model/rpc/common.yaml +++ b/model/rpc/common.yaml @@ -3,8 +3,7 @@ groups: type: attribute_group brief: 'Common attributes for RPC spans and metrics.' attributes: - - ref: rpc.method - requirement_level: recommended + - ref: rpc.method.name - ref: server.address requirement_level: required brief: > diff --git a/model/rpc/deprecated/registry-deprecated.yaml b/model/rpc/deprecated/registry-deprecated.yaml index 8b19c6cb49..5f196be6cc 100644 --- a/model/rpc/deprecated/registry-deprecated.yaml +++ b/model/rpc/deprecated/registry-deprecated.yaml @@ -275,3 +275,23 @@ groups: renamed_to: "jsonrpc.protocol.version" brief: 'Deprecated, use `jsonrpc.protocol.version` instead.' examples: ['2.0', '1.0'] + - id: rpc.service + type: string + stability: development + brief: 'Deprecated, usefully-qualified `rpc.method.name` instead.' + examples: "myservice.EchoService" + deprecated: + reason: uncategorized + note: 'Value should be included in `rpc.method.name` which is expected + to be a fully-qualified name.' + - id: rpc.method + type: string + stability: development + brief: 'Deprecated, use fully-qualified `rpc.method.name` instead.' + examples: "exampleMethod" + deprecated: + reason: uncategorized + note: 'Value should be included in `rpc.method.name` which is expected + to be a fully-qualified name.' + + diff --git a/model/rpc/metrics.yaml b/model/rpc/metrics.yaml index f1d1d6c928..5f5375da7f 100644 --- a/model/rpc/metrics.yaml +++ b/model/rpc/metrics.yaml @@ -6,12 +6,15 @@ groups: attributes: - ref: rpc.system.name requirement_level: required - - ref: rpc.service - ref: server.address requirement_level: required - ref: server.port requirement_level: conditionally_required: If applicable. + - ref: rpc.method.name + requirement_level: + conditionally_required: if available. + - id: attributes.metrics.rpc.server type: attribute_group brief: "Describes RPC metric attributes." @@ -25,6 +28,10 @@ groups: - ref: server.port note: "" requirement_level: opt_in + - ref: rpc.method.name + requirement_level: + conditionally_required: if available. + # RPC Server metrics - id: metric.rpc.server.call.duration type: metric diff --git a/model/rpc/registry.yaml b/model/rpc/registry.yaml index 6b1f5683d5..c411dc4749 100644 --- a/model/rpc/registry.yaml +++ b/model/rpc/registry.yaml @@ -40,28 +40,48 @@ groups: For example, a property `my-custom-key` with value `["attribute_value"]` SHOULD be recorded as the `rpc.response.metadata.my-custom-key` attribute with value `["attribute_value"]` examples: [["attribute_value"]] - - id: rpc.method + - id: rpc.method.name type: string stability: development - brief: This is the logical name of the method from the RPC interface perspective. - examples: "exampleMethod" - note: > - 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. + brief: The fully-qualified logical name of the method from the RPC + interface perspective. + examples: + - "com.example.ExampleService/exampleMethod" + - "EchoService/Echo" + - "_OTHER" + note: | + The method name MAY have unbounded cardinality in edge or error cases. + + Some RPC frameworks or libraries provide a fixed set of recognized methods + for client stubs and server implementations. Instrumentations for such + frameworks MUST set this attribute to the original method name only + when the method is recognized by the framework or library. + + When the method is not recognized, for example, when the server receives + a request for a method that is not predefined on the server, or when + instrumentation is not able to reliably detect if the method is predefined, + the attribute MUST be set to `_OTHER`. In such cases, tracing + instrumentations MUST also set `rpc.method.name_original` attribute to + the original method value. + + If the RPC instrumentation could end up converting valid RPC methods to + `_OTHER`, then it SHOULD provide a way to configure the list of recognized + RPC methods. + + The `rpc.method.name` can be different from the name of any implementing + method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - - id: rpc.service + - id: rpc.method.name_original type: string stability: development - brief: 'The full (logical) name of the service being called, including its package name, if applicable.' - examples: "myservice.EchoService" - note: > - 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.function.name` attribute may be used to record the fully-qualified - method actually executing the call on the server side, or the - RPC client stub class on the client side. + brief: > + The original name of the method used by the client. + examples: + - "com.myservice.EchoService/catchAll" + - "com.myservice.EchoService/unknownMethod" + - "InvalidMethod" - id: rpc.system.name brief: 'The Remote Procedure Call (RPC) system.' note: > diff --git a/model/rpc/spans.yaml b/model/rpc/spans.yaml index e3fdc8f172..10b72b770c 100644 --- a/model/rpc/spans.yaml +++ b/model/rpc/spans.yaml @@ -5,8 +5,6 @@ groups: brief: 'This document defines semantic conventions for remote procedure calls.' extends: common.rpc.attributes attributes: - - ref: rpc.method - sampling_relevant: true - ref: server.address sampling_relevant: true - ref: server.port @@ -16,6 +14,13 @@ groups: - ref: network.peer.port requirement_level: recommended: If `network.peer.address` is set. + - ref: rpc.method.name + requirement_level: + conditionally_required: if available. + sampling_relevant: true + - ref: rpc.method.name_original + requirement_level: + conditionally_required: If and only if it's different than `rpc.method.name`. - id: rpc.server type: attribute_group @@ -27,19 +32,6 @@ groups: - ref: client.port requirement_level: recommended - - id: rpc_service.server - type: attribute_group - brief: 'This document defines semantic conventions for remote procedure calls.' - extends: rpc - attributes: - - ref: client.address - requirement_level: recommended - - ref: client.port - requirement_level: recommended - - ref: rpc.service - requirement_level: recommended - sampling_relevant: true - - id: span.rpc.call.client type: span stability: development @@ -68,13 +60,11 @@ groups: - ref: rpc.system.name requirement_level: required sampling_relevant: true - - ref: rpc.service - sampling_relevant: true - id: span.rpc.call.server type: span stability: development - extends: rpc_service.server + extends: rpc.server span_kind: server brief: This span represents an incoming Remote Procedure Call (RPC). events: [rpc.message] @@ -123,13 +113,11 @@ groups: requirement_level: opt_in - ref: rpc.response.metadata requirement_level: opt_in - - ref: rpc.service - sampling_relevant: true - id: span.rpc.connect_rpc.call.server type: span stability: development - extends: rpc_service.server + extends: rpc.server span_kind: server brief: This span represents an incoming Remote Procedure Call (RPC). note: | @@ -177,11 +165,8 @@ groups: extends: rpc span_kind: client attributes: - - ref: rpc.method - requirement_level: required - - ref: rpc.service + - ref: rpc.method.name requirement_level: required - sampling_relevant: true - ref: rpc.response.status_code requirement_level: required brief: > @@ -197,7 +182,7 @@ groups: - id: span.rpc.grpc.call.server type: span stability: development - extends: rpc_service.server + extends: rpc.server span_kind: server brief: This span represents an incoming Remote Procedure Call (RPC). note: | @@ -211,6 +196,8 @@ groups: document for details on how to record span status. See also `rpc.response.status_code` attribute for the details on which values classify as errors. attributes: + - ref: rpc.method.name + requirement_level: required - ref: rpc.response.status_code requirement_level: required brief: > @@ -249,13 +236,24 @@ groups: extends: rpc span_kind: client attributes: - - ref: rpc.method - requirement_level: required - ref: jsonrpc.protocol.version requirement_level: conditionally_required: If other than the default version (`1.0`) - ref: jsonrpc.request.id requirement_level: recommended + - ref: rpc.method.name + brief: JSON-RPC method name provided in the request. + note: > + JSON-RPC supports sending and receiving arbitrary method names without + prior registration or definition. As a result, the method name MAY have + unbounded cardinality in edge or error cases. + + General-purpose JSON-RPC instrumentations therefore SHOULD NOT set this + attribute by default and SHOULD provide a way to configure the list of + recognized RPC methods. + When tracing instrumentation converts RPC method to `_OTHER`, it MUST + also set `rpc.method.name_original` span attribute to the original value. + requirement_level: opt_in - ref: rpc.response.status_code brief: > The [`error.code`](https://www.jsonrpc.org/specification#error_object) @@ -283,13 +281,24 @@ groups: an [`error` object](https://www.jsonrpc.org/specification#error_object) are considered errors. attributes: - - ref: rpc.method - requirement_level: required - ref: jsonrpc.protocol.version requirement_level: conditionally_required: If other than the default version (`1.0`) - ref: jsonrpc.request.id requirement_level: recommended + - ref: rpc.method.name + brief: JSON-RPC method name provided in the request. + note: > + JSON-RPC supports sending and receiving arbitrary method names without + prior registration or definition. As a result, the method name MAY have + unbounded cardinality in edge or error cases. + + General-purpose JSON-RPC instrumentations therefore SHOULD NOT set this + attribute by default and SHOULD provide a way to configure the list of + recognized RPC methods. + When tracing instrumentation converts RPC method to `_OTHER`, it MUST + also set `rpc.method.name_original` span attribute to the original value. + requirement_level: opt_in - ref: rpc.response.status_code brief: > The [`error.code`](https://www.jsonrpc.org/specification#error_object) property of From f58c8f44535615cbe59684f5788c00320716c8ea Mon Sep 17 00:00:00 2001 From: liudmila molkova Date: Tue, 16 Dec 2025 14:29:56 -0800 Subject: [PATCH 2/9] up --- docs/rpc/grpc.md | 60 +++++++++---------- model/rpc/deprecated/registry-deprecated.yaml | 2 - model/rpc/spans.yaml | 2 - 3 files changed, 30 insertions(+), 34 deletions(-) diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md index 539c529a0a..f57fb0b37b 100644 --- a/docs/rpc/grpc.md +++ b/docs/rpc/grpc.md @@ -175,10 +175,10 @@ for the details on which values classify as errors. | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | -| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The fully-qualified logical name of the method from the RPC interface perspective. [1] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The string representation of the [status code](https://github.com/grpc/grpc/blob/v1.75.0/doc/statuscodes.md) returned by the server. [2] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | -| [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [4] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | +| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The string representation of the [status code](https://github.com/grpc/grpc/blob/v1.75.0/doc/statuscodes.md) returned by the server. [1] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | +| [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | +| [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | +| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | | [`rpc.method.name_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [5] | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | | [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [6] | int | Server port number. [7] | `80`; `8080`; `443` | | [`client.address`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [8] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | @@ -191,7 +191,32 @@ for the details on which values classify as errors. | [`rpc.request.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [13] | `["1.2.3.4", "1.2.3.5"]` | | [`rpc.response.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [14] | `["attribute_value"]` | -**[1] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. +**[1] `rpc.response.status_code`:** The following status codes SHOULD be considered errors: + +- `UNKNOWN` +- `DEADLINE_EXCEEDED` +- `UNIMPLEMENTED` +- `INTERNAL` +- `UNAVAILABLE` +- `DATA_LOSS` + +**[2] `server.address`:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + +**[3] `error.type`:** If the RPC fails with an error before status code is returned, +`error.type` SHOULD be set to the exception type (its fully-qualified class name, if applicable) +or a component-specific, low cardinality error identifier. + +If a response status code is returned and status indicates an error, +`error.type` SHOULD be set to that status code. Check system-specific conventions +for the details on which values of `rpc.response.status_code` are considered errors. + +The `error.type` value SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +If the request has completed successfully, instrumentations SHOULD NOT set +`error.type`. + +**[4] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such @@ -215,31 +240,6 @@ The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. -**[2] `rpc.response.status_code`:** The following status codes SHOULD be considered errors: - -- `UNKNOWN` -- `DEADLINE_EXCEEDED` -- `UNIMPLEMENTED` -- `INTERNAL` -- `UNAVAILABLE` -- `DATA_LOSS` - -**[3] `server.address`:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. - -**[4] `error.type`:** If the RPC fails with an error before status code is returned, -`error.type` SHOULD be set to the exception type (its fully-qualified class name, if applicable) -or a component-specific, low cardinality error identifier. - -If a response status code is returned and status indicates an error, -`error.type` SHOULD be set to that status code. Check system-specific conventions -for the details on which values of `rpc.response.status_code` are considered errors. - -The `error.type` value SHOULD be predictable and SHOULD have low cardinality. -Instrumentations SHOULD document the list of errors they report. - -If the request has completed successfully, instrumentations SHOULD NOT set -`error.type`. - **[5] `rpc.method.name_original`:** If and only if it's different than `rpc.method.name`. **[6] `server.port`:** if the port is supported by the network transport used for communication. diff --git a/model/rpc/deprecated/registry-deprecated.yaml b/model/rpc/deprecated/registry-deprecated.yaml index 5f196be6cc..f6454b249a 100644 --- a/model/rpc/deprecated/registry-deprecated.yaml +++ b/model/rpc/deprecated/registry-deprecated.yaml @@ -293,5 +293,3 @@ groups: reason: uncategorized note: 'Value should be included in `rpc.method.name` which is expected to be a fully-qualified name.' - - diff --git a/model/rpc/spans.yaml b/model/rpc/spans.yaml index 10b72b770c..f6446f8368 100644 --- a/model/rpc/spans.yaml +++ b/model/rpc/spans.yaml @@ -196,8 +196,6 @@ groups: document for details on how to record span status. See also `rpc.response.status_code` attribute for the details on which values classify as errors. attributes: - - ref: rpc.method.name - requirement_level: required - ref: rpc.response.status_code requirement_level: required brief: > From 643c7a696824d94636f25e9e71f36c836317e7cd Mon Sep 17 00:00:00 2001 From: liudmila molkova Date: Tue, 16 Dec 2025 14:34:42 -0800 Subject: [PATCH 3/9] changelog --- .chloggen/rpc-method-service.yaml | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .chloggen/rpc-method-service.yaml diff --git a/.chloggen/rpc-method-service.yaml b/.chloggen/rpc-method-service.yaml new file mode 100644 index 0000000000..6f5562235f --- /dev/null +++ b/.chloggen/rpc-method-service.yaml @@ -0,0 +1,5 @@ +change_type: breaking +component: rpc +note: Merge `rpc.method` and `rpc.service` into fully-qualified `rpc.method.name` + attribute, clarify possible high cardinality of `rpc.method.name` in edge cases. +issues: [3196, 3223] \ No newline at end of file From d4327cb034e3811157b9ad1241efd5019ba4aa78 Mon Sep 17 00:00:00 2001 From: liudmila molkova Date: Tue, 16 Dec 2025 14:40:38 -0800 Subject: [PATCH 4/9] up --- .chloggen/rpc-method-service.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.chloggen/rpc-method-service.yaml b/.chloggen/rpc-method-service.yaml index 6f5562235f..ebe537c3a5 100644 --- a/.chloggen/rpc-method-service.yaml +++ b/.chloggen/rpc-method-service.yaml @@ -1,5 +1,6 @@ change_type: breaking component: rpc note: Merge `rpc.method` and `rpc.service` into fully-qualified `rpc.method.name` - attribute, clarify possible high cardinality of `rpc.method.name` in edge cases. -issues: [3196, 3223] \ No newline at end of file + attribute. Clarify how to handle possible high cardinality of `rpc.method.name` + in edge cases. Clarify `rpc.method.name` usage in span names. +issues: [3196, 3223] From 67a799144c4c2c8f64baa4007d3b347244ec3c95 Mon Sep 17 00:00:00 2001 From: liudmila molkova Date: Tue, 16 Dec 2025 14:41:23 -0800 Subject: [PATCH 5/9] up --- .chloggen/rpc-method-service.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.chloggen/rpc-method-service.yaml b/.chloggen/rpc-method-service.yaml index ebe537c3a5..c5067d1ac5 100644 --- a/.chloggen/rpc-method-service.yaml +++ b/.chloggen/rpc-method-service.yaml @@ -3,4 +3,4 @@ component: rpc note: Merge `rpc.method` and `rpc.service` into fully-qualified `rpc.method.name` attribute. Clarify how to handle possible high cardinality of `rpc.method.name` in edge cases. Clarify `rpc.method.name` usage in span names. -issues: [3196, 3223] +issues: [2863, 3196, 3223] From 6f4ab9a7b461cef3753d08fb0106e34bea2c4682 Mon Sep 17 00:00:00 2001 From: liudmila molkova Date: Wed, 17 Dec 2025 14:31:46 -0800 Subject: [PATCH 6/9] typos --- docs/registry/attributes/rpc.md | 2 +- docs/rpc/rpc-spans.md | 2 +- model/rpc/deprecated/registry-deprecated.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/registry/attributes/rpc.md b/docs/registry/attributes/rpc.md index 937f886928..cbd50df21d 100644 --- a/docs/registry/attributes/rpc.md +++ b/docs/registry/attributes/rpc.md @@ -111,7 +111,7 @@ Deprecated rpc message attributes. | `rpc.jsonrpc.request_id` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `jsonrpc.request.id`. | string | Deprecated, use `jsonrpc.request.id` instead. | `10`; `request-7`; `` | | `rpc.jsonrpc.version` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `jsonrpc.protocol.version`. | string | Deprecated, use `jsonrpc.protocol.version` instead. | `2.0`; `1.0` | | `rpc.method` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | string | Deprecated, use fully-qualified `rpc.method.name` instead. | `exampleMethod` | -| `rpc.service` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | string | Deprecated, usefully-qualified `rpc.method.name` instead. | `myservice.EchoService` | +| `rpc.service` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | string | Deprecated, use fully-qualified `rpc.method.name` instead. | `myservice.EchoService` | | `rpc.system` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `rpc.system.name`. | string | Deprecated, use `rpc.system.name` attribute instead. | `grpc`; `java_rmi`; `dotnet_wcf` | --- diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 904cfc0432..eb603d90d5 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -56,7 +56,7 @@ RPC spans MUST follow the overall [guidelines for span names](https://github.com RPC span names SHOULD be `{rpc.method.name}` if there is `rpc.method.name` available and it's not set to `_OTHER`. In other cases (when `{rpc.method.name}` is set to `_OTHER` or is not available), -span name span name SHOULD be `{rpc.system.name}`. +span name SHOULD be `{rpc.system.name}`. Semantic conventions for individual RPC systems MAY specify different span name format. diff --git a/model/rpc/deprecated/registry-deprecated.yaml b/model/rpc/deprecated/registry-deprecated.yaml index f6454b249a..2d1e005c81 100644 --- a/model/rpc/deprecated/registry-deprecated.yaml +++ b/model/rpc/deprecated/registry-deprecated.yaml @@ -278,7 +278,7 @@ groups: - id: rpc.service type: string stability: development - brief: 'Deprecated, usefully-qualified `rpc.method.name` instead.' + brief: 'Deprecated, use fully-qualified `rpc.method.name` instead.' examples: "myservice.EchoService" deprecated: reason: uncategorized From 7283135852f5f8d2f25ae3cb02c86d149ae88688 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 29 Dec 2025 12:18:52 -0800 Subject: [PATCH 7/9] Update docs/rpc/rpc-spans.md Co-authored-by: Matthew Hensley <130569+matt-hensley@users.noreply.github.com> --- docs/rpc/rpc-spans.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index eb603d90d5..873ceab209 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -53,10 +53,11 @@ This document defines how to describe remote procedure calls RPC spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.51.0/specification/trace/api.md#span). -RPC span names SHOULD be `{rpc.method.name}` if there is `rpc.method.name` -available and it's not set to `_OTHER`. -In other cases (when `{rpc.method.name}` is set to `_OTHER` or is not available), -span name SHOULD be `{rpc.system.name}`. +The *span name* SHOULD be `{rpc.method.name}` if it is +available and not set to `_OTHER`. + +If `rpc.method.name` is unavailable or set to `_OTHER`, +the span name SHOULD be `{rpc.system.name}`. Semantic conventions for individual RPC systems MAY specify different span name format. From b8d10e49f70cd20d0500306c5ec6324246f07cbc Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 29 Dec 2025 12:19:13 -0800 Subject: [PATCH 8/9] back to rpc.method --- .chloggen/rpc-method-service.yaml | 6 +- docs/cloud-providers/aws-sdk.md | 4 +- docs/db/dynamodb.md | 52 +++++----- docs/object-stores/s3.md | 4 +- docs/registry/attributes/rpc.md | 13 ++- docs/rpc/connect-rpc.md | 96 +++++++++---------- docs/rpc/grpc.md | 88 ++++++++--------- docs/rpc/json-rpc.md | 84 ++++++++-------- docs/rpc/rpc-metrics.md | 48 +++++----- docs/rpc/rpc-spans.md | 80 ++++++++-------- model/rpc/common.yaml | 2 +- model/rpc/deprecated/registry-deprecated.yaml | 13 +-- model/rpc/metrics.yaml | 4 +- model/rpc/registry.yaml | 8 +- model/rpc/spans.yaml | 16 ++-- 15 files changed, 246 insertions(+), 272 deletions(-) diff --git a/.chloggen/rpc-method-service.yaml b/.chloggen/rpc-method-service.yaml index c5067d1ac5..ba8ec9e4e1 100644 --- a/.chloggen/rpc-method-service.yaml +++ b/.chloggen/rpc-method-service.yaml @@ -1,6 +1,6 @@ change_type: breaking component: rpc -note: Merge `rpc.method` and `rpc.service` into fully-qualified `rpc.method.name` - attribute. Clarify how to handle possible high cardinality of `rpc.method.name` - in edge cases. Clarify `rpc.method.name` usage in span names. +note: Merge `rpc.method` and `rpc.service` into fully-qualified `rpc.method` + attribute. Clarify how to handle possible high cardinality of `rpc.method` + in edge cases. Clarify `rpc.method` usage in span names. issues: [2863, 3196, 3223] diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md index cee7e2fc32..34e5785fb1 100644 --- a/docs/cloud-providers/aws-sdk.md +++ b/docs/cloud-providers/aws-sdk.md @@ -44,8 +44,8 @@ interesting conventions are found. | [`aws.extended_request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If available. | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). diff --git a/docs/db/dynamodb.md b/docs/db/dynamodb.md index d2f357bc84..7a9f6960e2 100644 --- a/docs/db/dynamodb.md +++ b/docs/db/dynamodb.md @@ -60,8 +60,8 @@ This span represents a `DynamoDB.BatchGetItem` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | The keys in the `RequestItems` object field. | `["Users", "Cats"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -111,8 +111,8 @@ This span represents a `DynamoDB.BatchWriteItem` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | The keys in the `RequestItems` object field. | `["Users", "Cats"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -166,8 +166,8 @@ This span represents a `DynamoDB.CreateTable` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -217,8 +217,8 @@ This span represents a `DynamoDB.DeleteItem` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -266,8 +266,8 @@ This span represents a `DynamoDB.DeleteTable` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -315,8 +315,8 @@ This span represents a `DynamoDB.DescribeTable` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -367,8 +367,8 @@ This span represents a `DynamoDB.GetItem` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -418,8 +418,8 @@ This span represents a `DynamoDB.ListTables` call. | [`aws.dynamodb.table_count`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | The number of items in the `TableNames` response parameter. | `20` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -469,8 +469,8 @@ This span represents a `DynamoDB.PutItem` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | The keys in the `RequestItems` object field. | `["Users", "Cats"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -526,8 +526,8 @@ This span represents a `DynamoDB.Query` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -586,8 +586,8 @@ This span represents a `DynamoDB.Scan` call. | [`aws.dynamodb.total_segments`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | The value of the `TotalSegments` request parameter. | `100` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -637,8 +637,8 @@ This span represents a `DynamoDB.UpdateItem` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). @@ -691,8 +691,8 @@ This span represents a `DynamoDB.UpdateTable` call. | [`aws.dynamodb.table_names`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions). diff --git a/docs/object-stores/s3.md b/docs/object-stores/s3.md index 7a942f3beb..cd288bf0a7 100644 --- a/docs/object-stores/s3.md +++ b/docs/object-stores/s3.md @@ -33,8 +33,8 @@ Semantic Conventions for AWS S3 client spans extend the general [AWS SDK Semanti | [`aws.s3.part_number`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000. [5] | `3456` | | [`aws.s3.upload_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Upload ID that identifies the multipart upload. [6] | `dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ` | | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [7] | `us-east-1`; `us-west-2` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | -| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | +| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | **[1] `aws.s3.bucket`:** The `bucket` attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter. This applies to almost all S3 operations except `list-buckets`. diff --git a/docs/registry/attributes/rpc.md b/docs/registry/attributes/rpc.md index cbd50df21d..3a4d561725 100644 --- a/docs/registry/attributes/rpc.md +++ b/docs/registry/attributes/rpc.md @@ -18,8 +18,8 @@ This document defines attributes for remote procedure calls. | `rpc.message.id` | ![Development](https://img.shields.io/badge/-development-blue) | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | | | `rpc.message.type` | ![Development](https://img.shields.io/badge/-development-blue) | string | Whether this is a received or sent message. | `SENT`; `RECEIVED` | | `rpc.message.uncompressed_size` | ![Development](https://img.shields.io/badge/-development-blue) | int | Uncompressed size of the message in bytes. | | -| `rpc.method.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | The fully-qualified logical name of the method from the RPC interface perspective. [2] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | -| `rpc.method.name_original` | ![Development](https://img.shields.io/badge/-development-blue) | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | +| `rpc.method` | ![Development](https://img.shields.io/badge/-development-blue) | string | The fully-qualified logical name of the method from the RPC interface perspective. [2] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| `rpc.method_original` | ![Development](https://img.shields.io/badge/-development-blue) | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | | `rpc.request.metadata.` | ![Development](https://img.shields.io/badge/-development-blue) | string[] | RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [3] | `["1.2.3.4", "1.2.3.5"]` | | `rpc.response.metadata.` | ![Development](https://img.shields.io/badge/-development-blue) | string[] | RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [4] | `["attribute_value"]` | | `rpc.response.status_code` | ![Development](https://img.shields.io/badge/-development-blue) | string | Status code of the RPC returned by the RPC server or generated by the client [5] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | @@ -27,7 +27,7 @@ This document defines attributes for remote procedure calls. **[1] `rpc.message.id`:** This way we guarantee that the values will be consistent between different implementations. -**[2] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. +**[2] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such @@ -38,14 +38,14 @@ When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. In such cases, tracing -instrumentations MUST also set `rpc.method.name_original` attribute to +instrumentations MUST also set `rpc.method_original` attribute to the original method value. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. -The `rpc.method.name` can be different from the name of any implementing +The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the @@ -110,8 +110,7 @@ Deprecated rpc message attributes. | `rpc.jsonrpc.error_message` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Use the span status description or `error.message` attribute on other signals. | string | Deprecated, use span status description or `error.message` attribute on other signals. | `Parse error`; `User already exists` | | `rpc.jsonrpc.request_id` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `jsonrpc.request.id`. | string | Deprecated, use `jsonrpc.request.id` instead. | `10`; `request-7`; `` | | `rpc.jsonrpc.version` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `jsonrpc.protocol.version`. | string | Deprecated, use `jsonrpc.protocol.version` instead. | `2.0`; `1.0` | -| `rpc.method` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | string | Deprecated, use fully-qualified `rpc.method.name` instead. | `exampleMethod` | -| `rpc.service` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method.name` which is expected to be a fully-qualified name. | string | Deprecated, use fully-qualified `rpc.method.name` instead. | `myservice.EchoService` | +| `rpc.service` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `rpc.method` which is expected to be a fully-qualified name. | string | Deprecated, use fully-qualified `rpc.method` instead. | `myservice.EchoService` | | `rpc.system` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `rpc.system.name`. | string | Deprecated, use `rpc.system.name` attribute instead. | `grpc`; `java_rmi`; `dotnet_wcf` | --- diff --git a/docs/rpc/connect-rpc.md b/docs/rpc/connect-rpc.md index 3620b58a0e..c1fc0edc1f 100644 --- a/docs/rpc/connect-rpc.md +++ b/docs/rpc/connect-rpc.md @@ -36,17 +36,17 @@ document for details on how to record span status. | --- | --- | --- | --- | --- | --- | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | -| [`rpc.method.name_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [4] | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The [error code](https://connectrpc.com//docs/protocol/#error-codes) of the Connect response. [5] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [6] | int | Server port number. [7] | `80`; `8080`; `443` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.method_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If and only if it's different than `rpc.method`. | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | +| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The [error code](https://connectrpc.com//docs/protocol/#error-codes) of the Connect response. [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | +| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [5] | int | Server port number. [6] | `80`; `8080`; `443` | | [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [8] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [9] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [10] | `tcp`; `udp` | -| [`rpc.request.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [11] | `["1.2.3.4", "1.2.3.5"]` | -| [`rpc.response.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [12] | `["attribute_value"]` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [7] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [8] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [9] | `tcp`; `udp` | +| [`rpc.request.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [10] | `["1.2.3.4", "1.2.3.5"]` | +| [`rpc.response.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [11] | `["attribute_value"]` | **[1] `server.address`:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. @@ -64,7 +64,7 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[3] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. +**[3] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such @@ -75,44 +75,42 @@ When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. In such cases, tracing -instrumentations MUST also set `rpc.method.name_original` attribute to +instrumentations MUST also set `rpc.method_original` attribute to the original method value. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. -The `rpc.method.name` can be different from the name of any implementing +The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. -**[4] `rpc.method.name_original`:** If and only if it's different than `rpc.method.name`. +**[4] `rpc.response.status_code`:** All error codes except `OK` SHOULD be considered errors. -**[5] `rpc.response.status_code`:** All error codes except `OK` SHOULD be considered errors. +**[5] `server.port`:** if the port is supported by the network transport used for communication. -**[6] `server.port`:** if the port is supported by the network transport used for communication. +**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[7] `network.protocol.name`:** The value SHOULD be normalized to lowercase. -**[8] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[8] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[9] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. - -**[10] `network.transport`:** The value SHOULD be normalized to lowercase. +**[9] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[11] `rpc.request.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. +**[10] `rpc.request.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. For example, a property `my-custom-key` with value `["1.2.3.4", "1.2.3.5"]` SHOULD be recorded as `rpc.request.metadata.my-custom-key` attribute with value `["1.2.3.4", "1.2.3.5"]` -**[12] `rpc.response.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. +**[11] `rpc.response.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. For example, a property `my-custom-key` with value `["attribute_value"]` SHOULD be recorded as @@ -121,7 +119,7 @@ the `rpc.response.metadata.my-custom-key` attribute with value `["attribute_valu The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* [`rpc.method.name`](/docs/registry/attributes/rpc.md) +* [`rpc.method`](/docs/registry/attributes/rpc.md) * [`server.address`](/docs/registry/attributes/server.md) * [`server.port`](/docs/registry/attributes/server.md) @@ -175,19 +173,19 @@ document for details on how to record span status. | --- | --- | --- | --- | --- | --- | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | -| [`rpc.method.name_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [4] | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The [error code](https://connectrpc.com/docs/protocol/#error-codes) of the Connect response. [5] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [6] | int | Server port number. [7] | `80`; `8080`; `443` | -| [`client.address`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [8] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | -| [`client.port`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | Client port number. [9] | `65123` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.method_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If and only if it's different than `rpc.method`. | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | +| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The [error code](https://connectrpc.com/docs/protocol/#error-codes) of the Connect response. [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | +| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [5] | int | Server port number. [6] | `80`; `8080`; `443` | +| [`client.address`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [7] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | +| [`client.port`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | Client port number. [8] | `65123` | | [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [10] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [11] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [12] | `tcp`; `udp` | -| [`rpc.request.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [13] | `["1.2.3.4", "1.2.3.5"]` | -| [`rpc.response.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [14] | `["attribute_value"]` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [9] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [10] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [11] | `tcp`; `udp` | +| [`rpc.request.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [12] | `["1.2.3.4", "1.2.3.5"]` | +| [`rpc.response.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [13] | `["attribute_value"]` | **[1] `server.address`:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. @@ -205,7 +203,7 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[3] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. +**[3] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such @@ -216,22 +214,20 @@ When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. In such cases, tracing -instrumentations MUST also set `rpc.method.name_original` attribute to +instrumentations MUST also set `rpc.method_original` attribute to the original method value. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. -The `rpc.method.name` can be different from the name of any implementing +The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. -**[4] `rpc.method.name_original`:** If and only if it's different than `rpc.method.name`. - -**[5] `rpc.response.status_code`:** The following error codes SHOULD be considered errors: +**[4] `rpc.response.status_code`:** The following error codes SHOULD be considered errors: - `unknown` - `deadline_exceeded` @@ -240,31 +236,31 @@ RPC client stub method on the client side. - `unavailable` - `data_loss` -**[6] `server.port`:** if the port is supported by the network transport used for communication. +**[5] `server.port`:** if the port is supported by the network transport used for communication. -**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[8] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. +**[7] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. -**[9] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. +**[8] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. -**[10] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[9] `network.protocol.name`:** The value SHOULD be normalized to lowercase. -**[11] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. +**[10] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[12] `network.transport`:** The value SHOULD be normalized to lowercase. +**[11] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[13] `rpc.request.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. +**[12] `rpc.request.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. For example, a property `my-custom-key` with value `["1.2.3.4", "1.2.3.5"]` SHOULD be recorded as `rpc.request.metadata.my-custom-key` attribute with value `["1.2.3.4", "1.2.3.5"]` -**[14] `rpc.response.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. +**[13] `rpc.response.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. For example, a property `my-custom-key` with value `["attribute_value"]` SHOULD be recorded as @@ -273,7 +269,7 @@ the `rpc.response.metadata.my-custom-key` attribute with value `["attribute_valu The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* [`rpc.method.name`](/docs/registry/attributes/rpc.md) +* [`rpc.method`](/docs/registry/attributes/rpc.md) * [`server.address`](/docs/registry/attributes/server.md) * [`server.port`](/docs/registry/attributes/server.md) diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md index f57fb0b37b..f2401dd51e 100644 --- a/docs/rpc/grpc.md +++ b/docs/rpc/grpc.md @@ -35,21 +35,21 @@ for the details on which values classify as errors. | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | -| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The fully-qualified logical name of the method from the RPC interface perspective. [1] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The fully-qualified logical name of the method from the RPC interface perspective. [1] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | | [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The string representation of the [status code](https://github.com/grpc/grpc/blob/v1.75.0/doc/statuscodes.md) returned by the server or generated by the client. [2] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [4] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.method.name_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [5] | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [6] | int | Server port number. [7] | `80`; `8080`; `443` | +| [`rpc.method_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If and only if it's different than `rpc.method`. | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | +| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [5] | int | Server port number. [6] | `80`; `8080`; `443` | | [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [8] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [9] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [10] | `tcp`; `udp` | -| [`rpc.request.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [11] | `["1.2.3.4", "1.2.3.5"]` | -| [`rpc.response.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [12] | `["attribute_value"]` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [7] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [8] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [9] | `tcp`; `udp` | +| [`rpc.request.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [10] | `["1.2.3.4", "1.2.3.5"]` | +| [`rpc.response.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [11] | `["attribute_value"]` | -**[1] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. +**[1] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such @@ -60,14 +60,14 @@ When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. In such cases, tracing -instrumentations MUST also set `rpc.method.name_original` attribute to +instrumentations MUST also set `rpc.method_original` attribute to the original method value. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. -The `rpc.method.name` can be different from the name of any implementing +The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the @@ -91,29 +91,27 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[5] `rpc.method.name_original`:** If and only if it's different than `rpc.method.name`. +**[5] `server.port`:** if the port is supported by the network transport used for communication. -**[6] `server.port`:** if the port is supported by the network transport used for communication. +**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[7] `network.protocol.name`:** The value SHOULD be normalized to lowercase. -**[8] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[8] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[9] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. - -**[10] `network.transport`:** The value SHOULD be normalized to lowercase. +**[9] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[11] `rpc.request.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. +**[10] `rpc.request.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. For example, a property `my-custom-key` with value `["1.2.3.4", "1.2.3.5"]` SHOULD be recorded as `rpc.request.metadata.my-custom-key` attribute with value `["1.2.3.4", "1.2.3.5"]` -**[12] `rpc.response.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. +**[11] `rpc.response.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. For example, a property `my-custom-key` with value `["attribute_value"]` SHOULD be recorded as @@ -122,7 +120,7 @@ the `rpc.response.metadata.my-custom-key` attribute with value `["attribute_valu The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* [`rpc.method.name`](/docs/registry/attributes/rpc.md) +* [`rpc.method`](/docs/registry/attributes/rpc.md) * [`server.address`](/docs/registry/attributes/server.md) * [`server.port`](/docs/registry/attributes/server.md) @@ -178,18 +176,18 @@ for the details on which values classify as errors. | [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The string representation of the [status code](https://github.com/grpc/grpc/blob/v1.75.0/doc/statuscodes.md) returned by the server. [1] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | -| [`rpc.method.name_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [5] | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [6] | int | Server port number. [7] | `80`; `8080`; `443` | -| [`client.address`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [8] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | -| [`client.port`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | Client port number. [9] | `65123` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.method_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If and only if it's different than `rpc.method`. | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | +| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [5] | int | Server port number. [6] | `80`; `8080`; `443` | +| [`client.address`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [7] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | +| [`client.port`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | Client port number. [8] | `65123` | | [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [10] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [11] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [12] | `tcp`; `udp` | -| [`rpc.request.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [13] | `["1.2.3.4", "1.2.3.5"]` | -| [`rpc.response.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [14] | `["attribute_value"]` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [9] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [10] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [11] | `tcp`; `udp` | +| [`rpc.request.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [12] | `["1.2.3.4", "1.2.3.5"]` | +| [`rpc.response.metadata.`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [13] | `["attribute_value"]` | **[1] `rpc.response.status_code`:** The following status codes SHOULD be considered errors: @@ -216,7 +214,7 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[4] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. +**[4] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such @@ -227,46 +225,44 @@ When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. In such cases, tracing -instrumentations MUST also set `rpc.method.name_original` attribute to +instrumentations MUST also set `rpc.method_original` attribute to the original method value. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. -The `rpc.method.name` can be different from the name of any implementing +The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. -**[5] `rpc.method.name_original`:** If and only if it's different than `rpc.method.name`. - -**[6] `server.port`:** if the port is supported by the network transport used for communication. +**[5] `server.port`:** if the port is supported by the network transport used for communication. -**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[8] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. +**[7] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. -**[9] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. +**[8] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. -**[10] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[9] `network.protocol.name`:** The value SHOULD be normalized to lowercase. -**[11] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. +**[10] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[12] `network.transport`:** The value SHOULD be normalized to lowercase. +**[11] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[13] `rpc.request.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. +**[12] `rpc.request.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. For example, a property `my-custom-key` with value `["1.2.3.4", "1.2.3.5"]` SHOULD be recorded as `rpc.request.metadata.my-custom-key` attribute with value `["1.2.3.4", "1.2.3.5"]` -**[14] `rpc.response.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. +**[13] `rpc.response.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. For example, a property `my-custom-key` with value `["attribute_value"]` SHOULD be recorded as @@ -275,7 +271,7 @@ the `rpc.response.metadata.my-custom-key` attribute with value `["attribute_valu The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* [`rpc.method.name`](/docs/registry/attributes/rpc.md) +* [`rpc.method`](/docs/registry/attributes/rpc.md) * [`server.address`](/docs/registry/attributes/server.md) * [`server.port`](/docs/registry/attributes/server.md) diff --git a/docs/rpc/json-rpc.md b/docs/rpc/json-rpc.md index f42f0b076d..9805e6f306 100644 --- a/docs/rpc/json-rpc.md +++ b/docs/rpc/json-rpc.md @@ -39,16 +39,16 @@ are considered errors. | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | | [`jsonrpc.protocol.version`](/docs/registry/attributes/jsonrpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If other than the default version (`1.0`) | string | Protocol version, as specified in the `jsonrpc` property of the request and its corresponding response. | `2.0`; `1.0` | -| [`rpc.method.name_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [3] | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` when available | string | The [`error.code`](https://www.jsonrpc.org/specification#error_object) property of response if it is an error response recorded as a string. [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [5] | int | Server port number. [6] | `80`; `8080`; `443` | -| [`jsonrpc.request.id`](/docs/registry/attributes/jsonrpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | A string representation of the `id` property of the request and its corresponding response. [7] | `10`; `request-7` | +| [`rpc.method_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If and only if it's different than `rpc.method`. | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | +| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` when available | string | The [`error.code`](https://www.jsonrpc.org/specification#error_object) property of response if it is an error response recorded as a string. [3] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | +| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [4] | int | Server port number. [5] | `80`; `8080`; `443` | +| [`jsonrpc.request.id`](/docs/registry/attributes/jsonrpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | A string representation of the `id` property of the request and its corresponding response. [6] | `10`; `request-7` | | [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [8] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [9] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [10] | `tcp`; `udp` | -| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | JSON-RPC method name provided in the request. [11] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [7] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [8] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [9] | `tcp`; `udp` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | JSON-RPC method name provided in the request. [10] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | **[1] `server.address`:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. @@ -66,34 +66,32 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[3] `rpc.method.name_original`:** If and only if it's different than `rpc.method.name`. +**[3] `rpc.response.status_code`:** All JSON RPC error codes SHOULD be considered errors. -**[4] `rpc.response.status_code`:** All JSON RPC error codes SHOULD be considered errors. +**[4] `server.port`:** if the port is supported by the network transport used for communication. -**[5] `server.port`:** if the port is supported by the network transport used for communication. +**[5] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. - -**[7] `jsonrpc.request.id`:** Under the [JSON-RPC specification](https://www.jsonrpc.org/specification), the `id` property may be a string, number, null, or omitted entirely. When omitted, the request is treated as a notification. Using `null` is not equivalent to omitting the `id`, but it is discouraged. +**[6] `jsonrpc.request.id`:** Under the [JSON-RPC specification](https://www.jsonrpc.org/specification), the `id` property may be a string, number, null, or omitted entirely. When omitted, the request is treated as a notification. Using `null` is not equivalent to omitting the `id`, but it is discouraged. Instrumentations SHOULD NOT capture this attribute when the `id` is `null` or omitted. -**[8] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[7] `network.protocol.name`:** The value SHOULD be normalized to lowercase. -**[9] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. +**[8] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[10] `network.transport`:** The value SHOULD be normalized to lowercase. +**[9] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[11] `rpc.method.name`:** JSON-RPC supports sending and receiving arbitrary method names without prior registration or definition. As a result, the method name MAY have unbounded cardinality in edge or error cases. -General-purpose JSON-RPC instrumentations therefore SHOULD NOT set this attribute by default and SHOULD provide a way to configure the list of recognized RPC methods. When tracing instrumentation converts RPC method to `_OTHER`, it MUST also set `rpc.method.name_original` span attribute to the original value. +**[10] `rpc.method`:** JSON-RPC supports sending and receiving arbitrary method names without prior registration or definition. As a result, the method name MAY have unbounded cardinality in edge or error cases. +General-purpose JSON-RPC instrumentations therefore SHOULD NOT set this attribute by default and SHOULD provide a way to configure the list of recognized RPC methods. When tracing instrumentation converts RPC method to `_OTHER`, it MUST also set `rpc.method_original` span attribute to the original value. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* [`rpc.method.name`](/docs/registry/attributes/rpc.md) +* [`rpc.method`](/docs/registry/attributes/rpc.md) * [`server.address`](/docs/registry/attributes/server.md) * [`server.port`](/docs/registry/attributes/server.md) @@ -150,18 +148,18 @@ are considered errors. | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | | [`jsonrpc.protocol.version`](/docs/registry/attributes/jsonrpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If other than the default version (`1.0`) | string | Protocol version, as specified in the `jsonrpc` property of the request and its corresponding response. | `2.0`; `1.0` | -| [`rpc.method.name_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [3] | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` when available | string | The [`error.code`](https://www.jsonrpc.org/specification#error_object) property of response recorded as a string. [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [5] | int | Server port number. [6] | `80`; `8080`; `443` | -| [`client.address`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [7] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | -| [`client.port`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | Client port number. [8] | `65123` | -| [`jsonrpc.request.id`](/docs/registry/attributes/jsonrpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | A string representation of the `id` property of the request and its corresponding response. [9] | `10`; `request-7` | +| [`rpc.method_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If and only if it's different than `rpc.method`. | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | +| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` when available | string | The [`error.code`](https://www.jsonrpc.org/specification#error_object) property of response recorded as a string. [3] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | +| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [4] | int | Server port number. [5] | `80`; `8080`; `443` | +| [`client.address`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [6] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | +| [`client.port`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | Client port number. [7] | `65123` | +| [`jsonrpc.request.id`](/docs/registry/attributes/jsonrpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | A string representation of the `id` property of the request and its corresponding response. [8] | `10`; `request-7` | | [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [10] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [11] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [12] | `tcp`; `udp` | -| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | JSON-RPC method name provided in the request. [13] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [9] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [10] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [11] | `tcp`; `udp` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | JSON-RPC method name provided in the request. [12] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | **[1] `server.address`:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. @@ -179,38 +177,36 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[3] `rpc.method.name_original`:** If and only if it's different than `rpc.method.name`. - -**[4] `rpc.response.status_code`:** All JSON RPC error codes SHOULD be considered errors. +**[3] `rpc.response.status_code`:** All JSON RPC error codes SHOULD be considered errors. -**[5] `server.port`:** if the port is supported by the network transport used for communication. +**[4] `server.port`:** if the port is supported by the network transport used for communication. -**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[5] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[7] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. +**[6] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. -**[8] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. +**[7] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. -**[9] `jsonrpc.request.id`:** Under the [JSON-RPC specification](https://www.jsonrpc.org/specification), the `id` property may be a string, number, null, or omitted entirely. When omitted, the request is treated as a notification. Using `null` is not equivalent to omitting the `id`, but it is discouraged. +**[8] `jsonrpc.request.id`:** Under the [JSON-RPC specification](https://www.jsonrpc.org/specification), the `id` property may be a string, number, null, or omitted entirely. When omitted, the request is treated as a notification. Using `null` is not equivalent to omitting the `id`, but it is discouraged. Instrumentations SHOULD NOT capture this attribute when the `id` is `null` or omitted. -**[10] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[9] `network.protocol.name`:** The value SHOULD be normalized to lowercase. -**[11] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. +**[10] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[12] `network.transport`:** The value SHOULD be normalized to lowercase. +**[11] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[13] `rpc.method.name`:** JSON-RPC supports sending and receiving arbitrary method names without prior registration or definition. As a result, the method name MAY have unbounded cardinality in edge or error cases. -General-purpose JSON-RPC instrumentations therefore SHOULD NOT set this attribute by default and SHOULD provide a way to configure the list of recognized RPC methods. When tracing instrumentation converts RPC method to `_OTHER`, it MUST also set `rpc.method.name_original` span attribute to the original value. +**[12] `rpc.method`:** JSON-RPC supports sending and receiving arbitrary method names without prior registration or definition. As a result, the method name MAY have unbounded cardinality in edge or error cases. +General-purpose JSON-RPC instrumentations therefore SHOULD NOT set this attribute by default and SHOULD provide a way to configure the list of recognized RPC methods. When tracing instrumentation converts RPC method to `_OTHER`, it MUST also set `rpc.method_original` span attribute to the original value. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* [`rpc.method.name`](/docs/registry/attributes/rpc.md) +* [`rpc.method`](/docs/registry/attributes/rpc.md) * [`server.address`](/docs/registry/attributes/server.md) * [`server.port`](/docs/registry/attributes/server.md) diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index 7ee10ec94f..e23a5425aa 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -89,7 +89,7 @@ SHOULD be the same as the RPC server span duration. | --- | --- | --- | --- | --- | --- | | [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | | [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | | [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [5] | `http` | | [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [6] | `1.1`; `2` | @@ -113,7 +113,7 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[3] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. +**[3] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such @@ -124,14 +124,14 @@ When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. In such cases, tracing -instrumentations MUST also set `rpc.method.name_original` attribute to +instrumentations MUST also set `rpc.method_original` attribute to the original method value. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. -The `rpc.method.name` can be different from the name of any implementing +The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the @@ -206,7 +206,7 @@ This metric is [recommended][MetricRecommended]. | --- | --- | --- | --- | --- | --- | | [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | | [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | | [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [5] | `http` | | [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [6] | `1.1`; `2` | @@ -230,7 +230,7 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[3] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. +**[3] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such @@ -241,14 +241,14 @@ When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. In such cases, tracing -instrumentations MUST also set `rpc.method.name_original` attribute to +instrumentations MUST also set `rpc.method_original` attribute to the original method value. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. -The `rpc.method.name` can be different from the name of any implementing +The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the @@ -323,7 +323,7 @@ This metric is [recommended][MetricRecommended]. | --- | --- | --- | --- | --- | --- | | [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | | [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | | [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [5] | `http` | | [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [6] | `1.1`; `2` | @@ -347,7 +347,7 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[3] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. +**[3] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such @@ -358,14 +358,14 @@ When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. In such cases, tracing -instrumentations MUST also set `rpc.method.name_original` attribute to +instrumentations MUST also set `rpc.method_original` attribute to the original method value. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. -The `rpc.method.name` can be different from the name of any implementing +The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the @@ -450,7 +450,7 @@ SHOULD be the same as the RPC client span duration. | [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | | [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [5] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | | [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If applicable. | int | Server port number. [6] | `80`; `8080`; `443` | | [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [7] | `http` | @@ -475,7 +475,7 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[4] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. +**[4] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such @@ -486,14 +486,14 @@ When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. In such cases, tracing -instrumentations MUST also set `rpc.method.name_original` attribute to +instrumentations MUST also set `rpc.method_original` attribute to the original method value. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. -The `rpc.method.name` can be different from the name of any implementing +The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the @@ -571,7 +571,7 @@ This metric is [recommended][MetricRecommended]. | [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | | [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [5] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | | [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If applicable. | int | Server port number. [6] | `80`; `8080`; `443` | | [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [7] | `http` | @@ -596,7 +596,7 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[4] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. +**[4] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such @@ -607,14 +607,14 @@ When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. In such cases, tracing -instrumentations MUST also set `rpc.method.name_original` attribute to +instrumentations MUST also set `rpc.method_original` attribute to the original method value. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. -The `rpc.method.name` can be different from the name of any implementing +The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the @@ -692,7 +692,7 @@ This metric is [recommended][MetricRecommended]. | [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | | [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [5] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | | [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If applicable. | int | Server port number. [6] | `80`; `8080`; `443` | | [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [7] | `http` | @@ -717,7 +717,7 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[4] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. +**[4] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such @@ -728,14 +728,14 @@ When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. In such cases, tracing -instrumentations MUST also set `rpc.method.name_original` attribute to +instrumentations MUST also set `rpc.method_original` attribute to the original method value. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. -The `rpc.method.name` can be different from the name of any implementing +The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index eb603d90d5..b37f82351b 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -96,15 +96,15 @@ document for details on how to record span status. | [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | -| [`rpc.method.name_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [5] | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [6] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [7] | int | Server port number. [8] | `80`; `8080`; `443` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.method_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If and only if it's different than `rpc.method`. | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | +| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [5] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | +| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [6] | int | Server port number. [7] | `80`; `8080`; `443` | | [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [9] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [10] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [11] | `tcp`; `udp` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [8] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [9] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [10] | `tcp`; `udp` | **[1] `rpc.system.name`:** The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. @@ -124,7 +124,7 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[4] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. +**[4] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such @@ -135,33 +135,31 @@ When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. In such cases, tracing -instrumentations MUST also set `rpc.method.name_original` attribute to +instrumentations MUST also set `rpc.method_original` attribute to the original method value. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. -The `rpc.method.name` can be different from the name of any implementing +The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. -**[5] `rpc.method.name_original`:** If and only if it's different than `rpc.method.name`. - -**[6] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. +**[5] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. -**[7] `server.port`:** if the port is supported by the network transport used for communication. +**[6] `server.port`:** if the port is supported by the network transport used for communication. -**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[9] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[8] `network.protocol.name`:** The value SHOULD be normalized to lowercase. -**[10] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. +**[9] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[11] `network.transport`:** The value SHOULD be normalized to lowercase. +**[10] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example @@ -170,7 +168,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* [`rpc.method.name`](/docs/registry/attributes/rpc.md) +* [`rpc.method`](/docs/registry/attributes/rpc.md) * [`rpc.system.name`](/docs/registry/attributes/rpc.md) * [`server.address`](/docs/registry/attributes/server.md) * [`server.port`](/docs/registry/attributes/server.md) @@ -242,17 +240,17 @@ document for details on how to record span status. | [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.method.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | -| [`rpc.method.name_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [5] | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [6] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [7] | int | Server port number. [8] | `80`; `8080`; `443` | -| [`client.address`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [9] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | -| [`client.port`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | Client port number. [10] | `65123` | +| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | +| [`rpc.method_original`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` If and only if it's different than `rpc.method`. | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | +| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [5] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | +| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [6] | int | Server port number. [7] | `80`; `8080`; `443` | +| [`client.address`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [8] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | +| [`client.port`](/docs/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | Client port number. [9] | `65123` | | [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [11] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [12] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [13] | `tcp`; `udp` | +| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [10] | `http` | +| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [11] | `1.1`; `2` | +| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [12] | `tcp`; `udp` | **[1] `rpc.system.name`:** The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. @@ -272,7 +270,7 @@ Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[4] `rpc.method.name`:** The method name MAY have unbounded cardinality in edge or error cases. +**[4] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such @@ -283,37 +281,35 @@ When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. In such cases, tracing -instrumentations MUST also set `rpc.method.name_original` attribute to +instrumentations MUST also set `rpc.method_original` attribute to the original method value. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. -The `rpc.method.name` can be different from the name of any implementing +The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. -**[5] `rpc.method.name_original`:** If and only if it's different than `rpc.method.name`. - -**[6] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. +**[5] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. -**[7] `server.port`:** if the port is supported by the network transport used for communication. +**[6] `server.port`:** if the port is supported by the network transport used for communication. -**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[9] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. +**[8] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. -**[10] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. +**[9] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. -**[11] `network.protocol.name`:** The value SHOULD be normalized to lowercase. +**[10] `network.protocol.name`:** The value SHOULD be normalized to lowercase. -**[12] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. +**[11] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[13] `network.transport`:** The value SHOULD be normalized to lowercase. +**[12] `network.transport`:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example @@ -322,7 +318,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* [`rpc.method.name`](/docs/registry/attributes/rpc.md) +* [`rpc.method`](/docs/registry/attributes/rpc.md) * [`rpc.system.name`](/docs/registry/attributes/rpc.md) * [`server.address`](/docs/registry/attributes/server.md) * [`server.port`](/docs/registry/attributes/server.md) diff --git a/model/rpc/common.yaml b/model/rpc/common.yaml index 84cd31feda..7a9b829068 100644 --- a/model/rpc/common.yaml +++ b/model/rpc/common.yaml @@ -3,7 +3,7 @@ groups: type: attribute_group brief: 'Common attributes for RPC spans and metrics.' attributes: - - ref: rpc.method.name + - ref: rpc.method - ref: server.address requirement_level: required brief: > diff --git a/model/rpc/deprecated/registry-deprecated.yaml b/model/rpc/deprecated/registry-deprecated.yaml index 2d1e005c81..edd332ff08 100644 --- a/model/rpc/deprecated/registry-deprecated.yaml +++ b/model/rpc/deprecated/registry-deprecated.yaml @@ -278,18 +278,9 @@ groups: - id: rpc.service type: string stability: development - brief: 'Deprecated, use fully-qualified `rpc.method.name` instead.' + brief: 'Deprecated, use fully-qualified `rpc.method` instead.' examples: "myservice.EchoService" deprecated: reason: uncategorized - note: 'Value should be included in `rpc.method.name` which is expected - to be a fully-qualified name.' - - id: rpc.method - type: string - stability: development - brief: 'Deprecated, use fully-qualified `rpc.method.name` instead.' - examples: "exampleMethod" - deprecated: - reason: uncategorized - note: 'Value should be included in `rpc.method.name` which is expected + note: 'Value should be included in `rpc.method` which is expected to be a fully-qualified name.' diff --git a/model/rpc/metrics.yaml b/model/rpc/metrics.yaml index 5f5375da7f..17983067c4 100644 --- a/model/rpc/metrics.yaml +++ b/model/rpc/metrics.yaml @@ -11,7 +11,7 @@ groups: - ref: server.port requirement_level: conditionally_required: If applicable. - - ref: rpc.method.name + - ref: rpc.method requirement_level: conditionally_required: if available. @@ -28,7 +28,7 @@ groups: - ref: server.port note: "" requirement_level: opt_in - - ref: rpc.method.name + - ref: rpc.method requirement_level: conditionally_required: if available. diff --git a/model/rpc/registry.yaml b/model/rpc/registry.yaml index c411dc4749..05baa9e779 100644 --- a/model/rpc/registry.yaml +++ b/model/rpc/registry.yaml @@ -40,7 +40,7 @@ groups: For example, a property `my-custom-key` with value `["attribute_value"]` SHOULD be recorded as the `rpc.response.metadata.my-custom-key` attribute with value `["attribute_value"]` examples: [["attribute_value"]] - - id: rpc.method.name + - id: rpc.method type: string stability: development brief: The fully-qualified logical name of the method from the RPC @@ -61,19 +61,19 @@ groups: a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. In such cases, tracing - instrumentations MUST also set `rpc.method.name_original` attribute to + instrumentations MUST also set `rpc.method_original` attribute to the original method value. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. - The `rpc.method.name` can be different from the name of any implementing + The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - - id: rpc.method.name_original + - id: rpc.method_original type: string stability: development brief: > diff --git a/model/rpc/spans.yaml b/model/rpc/spans.yaml index f6446f8368..e223eab826 100644 --- a/model/rpc/spans.yaml +++ b/model/rpc/spans.yaml @@ -14,13 +14,13 @@ groups: - ref: network.peer.port requirement_level: recommended: If `network.peer.address` is set. - - ref: rpc.method.name + - ref: rpc.method requirement_level: conditionally_required: if available. sampling_relevant: true - - ref: rpc.method.name_original + - ref: rpc.method_original requirement_level: - conditionally_required: If and only if it's different than `rpc.method.name`. + conditionally_required: If and only if it's different than `rpc.method`. - id: rpc.server type: attribute_group @@ -165,7 +165,7 @@ groups: extends: rpc span_kind: client attributes: - - ref: rpc.method.name + - ref: rpc.method requirement_level: required - ref: rpc.response.status_code requirement_level: required @@ -239,7 +239,7 @@ groups: conditionally_required: If other than the default version (`1.0`) - ref: jsonrpc.request.id requirement_level: recommended - - ref: rpc.method.name + - ref: rpc.method brief: JSON-RPC method name provided in the request. note: > JSON-RPC supports sending and receiving arbitrary method names without @@ -250,7 +250,7 @@ groups: attribute by default and SHOULD provide a way to configure the list of recognized RPC methods. When tracing instrumentation converts RPC method to `_OTHER`, it MUST - also set `rpc.method.name_original` span attribute to the original value. + also set `rpc.method_original` span attribute to the original value. requirement_level: opt_in - ref: rpc.response.status_code brief: > @@ -284,7 +284,7 @@ groups: conditionally_required: If other than the default version (`1.0`) - ref: jsonrpc.request.id requirement_level: recommended - - ref: rpc.method.name + - ref: rpc.method brief: JSON-RPC method name provided in the request. note: > JSON-RPC supports sending and receiving arbitrary method names without @@ -295,7 +295,7 @@ groups: attribute by default and SHOULD provide a way to configure the list of recognized RPC methods. When tracing instrumentation converts RPC method to `_OTHER`, it MUST - also set `rpc.method.name_original` span attribute to the original value. + also set `rpc.method_original` span attribute to the original value. requirement_level: opt_in - ref: rpc.response.status_code brief: > From 0cd7885c3d53ac8c1c30f0d11e8c522a233517ba Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 29 Dec 2025 12:21:12 -0800 Subject: [PATCH 9/9] up --- docs/rpc/rpc-spans.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 7d6c208fc1..1ab2b97e9c 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -51,13 +51,13 @@ This document defines how to describe remote procedure calls ### Span name -RPC spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.51.0/specification/trace/api.md#span). +RPC spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.52.0/specification/trace/api.md#span). -The *span name* SHOULD be `{rpc.method.name}` if it is -available and not set to `_OTHER`. +The *span name* SHOULD be `{rpc.method}` if it is available and not set to +`_OTHER`. -If `rpc.method.name` is unavailable or set to `_OTHER`, -the span name SHOULD be `{rpc.system.name}`. +If `rpc.method` is unavailable or set to `_OTHER`, the span name SHOULD be +`{rpc.system.name}`. Semantic conventions for individual RPC systems MAY specify different span name format.