diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index d7deb572d..81002bd95 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -29,6 +29,7 @@ Currently, the following namespaces exist: * [HTTP](http.md) * [Network](network.md) +* [RPC](rpc.md) * [URL](url.md) * [User agent](user-agent.md) diff --git a/docs/attributes-registry/rpc.md b/docs/attributes-registry/rpc.md new file mode 100644 index 000000000..fd112b1d2 --- /dev/null +++ b/docs/attributes-registry/rpc.md @@ -0,0 +1,91 @@ + + +# RPC + +## RPC Attributes + +RPC attributes are intended to be used in the context of events related to remote procedure calls (RPC). + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `rpc.connect_rpc.error_code` | string | The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. | `cancelled` | +| `rpc.connect_rpc.request.metadata.` | string[] | Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. [1] | `rpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]` | +| `rpc.connect_rpc.response.metadata.` | string[] | Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. [2] | `rpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]` | +| `rpc.grpc.request.metadata.` | string[] | gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [3] | `rpc.grpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]` | +| `rpc.grpc.response.metadata.` | string[] | gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [4] | `rpc.grpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]` | +| `rpc.grpc.status_code` | int | The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. | `0` | +| `rpc.jsonrpc.error_code` | int | `error.code` property of response if it is an error response. | `-32700`; `100` | +| `rpc.jsonrpc.error_message` | string | `error.message` property of response if it is an error response. | `Parse error`; `User already exists` | +| `rpc.jsonrpc.request_id` | string | `id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. | `10`; `request-7`; `` | +| `rpc.jsonrpc.version` | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted. | `2.0`; `1.0` | +| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [5] | `exampleMethod` | +| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [6] | `myservice.EchoService` | +| `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | + +**[1]:** 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. + +**[2]:** 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. + +**[3]:** 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. + +**[4]:** 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. + +**[5]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +**[6]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +`rpc.connect_rpc.error_code` MUST be one of the following: + +| Value | Description | +|---|---| +| `cancelled` | cancelled | +| `unknown` | unknown | +| `invalid_argument` | invalid_argument | +| `deadline_exceeded` | deadline_exceeded | +| `not_found` | not_found | +| `already_exists` | already_exists | +| `permission_denied` | permission_denied | +| `resource_exhausted` | resource_exhausted | +| `failed_precondition` | failed_precondition | +| `aborted` | aborted | +| `out_of_range` | out_of_range | +| `unimplemented` | unimplemented | +| `internal` | internal | +| `unavailable` | unavailable | +| `data_loss` | data_loss | +| `unauthenticated` | unauthenticated | + +`rpc.grpc.status_code` MUST be one of the following: + +| Value | Description | +|---|---| +| `0` | OK | +| `1` | CANCELLED | +| `2` | UNKNOWN | +| `3` | INVALID_ARGUMENT | +| `4` | DEADLINE_EXCEEDED | +| `5` | NOT_FOUND | +| `6` | ALREADY_EXISTS | +| `7` | PERMISSION_DENIED | +| `8` | RESOURCE_EXHAUSTED | +| `9` | FAILED_PRECONDITION | +| `10` | ABORTED | +| `11` | OUT_OF_RANGE | +| `12` | UNIMPLEMENTED | +| `13` | INTERNAL | +| `14` | UNAVAILABLE | +| `15` | DATA_LOSS | +| `16` | UNAUTHENTICATED | + +`rpc.system` 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. + +| Value | Description | +|---|---| +| `grpc` | gRPC | +| `java_rmi` | Java RMI | +| `dotnet_wcf` | .NET WCF | +| `apache_dubbo` | Apache Dubbo | +| `connect_rpc` | Connect RPC | + diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md index e412dba1d..9eb207774 100644 --- a/docs/cloud-providers/aws-sdk.md +++ b/docs/cloud-providers/aws-sdk.md @@ -28,9 +28,9 @@ with the naming guidelines for RPC client spans. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `aws.request_id` | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | Recommended | -| [`rpc.method`](../rpc/rpc-spans.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | Recommended | -| [`rpc.service`](../rpc/rpc-spans.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | Recommended | -| [`rpc.system`](../rpc/rpc-spans.md) | string | The value `aws-api`. | `aws-api` | Required | +| [`rpc.method`](../attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | Recommended | +| [`rpc.service`](../attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | Recommended | +| [`rpc.system`](../attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | Required | **[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). diff --git a/docs/rpc/connect-rpc.md b/docs/rpc/connect-rpc.md index f2b9d9ca0..dd590f75d 100644 --- a/docs/rpc/connect-rpc.md +++ b/docs/rpc/connect-rpc.md @@ -16,12 +16,12 @@ described on this page. Below is a table of attributes that SHOULD be included on client and server Connect RPC measurements. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `rpc.connect_rpc.error_code` | string | The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. | `cancelled` | Conditionally Required: [1] | -| `rpc.connect_rpc.request.metadata.` | string[] | Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. [2] | `rpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]` | Opt-In | -| `rpc.connect_rpc.response.metadata.` | string[] | Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. [3] | `rpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]` | Opt-In | +| [`rpc.connect_rpc.error_code`](../attributes-registry/rpc.md) | string | The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. | `cancelled` | Conditionally Required: [1] | +| [`rpc.connect_rpc.request.metadata.`](../attributes-registry/rpc.md) | string[] | Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. [2] | `rpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]` | Opt-In | +| [`rpc.connect_rpc.response.metadata.`](../attributes-registry/rpc.md) | string[] | Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. [3] | `rpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]` | Opt-In | **[1]:** If response is not successful and if error code available. diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md index 52c490356..100f17dc4 100644 --- a/docs/rpc/grpc.md +++ b/docs/rpc/grpc.md @@ -16,12 +16,12 @@ described on this page. Below is a table of attributes that SHOULD be included on client and server gRPC measurements. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `rpc.grpc.request.metadata.` | string[] | gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [1] | `rpc.grpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]` | Opt-In | -| `rpc.grpc.response.metadata.` | string[] | gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [2] | `rpc.grpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]` | Opt-In | -| `rpc.grpc.status_code` | int | The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. | `0` | Required | +| [`rpc.grpc.request.metadata.`](../attributes-registry/rpc.md) | string[] | gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [1] | `rpc.grpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]` | Opt-In | +| [`rpc.grpc.response.metadata.`](../attributes-registry/rpc.md) | string[] | gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [2] | `rpc.grpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]` | Opt-In | +| [`rpc.grpc.status_code`](../attributes-registry/rpc.md) | int | The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. | `0` | Required | **[1]:** 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. diff --git a/docs/rpc/json-rpc.md b/docs/rpc/json-rpc.md index 32ebf6540..dbf79fca7 100644 --- a/docs/rpc/json-rpc.md +++ b/docs/rpc/json-rpc.md @@ -14,14 +14,14 @@ described on this page. `rpc.system` MUST be set to `"jsonrpc"`. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `rpc.jsonrpc.error_code` | int | `error.code` property of response if it is an error response. | `-32700`; `100` | Conditionally Required: If response is not successful. | -| `rpc.jsonrpc.error_message` | string | `error.message` property of response if it is an error response. | `Parse error`; `User already exists` | Recommended | -| `rpc.jsonrpc.request_id` | string | `id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. | `10`; `request-7`; `` | Recommended | -| `rpc.jsonrpc.version` | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted. | `2.0`; `1.0` | Conditionally Required: If other than the default version (`1.0`) | -| [`rpc.method`](rpc-spans.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [1] | `exampleMethod` | Required | +| [`rpc.jsonrpc.error_code`](../attributes-registry/rpc.md) | int | `error.code` property of response if it is an error response. | `-32700`; `100` | Conditionally Required: If response is not successful. | +| [`rpc.jsonrpc.error_message`](../attributes-registry/rpc.md) | string | `error.message` property of response if it is an error response. | `Parse error`; `User already exists` | Recommended | +| [`rpc.jsonrpc.request_id`](../attributes-registry/rpc.md) | string | `id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. | `10`; `request-7`; `` | Recommended | +| [`rpc.jsonrpc.version`](../attributes-registry/rpc.md) | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted. | `2.0`; `1.0` | Conditionally Required: If other than the default version (`1.0`) | +| [`rpc.method`](../attributes-registry/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [1] | `exampleMethod` | Required | **[1]:** This is always required for jsonrpc. See the note in the general RPC conventions for more information. diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index a27e701e9..22fe31555 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -222,9 +222,9 @@ measurements. |---|---|---|---|---| | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended | | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | -| [`rpc.method`](rpc-spans.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [3] | `exampleMethod` | Recommended | -| [`rpc.service`](rpc-spans.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [4] | `myservice.EchoService` | Recommended | -| [`rpc.system`](rpc-spans.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | +| [`rpc.method`](../attributes-registry/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [3] | `exampleMethod` | Recommended | +| [`rpc.service`](../attributes-registry/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [4] | `myservice.EchoService` | Recommended | +| [`rpc.system`](../attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | | [`server.address`](../general/attributes.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`server.port`](../general/attributes.md) | int | Server port number. [6] | `80`; `8080`; `443` | Recommended | diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 695766872..af881e211 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -82,14 +82,14 @@ Examples of span names: ### Common attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended | | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | -| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [3] | `exampleMethod` | Recommended | -| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [4] | `myservice.EchoService` | Recommended | -| `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | +| [`rpc.method`](../attributes-registry/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [3] | `exampleMethod` | Recommended | +| [`rpc.service`](../attributes-registry/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [4] | `myservice.EchoService` | Recommended | +| [`rpc.system`](../attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | | [`server.address`](../general/attributes.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../general/attributes.md) | int | Server port number. [6] | `80`; `8080`; `443` | Conditionally Required: See below | @@ -109,6 +109,22 @@ different processes could be listening on TCP port 12345 and UDP port 12345. **[6]:** 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. +`network.transport` 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. + +| Value | Description | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. | +| `unix` | Unix domain socket | + +`network.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. + +| Value | Description | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + `rpc.system` 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. | Value | Description | diff --git a/model/metrics/rpc-metrics.yaml b/model/metrics/rpc-metrics.yaml index 43186b076..ca29cdf19 100644 --- a/model/metrics/rpc-metrics.yaml +++ b/model/metrics/rpc-metrics.yaml @@ -7,6 +7,7 @@ groups: brief: "Describes RPC metric attributes." attributes: - ref: rpc.system + requirement_level: required - ref: rpc.service - ref: rpc.method - ref: network.transport diff --git a/model/registry/rpc.yaml b/model/registry/rpc.yaml new file mode 100644 index 000000000..64f1f9a66 --- /dev/null +++ b/model/registry/rpc.yaml @@ -0,0 +1,190 @@ +groups: + - id: registry.rpc + prefix: rpc + type: attribute_group + brief: 'This document defines attributes for remote procedure calls.' + attributes: + - id: connect_rpc.error_code + type: + members: + - id: cancelled + value: cancelled + - id: unknown + value: unknown + - id: invalid_argument + value: invalid_argument + - id: deadline_exceeded + value: deadline_exceeded + - id: not_found + value: not_found + - id: already_exists + value: already_exists + - id: permission_denied + value: permission_denied + - id: resource_exhausted + value: resource_exhausted + - id: failed_precondition + value: failed_precondition + - id: aborted + value: aborted + - id: out_of_range + value: out_of_range + - id: unimplemented + value: unimplemented + - id: internal + value: internal + - id: unavailable + value: unavailable + - id: data_loss + value: data_loss + - id: unauthenticated + value: unauthenticated + brief: "The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values." + - id: connect_rpc.request.metadata + type: template[string[]] + brief: > + Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + note: > + 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. + examples: ['rpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]'] + - id: connect_rpc.response.metadata + type: template[string[]] + brief: > + Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + note: > + 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. + examples: ['rpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]'] + - id: grpc.status_code + type: + members: + - id: ok + brief: OK + value: 0 + - id: cancelled + brief: CANCELLED + value: 1 + - id: unknown + brief: UNKNOWN + value: 2 + - id: invalid_argument + brief: INVALID_ARGUMENT + value: 3 + - id: deadline_exceeded + brief: DEADLINE_EXCEEDED + value: 4 + - id: not_found + brief: NOT_FOUND + value: 5 + - id: already_exists + brief: ALREADY_EXISTS + value: 6 + - id: permission_denied + brief: PERMISSION_DENIED + value: 7 + - id: resource_exhausted + brief: RESOURCE_EXHAUSTED + value: 8 + - id: failed_precondition + brief: FAILED_PRECONDITION + value: 9 + - id: aborted + brief: ABORTED + value: 10 + - id: out_of_range + brief: OUT_OF_RANGE + value: 11 + - id: unimplemented + brief: UNIMPLEMENTED + value: 12 + - id: internal + brief: INTERNAL + value: 13 + - id: unavailable + brief: UNAVAILABLE + value: 14 + - id: data_loss + brief: DATA_LOSS + value: 15 + - id: unauthenticated + brief: UNAUTHENTICATED + value: 16 + brief: "The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request." + - id: grpc.request.metadata + type: template[string[]] + brief: > + gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + note: > + 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. + examples: ['rpc.grpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]'] + - id: grpc.response.metadata + type: template[string[]] + brief: > + gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + note: > + 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. + examples: ['rpc.grpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]'] + - id: jsonrpc.error_code + type: int + brief: "`error.code` property of response if it is an error response." + examples: [-32700, 100] + - id: jsonrpc.error_message + type: string + brief: "`error.message` property of response if it is an error response." + examples: ['Parse error', 'User already exists'] + - id: jsonrpc.request_id + type: string + brief: > + `id` property of request or response. + Since protocol allows id to be int, string, `null` or missing (for notifications), + value is expected to be cast to string for simplicity. + Use empty string in case of `null` value. Omit entirely if this is a notification. + examples: ['10', 'request-7', ''] + - id: jsonrpc.version + type: string + brief: "Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted." + examples: ['2.0', '1.0'] + - id: method + type: string + brief: 'The name of the (logical) method being called, must be equal to the $method part in the span name.' + note: > + This is the logical name of the method from the RPC interface perspective, + which can be different from the name of any implementing method/function. + The `code.function` attribute may be used to store the latter + (e.g., method actually executing the call on the server side, + RPC client stub method on the client side). + examples: "exampleMethod" + - id: service + type: string + brief: 'The full (logical) name of the service being called, including its package name, if applicable.' + note: > + This is the logical name of the service from the RPC interface perspective, + which can be different from the name of any implementing class. + The `code.namespace` attribute may be used to store the latter + (despite the attribute name, it may include a class name; + e.g., class with method actually executing the call on the server side, + RPC client stub class on the client side). + examples: "myservice.EchoService" + - id: system + brief: 'A string identifying the remoting system. See below for a list of well-known identifiers.' + type: + allow_custom_values: true + members: + - id: grpc + value: 'grpc' + brief: 'gRPC' + - id: java_rmi + value: 'java_rmi' + brief: 'Java RMI' + - id: dotnet_wcf + value: 'dotnet_wcf' + brief: '.NET WCF' + - id: apache_dubbo + value: 'apache_dubbo' + brief: 'Apache Dubbo' + - id: connect_rpc + value: 'connect_rpc' + brief: 'Connect RPC' diff --git a/model/trace/rpc.yaml b/model/trace/rpc.yaml index 85f4449d4..29fa0bf9b 100644 --- a/model/trace/rpc.yaml +++ b/model/trace/rpc.yaml @@ -5,50 +5,10 @@ groups: brief: 'This document defines semantic conventions for remote procedure calls.' events: [rpc.message] attributes: - - id: system + - ref: rpc.system requirement_level: required - brief: 'A string identifying the remoting system. See below for a list of well-known identifiers.' - type: - allow_custom_values: true - members: - - id: grpc - value: 'grpc' - brief: 'gRPC' - - id: java_rmi - value: 'java_rmi' - brief: 'Java RMI' - - id: dotnet_wcf - value: 'dotnet_wcf' - brief: '.NET WCF' - - id: apache_dubbo - value: 'apache_dubbo' - brief: 'Apache Dubbo' - - id: connect_rpc - value: 'connect_rpc' - brief: 'Connect RPC' - - id: service - type: string - requirement_level: recommended - brief: 'The full (logical) name of the service being called, including its package name, if applicable.' - note: > - This is the logical name of the service from the RPC interface perspective, - which can be different from the name of any implementing class. - The `code.namespace` attribute may be used to store the latter - (despite the attribute name, it may include a class name; - e.g., class with method actually executing the call on the server side, - RPC client stub class on the client side). - examples: "myservice.EchoService" - - id: method - type: string - requirement_level: recommended - brief: 'The name of the (logical) method being called, must be equal to the $method part in the span name.' - note: > - This is the logical name of the method from the RPC interface perspective, - which can be different from the name of any implementing method/function. - The `code.function` attribute may be used to store the latter - (e.g., method actually executing the call on the server side, - RPC client stub method on the client side). - examples: "exampleMethod" + - ref: rpc.service + - ref: rpc.method - ref: network.transport - ref: network.type - ref: server.address @@ -76,7 +36,6 @@ groups: recommended: If `network.peer.address` is set. - id: rpc.server - prefix: rpc type: span extends: rpc span_kind: server @@ -94,85 +53,19 @@ groups: - ref: network.type - id: rpc.grpc - prefix: rpc.grpc type: span extends: rpc brief: 'Tech-specific attributes for gRPC.' attributes: - - id: status_code - type: - members: - - id: ok - brief: OK - value: 0 - - id: cancelled - brief: CANCELLED - value: 1 - - id: unknown - brief: UNKNOWN - value: 2 - - id: invalid_argument - brief: INVALID_ARGUMENT - value: 3 - - id: deadline_exceeded - brief: DEADLINE_EXCEEDED - value: 4 - - id: not_found - brief: NOT_FOUND - value: 5 - - id: already_exists - brief: ALREADY_EXISTS - value: 6 - - id: permission_denied - brief: PERMISSION_DENIED - value: 7 - - id: resource_exhausted - brief: RESOURCE_EXHAUSTED - value: 8 - - id: failed_precondition - brief: FAILED_PRECONDITION - value: 9 - - id: aborted - brief: ABORTED - value: 10 - - id: out_of_range - brief: OUT_OF_RANGE - value: 11 - - id: unimplemented - brief: UNIMPLEMENTED - value: 12 - - id: internal - brief: INTERNAL - value: 13 - - id: unavailable - brief: UNAVAILABLE - value: 14 - - id: data_loss - brief: DATA_LOSS - value: 15 - - id: unauthenticated - brief: UNAUTHENTICATED - value: 16 + - ref: rpc.grpc.status_code + tag: grpc-tech-specific requirement_level: required - brief: "The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request." - - id: request.metadata - type: template[string[]] + - ref: rpc.grpc.request.metadata + tag: grpc-tech-specific requirement_level: opt_in - brief: > - gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. - note: > - 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. - examples: ['rpc.grpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]'] - - id: response.metadata - type: template[string[]] + - ref: rpc.grpc.response.metadata + tag: grpc-tech-specific requirement_level: opt_in - brief: > - gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. - note: > - 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. - examples: ['rpc.grpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]'] - id: rpc.jsonrpc prefix: rpc.jsonrpc @@ -180,31 +73,20 @@ groups: extends: rpc brief: 'Tech-specific attributes for [JSON RPC](https://www.jsonrpc.org/).' attributes: - - id: version - type: string + - ref: rpc.jsonrpc.version + tag: jsonrpc-tech-specific requirement_level: conditionally_required: If other than the default version (`1.0`) - brief: "Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted." - examples: ['2.0', '1.0'] - - id: request_id - type: string - brief: > - `id` property of request or response. - Since protocol allows id to be int, string, `null` or missing (for notifications), - value is expected to be cast to string for simplicity. - Use empty string in case of `null` value. Omit entirely if this is a notification. - examples: ['10', 'request-7', ''] - - id: error_code - type: int + - ref: rpc.jsonrpc.request_id + tag: jsonrpc-tech-specific + - ref: rpc.jsonrpc.error_code + tag: jsonrpc-tech-specific requirement_level: conditionally_required: If response is not successful. - brief: "`error.code` property of response if it is an error response." - examples: [-32700, 100] - - id: error_message - type: string - brief: "`error.message` property of response if it is an error response." - examples: ['Parse error', 'User already exists'] + - ref: rpc.jsonrpc.error_message + tag: jsonrpc-tech-specific - ref: rpc.method + tag: jsonrpc-tech-specific requirement_level: required note: > This is always required for jsonrpc. See the note in the general @@ -235,64 +117,17 @@ groups: brief: "Uncompressed size of the message in bytes." - id: rpc.connect_rpc - prefix: rpc.connect_rpc type: span extends: rpc brief: 'Tech-specific attributes for Connect RPC.' attributes: - - id: error_code - type: - members: - - id: cancelled - value: cancelled - - id: unknown - value: unknown - - id: invalid_argument - value: invalid_argument - - id: deadline_exceeded - value: deadline_exceeded - - id: not_found - value: not_found - - id: already_exists - value: already_exists - - id: permission_denied - value: permission_denied - - id: resource_exhausted - value: resource_exhausted - - id: failed_precondition - value: failed_precondition - - id: aborted - value: aborted - - id: out_of_range - value: out_of_range - - id: unimplemented - value: unimplemented - - id: internal - value: internal - - id: unavailable - value: unavailable - - id: data_loss - value: data_loss - - id: unauthenticated - value: unauthenticated + - ref: rpc.connect_rpc.error_code + tag: connect_rpc-tech-specific requirement_level: conditionally_required: If response is not successful and if error code available. - brief: "The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values." - - id: request.metadata - type: template[string[]] + - ref: rpc.connect_rpc.request.metadata + tag: connect_rpc-tech-specific requirement_level: opt_in - brief: > - Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. - note: > - 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. - examples: ['rpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]'] - - id: response.metadata - type: template[string[]] + - ref: rpc.connect_rpc.response.metadata + tag: connect_rpc-tech-specific requirement_level: opt_in - brief: > - Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. - note: > - 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. - examples: ['rpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]']