Add gRPC request/response metadata as span attributes (#2874)

CHANGELOG.md

@@ -22,6 +22,8 @@ release.
 
 ### Semantic Conventions
 
+- Add gRPC request and response metadata semantic conventions
+ ([#2874](https:/open-telemetry/opentelemetry-specification/pull/2874))
 - Add `process.paging.faults` metric to semantic conventions
  ([#2827](https:/open-telemetry/opentelemetry-specification/pull/2827))
 

specification/trace/semantic_conventions/rpc.md

@@ -19,6 +19,7 @@ This document defines how to describe remote procedure calls
 - [gRPC](#grpc)
  * [gRPC Attributes](#grpc-attributes)
  * [gRPC Status](#grpc-status)
+ * [gRPC Request and Response Metadata](#grpc-request-and-response-metadata)
 - [JSON RPC](#json-rpc)
  * [JSON RPC Attributes](#json-rpc-attributes)
 
@@ -202,6 +203,16 @@ For remote procedure calls via [gRPC][], additional conventions are described in
 
 The [Span Status](../api.md#set-status) MUST be left unset for an `OK` gRPC status code, and set to `Error` for all others.
 
+### gRPC Request and Response Metadata
+
+| Attribute | Type | Description | Examples | Requirement Level |
+|-------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|-------------------|
+| `rpc.request.metadata.<key>` | string[] | gRPC request metadata, `<key>` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]` | Optional |
+| `rpc.response.metadata.<key>` | string[] | gRPC response metadata, `<key>` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Optional |
+
+**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured.
+Including all request/response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
+
 ## JSON RPC
 
 Conventions specific to [JSON RPC](https://www.jsonrpc.org/).