AGENTS.md

1# gRPC Core Debugging & Tracing
2 
3This directory contains the implementation of the gRPC tracing library.
4 
5## Overarching Purpose
6 
7The tracing library provides a mechanism for logging trace messages from different parts of the gRPC stack. This can be useful for debugging and performance analysis. It is designed to be lightweight and should have a minimal impact on performance when it is disabled.
8 
9## How to Add a New Trace Flag
10 
111.  Add a new entry to the `trace_flags.yaml` file. The entry should include the name of the trace flag and a brief description of what it does.
122.  Run the `tools/codegen/core/generate_trace_flags_main.cc` script to regenerate the `trace_flags.h` and `trace_flags.cc` files.
133.  Use the `GRPC_TRACE_FLAG_ENABLED` macro to check if the trace flag is enabled, and the `GRPC_TRACE_LOG`, `GRPC_TRACE_DLOG`, or `GRPC_TRACE_VLOG` macros to log trace messages.
14 
15## Files
16 
17*   **`trace.h`**: The public interface to the tracing library.
18*   **`trace_impl.h`**: The implementation of the tracing library.
19*   **`trace_flags.yaml`**: The definition of all of the available trace flags.
20 
21## Major Classes
22 
23*   `grpc_core::TraceFlag`: Represents a single trace flag.
24 
25## Major Macros
26 
27*   **`GRPC_TRACE_FLAG_ENABLED(tracer)`**: Checks if a trace flag is enabled. `tracer` is the name of the trace flag, without the `grpc_` prefix.
28*   **`GRPC_TRACE_LOG(tracer, level)`**: Logs a trace message if a trace flag is enabled. This is equivalent to `LOG_IF(level, GRPC_TRACE_FLAG_ENABLED(tracer))`.
29*   **`GRPC_TRACE_DLOG(tracer, level)`**: Logs a trace message in debug builds if a trace flag is enabled. This is equivalent to `DLOG_IF(level, GRPC_TRACE_FLAG_ENABLED(tracer))`.
30*   **`GRPC_TRACE_VLOG(tracer, level)`**: Logs a verbose trace message if a trace flag is enabled. This is equivalent to `if (GRPC_TRACE_FLAG_ENABLED(tracer)) VLOG(level)`.
31 
32## Notes
33 
34*   Trace flags can be enabled at runtime by setting the `GRPC_TRACE` environment variable to a comma-separated list of trace flag names. For example, `GRPC_TRACE=api,http` will enable the `api` and `http` trace flags.
35*   The special value `all` can be used to enable all trace flags.
36*   Prefixing a trace flag with a `-` will disable it. For example, `GRPC_TRACE=all,-http` will enable all trace flags except for `http`.
37*   The tracing library is a powerful tool for debugging gRPC. It can be used to trace the execution of an RPC, to inspect the contents of messages, and to identify performance bottlenecks.
38