AGENTS.md

1# Channelz
2 
3This directory contains the implementation of gRPC's Channelz, which is a system for inspecting the state of gRPC channels.
4 
5## Overarching Purpose
6 
7Channelz provides a way to get detailed information about the state of gRPC channels, including things like the number of calls, the amount of data sent and received, and the status of the underlying transport. This information can be used for debugging, monitoring, and performance tuning.
8 
9## Files and Subdirectories
10 
11- **`channelz.h` / `channelz.cc`**: Defines the `Channelz` class, which is the main class for Channelz.
12- **`channel_trace.h` / `channel_trace.cc`**: Defines the `ChannelTrace` class, which is used to trace events on a channel.
13- **`channelz_registry.h` / `channelz_registry.cc`**: Defines the `ChannelzRegistry` class, which is a registry for all Channelz entities.
14- **`property_list.h` / `property_list.cc`**: Defines a list of properties that can be attached to a Channelz entity.
15- **`ztrace_collector.h`**: A collector for Channelz trace events.
16- **`v2tov1/`**: Code for converting between Channelz v2 and v1 formats.
17- **`zviz/`**: A web-based viewer for Channelz data.
18 
19## Notes
20 
21- Channelz is a powerful tool for understanding the behavior of gRPC channels.
22- It can be used to debug a wide variety of problems, from simple connectivity issues to complex performance problems.
23- The Channelz data can be accessed through a variety of tools, including the `grpc_cli` command-line tool and the web-based viewer in the `zviz` directory.
24 
25## DataSource Lifetime
26 
27`DataSource` objects are not owned by the `BaseNode` they are attached to.
28They are expected to be owned by some other transport-level object.
29`DataSource` implementations call `SourceConstructed()` in their constructor to
30register with a `BaseNode` and `SourceDestructing()` in their destructor to
31unregister.
32 
33Because `BaseNode` does not manage `DataSource` lifetime, it is unsafe for
34`BaseNode` to call `DataSource::AddData` without holding `BaseNode::data_sources_mu_`,
35as the `DataSource` could be destroyed by another thread concurrently.
36This means `data_sources_mu_` must be held during any call to `AddData`.
37Consequently, `AddData` implementations must not call back into any code that
38acquires `data_sources_mu_`, such as `SourceConstructed`, `SourceDestructing`,
39or other channelz rendering paths like `SerializeEntity` or `AdditionalInfo`,
40as this will cause a deadlock.
41 
42If this cannot be guaranteed (for example, in `Party` we might execute arbitrary
43other promises during a `Spawn()` call, in chttp2 we need to enter the combiner
44lock which has similar properties) a good technique is to use `EventEngine`
45to spawn a background task to collect the data outside of the BaseNode lock.