Explains what metadata is, how it is transmitted, and what it is used for.
Metadata is a side channel that allows clients and servers to provide information to each other that is associated with an RPC.
gRPC metadata is a key-value pair of data that is sent with initial or final gRPC requests or responses. It is used to provide additional information about the call, such as authentication credentials, tracing information, or custom headers.
gRPC metadata is implemented using HTTP/2 headers. The keys are ASCII
strings, while the values can be either ASCII strings or binary data. The keys
are case insensitive
and must not start with the prefix
grpc-, which is reserved for gRPC itself.
gRPC metadata can be sent and received by both the client and the server. Headers are sent from the client to the server before the initial request and from the server to the client before the initial response of an RPC call. Trailers are sent by the server when it closes an RPC.
gRPC metadata is useful for a variety of purposes, such as:
- Authentication: gRPC metadata can be used to send authentication
credentials to the server.
This can be used to implement different authentication schemes, such as
JWTusing the standard HTTP Authorization header.
- Tracing: gRPC metadata can be used to send tracing information to the server. This can be used to track the progress of a request through a distributed system.
- Custom headers: gRPC metadata can be used to send custom headers to the server or from the server to the client. This can be used to implement application-specific features, such as load balancing, rate limiting or providing detailed error messages from the server to the client.
- Internal usages: gRPC uses HTTP/2 headers and trailers, which will be integrated with the metadata specified by your application.
See Concepts guide
WARNING: Servers may limit the size of Request-Headers, with a default of 8 KiB suggested.
Custom metadata must follow the “Custom-Metadata” format listed in PROTOCOL-HTTP2 , with the exception of binary headers not needing to be base64 encoded.
Headers are sent before the initial request data message from the client to the server and similarly before the initial response data from the server to the client (gRPC optimizes for the unary case by combining headers, data and trailer into a single HTTP/2 frame). The header includes things like authentication credentials and how to handle the RPC. Some of the headers, such as authorization, are generated by gRPC for you.
Custom header handling is language dependent, generally through interceptors.
Trailers are a special kind of header that is sent after the message data. They are used internally to communicate the outcome of an RPC. At the application level, custom trailers can be used to communicate things not directly part of the data, such as server utilization and query cost. Trailers are sent only by the server.
For more details, please see the following gRPCs
- proposal: G1 true binary metadata
- proposal: L7 go metadata api
- proposal: L48 node metadata options
- proposal: L42 python metadata flags
- proposal: L11 ruby interceptors
Java Error Handling
Go Metadata Interceptor