open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Moved rpc attributes to the registry (#395) 

Signed-off-by: Alexander Wert <alexander.wert@elastic.co>
This commit is contained in:
Alexander Wert 2023-10-23 15:52:46 +02:00 committed by GitHub
parent cd047137dd
commit 064fe4efda
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 347 additions and 213 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/attributes-registry/README.md
View File

@ -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)

91
docs/attributes-registry/rpc.md Normal file
View File

@ -0,0 +1,91 @@
<!--- Hugo front matter used to generate the website version of this page:
--->
# RPC
## RPC Attributes
RPC attributes are intended to be used in the context of events related to remote procedure calls (RPC).
<!-- semconv registry.rpc(omit_requirement_level) -->
| 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.<key>` | string[] | Connect request metadata, `<key>` 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.<key>` | string[] | Connect response metadata, `<key>` 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.<key>` | string[] | gRPC request metadata, `<key>` 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.<key>` | string[] | gRPC response metadata, `<key>` 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 |
<!-- endsemconv -->

6
docs/cloud-providers/aws-sdk.md
View File

@ -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).

8
docs/rpc/connect-rpc.md
View File

@ -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.
<!-- semconv rpc.connect_rpc -->
<!-- semconv rpc.connect_rpc(full,tag=connect_rpc-tech-specific) -->
| 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.<key>` | string[] | Connect request metadata, `<key>` 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.<key>` | string[] | Connect response metadata, `<key>` 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.<key>`](../attributes-registry/rpc.md) | string[] | Connect request metadata, `<key>` 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.<key>`](../attributes-registry/rpc.md) | string[] | Connect response metadata, `<key>` 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.

8
docs/rpc/grpc.md
View File

@ -16,12 +16,12 @@ described on this page.
Below is a table of attributes that SHOULD be included on client and server gRPC measurements.
<!-- semconv rpc.grpc -->
<!-- semconv rpc.grpc(full,tag=grpc-tech-specific) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `rpc.grpc.request.metadata.<key>` | string[] | gRPC request metadata, `<key>` 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.<key>` | string[] | gRPC response metadata, `<key>` 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.<key>`](../attributes-registry/rpc.md) | string[] | gRPC request metadata, `<key>` 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.<key>`](../attributes-registry/rpc.md) | string[] | gRPC response metadata, `<key>` 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.

12
docs/rpc/json-rpc.md
View File

@ -14,14 +14,14 @@ described on this page.
`rpc.system` MUST be set to `"jsonrpc"`.
<!-- semconv rpc.jsonrpc -->
<!-- semconv rpc.jsonrpc(full,tag=jsonrpc-tech-specific) -->
| 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.
<!-- endsemconv -->

6
docs/rpc/rpc-metrics.md
View File

@ -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 |

24
docs/rpc/rpc-spans.md
View File

@ -82,14 +82,14 @@ Examples of span names:
### Common attributes
<!-- semconv rpc -->
<!-- semconv rpc(full) -->
| 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 |

1
model/metrics/rpc-metrics.yaml
View File

@ -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

190
model/registry/rpc.yaml Normal file
View File

@ -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, `<key>` 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, `<key>` 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, `<key>` 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, `<key>` 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'

213
model/trace/rpc.yaml
View File

@ -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, `<key>` 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, `<key>` 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, `<key>` 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, `<key>` 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"]']