AGENTS.md

1# Server Load Reporting Filter
2 
3This directory contains a server-side filter for reporting load data to a load balancer.
4 
5See also: [gRPC Filters overview](../AGENTS.md)
6 
7## Overarching Purpose
8 
9The server load reporting filter provides a mechanism for a gRPC server to report load data to a load balancer. This data can be used by the load balancer to make more intelligent load balancing decisions, such as routing requests to the least loaded backend.
10 
11## How it Works
12 
131.  The filter is added to the server's channel stack.
142.  When a request is received, the filter extracts a load balancing token from the initial metadata of the request. This token is used to associate the load report with a specific backend.
153.  The filter records various metrics throughout the lifecycle of the call, such as the number of bytes sent and received, and the call latency.
164.  When the call is complete, the filter can extract custom cost metrics from the trailing metadata of the response.
175.  The filter then uses OpenCensus to record the metrics. The metrics are tagged with the load balancing token, which allows the load balancer to correlate the metrics with the backend that handled the request.
18 
19## Files
20 
21*   `server_load_reporting_filter.h`, `server_load_reporting_filter.cc`: These files define the `ServerLoadReportingFilter` class, a server-side filter that reports load data to a load balancer.
22*   `registered_opencensus_objects.h`: This file defines the OpenCensus measures and tags that are used by the filter.
23 
24## Notes
25 
26*   This filter is an important component of gRPC's load balancing story, as it enables backends to provide real-time load information to load balancers.
27*   The filter is designed to be used with the `grpclb` load balancing policy, but it can be used with any load balancing policy that supports load reporting.
28*   The filter uses OpenCensus to record metrics. This means that the metrics can be exported to a variety of monitoring systems, such as Prometheus and Stackdriver.
29