Metadata

Key-value pairs alongside messages

Metadata is a set of key-value pairs sent with a call, like HTTP headers: authentication tokens, request IDs, tenant IDs, tracing context. Keys are lowercase ASCII; binary values use keys ending in -bin. Servers can send initial metadata (headers) and trailing metadata (trailers, alongside the status). Keep business data in messages and use metadata for cross-cutting information.

Cross-cutting concerns

Metadata carries context, TLS and tokens secure calls, and interceptors apply shared logic to every RPC.

Sending and reading metadata in Python

A sketch.

# client
order = stub.GetOrder(
    order_pb2.GetOrderRequest(id="o-1001"),
    metadata=[("x-request-id", "req-7f3a"), ("authorization", f"Bearer {token}")],
    timeout=2.0,
)

# server
def GetOrder(self, request, context):
    md = dict(context.invocation_metadata())
    request_id = md.get("x-request-id", "")
    context.set_trailing_metadata([("x-served-by", "orders-7d9c")])
    ...

Keep metadata small

Metadata is sent as HTTP/2 headers with size limits; large payloads belong in messages.

त्वरित जाँच: What suffix marks a binary metadata key?

• _b64
• -binary
• -bin
• -raw