| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 5 | 4 | 0% |
| Commands | 0 | 0 | 0 | — |
| Section tags | 0 | 0 | 3 | 0% |
What each file covers
Sections
0 shared · 5 only in A · 4 only in B- − Channelz
- − Overarching Purpose
- − Files and Subdirectories
- − Notes
- − DataSource Lifetime
- + gRPC C++ Agents Collaboration Guide
- + Preferred Tools & Libraries
- + Code Style & Conventions
- + About gRPC
Commands
neither file has anySection tags
0 shared · 0 only in A · 3 only in B- + code-style
- + dependencies
- + do-not
Line diff
grpc/grpc · src/core/channelz/AGENTS.md
@@ −1 @@
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.
grpc/grpc · AGENTS.md
@@ +1 @@
1# gRPC C++ Agents Collaboration Guide
2
3This document outlines conventions and best practices for AI-assisted development in the gRPC C++ codebase.
4
5## Preferred Tools & Libraries
6* Prefer gRPC types before absl.
7* Prefer std types when available, use absl types when not
8* Prefer `std::optional` over `absl::optional`
9* gRPC uses C++17, so we can't use C++20 onwards types.
10* The Python implementation cannot depend on the protobuf library, so any shared libraries must expose a C-style API that does not rely on C++ protobuf types.
11
12## Code Style & Conventions
13* `#include <grpc/support/port_platform.h>` is not required unless its macros are needed for compilation.
14* Only include headers that are actively used.
15* Abseil headers are sorted before gRPC headers.
16* For public api headers (in `include/grpc`) we use `<grpc/...>`.
17 * Example: `#include <grpc/grpc.h>`
18* Prefer explicit types over `std::pair` or `std::tuple` for return types.
19* Use `LOG(ERROR)` from `absl/log/log.h` for logging errors, never use `std::cerr` or `gpr_log`.
20* The `fuzztest.h` header is located at `fuzztest/fuzztest.h`.
21
22## About gRPC
23* gRPC uses its own macros for Bazel libraries, tests, etc. Each directory should have a `grpc_package` declaration. For libraries use `grpc_cc_library`, for tests `grpc_cc_test`.
24* Dependencies on non-gRPC libraries (like gtest or absl) are listed in the `external_deps` attribute.
25* The `:grpc` BUILD target is not allowed to depend on the C++ protobuf library, either directly or transitively.
26* Build files for implementation code are typically located in `src/core/BUILD` and `BUILD`. Do not add new `BUILD` files under the `src/` tree without explicit instruction.
27* Tests are located in `test/core` and `test/cpp` (corresponding to the `src` directories). These test directories contain their own `BUILD` files.
28* Fuzz tests use `fuzztest_main` instead of `gtest_main`.
29* When depending on a `grpc_proto_library`, the name of the `cc_library` target is the same as the `name` of the `grpc_proto_library` rule itself, not `[name]_cc_proto` as one might expect from standard Bazel `cc_proto_library` rules. The build system error messages can be misleading in this case.
30* The 'gtest' external_dep also includes 'gmock'.
31* All `upb` related build rules (`grpc_upb_proto_library`, `grpc_upb_proto_reflection_library`) for protos defined anywhere in the repository must be defined in the root `BUILD` file. They should not be placed in the `BUILD` file of the subdirectory where the proto is located.
32* Core end-to-end tests are defined in `test/core/end2end/BUILD` using the `grpc_core_end2end_test_suite` macro. This macro generates multiple `grpc_cc_test` targets by combining a configuration file (like `end2end_http2_config.cc`) with individual test implementation files located in `test/core/end2end/tests/`. The final test target name is created by appending `_test` to the `name` attribute of the macro. For example, `grpc_core_end2end_test_suite(name = "end2end_http2", ...)` generates the test target `//test/core/end2end:end2end_http2_test`.
33* Unused named parameters is a compilation failure.
34
@@ −1 +1 @@
1−# Channelz
1+# gRPC C++ Agents Collaboration Guide
22
3−This directory contains the implementation of gRPC's Channelz, which is a system for inspecting the state of gRPC channels.
3+This document outlines conventions and best practices for AI-assisted development in the gRPC C++ codebase.
44
5−## Overarching Purpose
5+## Preferred Tools & Libraries
6+* Prefer gRPC types before absl.
7+* Prefer std types when available, use absl types when not
8+* Prefer `std::optional` over `absl::optional`
9+* gRPC uses C++17, so we can't use C++20 onwards types.
10+* The Python implementation cannot depend on the protobuf library, so any shared libraries must expose a C-style API that does not rely on C++ protobuf types.
611
7−Channelz 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.
12+## Code Style & Conventions
13+* `#include <grpc/support/port_platform.h>` is not required unless its macros are needed for compilation.
14+* Only include headers that are actively used.
15+* Abseil headers are sorted before gRPC headers.
16+* For public api headers (in `include/grpc`) we use `<grpc/...>`.
17+ * Example: `#include <grpc/grpc.h>`
18+* Prefer explicit types over `std::pair` or `std::tuple` for return types.
19+* Use `LOG(ERROR)` from `absl/log/log.h` for logging errors, never use `std::cerr` or `gpr_log`.
20+* The `fuzztest.h` header is located at `fuzztest/fuzztest.h`.
821
9−## Files and Subdirectories
22+## About gRPC
23+* gRPC uses its own macros for Bazel libraries, tests, etc. Each directory should have a `grpc_package` declaration. For libraries use `grpc_cc_library`, for tests `grpc_cc_test`.
24+* Dependencies on non-gRPC libraries (like gtest or absl) are listed in the `external_deps` attribute.
25+* The `:grpc` BUILD target is not allowed to depend on the C++ protobuf library, either directly or transitively.
26+* Build files for implementation code are typically located in `src/core/BUILD` and `BUILD`. Do not add new `BUILD` files under the `src/` tree without explicit instruction.
27+* Tests are located in `test/core` and `test/cpp` (corresponding to the `src` directories). These test directories contain their own `BUILD` files.
28+* Fuzz tests use `fuzztest_main` instead of `gtest_main`.
29+* When depending on a `grpc_proto_library`, the name of the `cc_library` target is the same as the `name` of the `grpc_proto_library` rule itself, not `[name]_cc_proto` as one might expect from standard Bazel `cc_proto_library` rules. The build system error messages can be misleading in this case.
30+* The 'gtest' external_dep also includes 'gmock'.
31+* All `upb` related build rules (`grpc_upb_proto_library`, `grpc_upb_proto_reflection_library`) for protos defined anywhere in the repository must be defined in the root `BUILD` file. They should not be placed in the `BUILD` file of the subdirectory where the proto is located.
32+* Core end-to-end tests are defined in `test/core/end2end/BUILD` using the `grpc_core_end2end_test_suite` macro. This macro generates multiple `grpc_cc_test` targets by combining a configuration file (like `end2end_http2_config.cc`) with individual test implementation files located in `test/core/end2end/tests/`. The final test target name is created by appending `_test` to the `name` attribute of the macro. For example, `grpc_core_end2end_test_suite(name = "end2end_http2", ...)` generates the test target `//test/core/end2end:end2end_http2_test`.
33+* Unused named parameters is a compilation failure.
1034
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.
28−They are expected to be owned by some other transport-level object.
29−`DataSource` implementations call `SourceConstructed()` in their constructor to
30−register with a `BaseNode` and `SourceDestructing()` in their destructor to
31−unregister.
32−
33−Because `BaseNode` does not manage `DataSource` lifetime, it is unsafe for
34−`BaseNode` to call `DataSource::AddData` without holding `BaseNode::data_sources_mu_`,
35−as the `DataSource` could be destroyed by another thread concurrently.
36−This means `data_sources_mu_` must be held during any call to `AddData`.
37−Consequently, `AddData` implementations must not call back into any code that
38−acquires `data_sources_mu_`, such as `SourceConstructed`, `SourceDestructing`,
39−or other channelz rendering paths like `SerializeEntity` or `AdditionalInfo`,
40−as this will cause a deadlock.
41−
42−If this cannot be guaranteed (for example, in `Party` we might execute arbitrary
43−other promises during a `Spawn()` call, in chttp2 we need to enter the combiner
44−lock which has similar properties) a good technique is to use `EventEngine`
45−to spawn a background task to collect the data outside of the BaseNode lock.
