From 72755137e5e24148696c2b878c32ec37d7f84235 Mon Sep 17 00:00:00 2001 From: Rostislav Kirillov Date: Fri, 7 May 2021 21:13:43 +0500 Subject: [PATCH] added JSON RPC specific attributes (#1643) --- CHANGELOG.md | 1 + semantic_conventions/trace/rpc.yaml | 30 ++++++++++++++ .../trace/semantic_conventions/rpc.md | 39 ++++++++++++++----- 3 files changed, 61 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cc07f514d57..7c9dcfdf83a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -96,6 +96,7 @@ release. - Add details for filling semantic conventions for AWS Lambda ([#1442](https://github.com/open-telemetry/opentelemetry-specification/pull/1442)) - Update semantic conventions to distinguish between int and double ([#1550](https://github.com/open-telemetry/opentelemetry-specification/pull/1550)) - Add semantic convention for AWS ECS task revision ([#1581](https://github.com/open-telemetry/opentelemetry-specification/pull/1581)) +- Add JSON RPC specific conventions ([#1643](https://github.com/open-telemetry/opentelemetry-specification/pull/1643)). ### Compatibility diff --git a/semantic_conventions/trace/rpc.yaml b/semantic_conventions/trace/rpc.yaml index c3c82a218f7..b34d774e4d7 100644 --- a/semantic_conventions/trace/rpc.yaml +++ b/semantic_conventions/trace/rpc.yaml @@ -78,3 +78,33 @@ groups: required: always brief: "The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request." examples: [0, 1, 16] + - id: rpc.jsonrpc + prefix: rpc.jsonrpc + extends: rpc + brief: 'Tech-specific attributes for [JSON RPC](https://www.jsonrpc.org/).' + attributes: + - id: version + type: string + required: + conditional: 'If missing, it is assumed to be "1.0".' + brief: "Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 does not specify this, the value can be omitted." + examples: ['2.0', '1.0'] + - id: method + type: string + required: always + brief: "`method` property from request. Unlike `rpc.method`, this may not relate to the actual method being called. Useful for client-side traces since client does not know what will be called on the server." + examples: ['users.create', 'get_users'] + - 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 + required: + conditional: 'If missing, response is assumed to be 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'] diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 6209d8a1cb2..4212c7909bb 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -9,15 +9,18 @@ This document defines how to describe remote procedure calls -- [Common remote procedure call conventions](#common-remote-procedure-call-conventions) - * [Span name](#span-name) - * [Attributes](#attributes) - + [Service name](#service-name) - * [Distinction from HTTP spans](#distinction-from-http-spans) -- [gRPC](#grpc) - * [gRPC Attributes](#grpc-attributes) - * [gRPC Status](#grpc-status) - * [Events](#events) +- [Semantic conventions for RPC spans](#semantic-conventions-for-rpc-spans) + - [Common remote procedure call conventions](#common-remote-procedure-call-conventions) + - [Span name](#span-name) + - [Attributes](#attributes) + - [Service name](#service-name) + - [Distinction from HTTP spans](#distinction-from-http-spans) + - [gRPC](#grpc) + - [gRPC Attributes](#grpc-attributes) + - [gRPC Status](#grpc-status) + - [Events](#events) + - [JSON RPC](#json-rpc) + - [JSON RPC Attributes](#json-rpc-attributes) @@ -164,3 +167,21 @@ one for sent messages and one for received message. This way we guarantee that the values will be consistent between different implementations. In case of unary calls only one sent and one received message will be recorded for both client and server spans. + +## JSON RPC + +Conventions specific to [JSON RPC](https://www.jsonrpc.org/). + +`rpc.system` MUST be set to `"jsonrpc"`. + +### JSON RPC Attributes + + +| Attribute | Type | Description | Examples | Required | +|---|---|---|---|---| +| `rpc.jsonrpc.version` | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 does not specify this, the value can be omitted. | `2.0`; `1.0` | If missing, it is assumed to be "1.0". | +| `rpc.jsonrpc.method` | string | `method` property from request. Unlike `rpc.method`, this may not relate to the actual method being called. Useful for client-side traces since client does not know what will be called on the server. | `users.create`; `get_users` | Yes | +| `rpc.jsonrpc.request_id` | string | `id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. | `10`; `request-7`; `` | No | +| `rpc.jsonrpc.error_code` | int | `error.code` property of response if it is an error response. | `-32700`; `100` | If missing, response is assumed to be successful. | +| `rpc.jsonrpc.error_message` | string | `error.message` property of response if it is an error response. | `Parse error`; `User already exists` | No | +