Documentation: add documentation for non-experimental environment variables - #9227

Are you intending to say that the documented list here is exhaustive other than EXPERIMENTAL flags?

Yes, that's the intent, and your question caught that it wasn't actually true. I swept every os.Getenv/os.LookupEnv call across the main module and all submodules and found four non-experimental variables missing: GOOGLE_CLOUD_PROJECT (read by gcp/observability, alongside the two config variables already listed) and CSM_CANONICAL_SERVICE_NAME, CSM_WORKLOAD_NAME, CSM_MESH_ID (read by stats/opentelemetry/csm). All four are now documented.

I also made the exhaustiveness claim explicit rather than implied, and broadened the exclusion note to cover TEST_ONLY names as well as EXPERIMENTAL ones. That accounts for GRPC_TEST_ONLY_GOOGLE_C2P_RESOLVER_TRAFFIC_DIRECTOR_URI, which exists for gRPC's own tests. The 15 variables already in the list all check out against the code, with no stale entries.

The FATAL log level is also supported by the default logger's environment variable parser (it maps to fatalLog in grpclog). We should include FATAL in the list of supported severity levels to make the documentation complete.

Not taking this one, as FATAL isn't a recognized value. The parser at grpclog/loggerv2.go:66 has cases for only "", ERROR, WARNING and INFO (plus lowercase forms) and no default, so FATAL matches nothing and leaves infoW, warningW and errorW at io.Discard. Since grpclog/internal/loggerv2.go:258 derives the fatal writer as fatalW := errorW, setting FATAL produces no output at any severity rather than fatal-only logging.

It does point at a real gap in the doc, though: an unrecognized value silences the default logger entirely instead of falling back to the ERROR default, which is worth calling out. I've added a note to that effect, including that Fatal* calls still exit the process in that case since exit(1) runs unconditionally after the (discarded) print.

We should mention the behaviour in case of an unrecognized value, there are no default fallbacks.

Added. There is no fallback: an unrecognized value silences the logger entirely rather than leaving ERROR in effect, so no message of any severity is written. Called that out explicitly, along with FATAL being one such value.

This applies to other flags as well, so may be we can move it to common section above for the entire Logging block.

Moved. The Logging preamble now says the whole section configures the default logger and has no effect once the application installs its own via SetLoggerV2, and that the variables are read once at package init. Dropped the per variable mention.

The repo officially supports two more environment variables that this list
misses: HTTPS_PROXY and NO_PROXY (case-insensitive), documented in
Documentation/proxy.md and read via
http.ProxyFromEnvironment in
internal/resolver/delegatingresolver/delegatingresolver.go:42 (the lookup is
made with an https-scheme request, so HTTP_PROXY is not consulted, and
localhost targets are always excluded). Since this list claims to be
exhaustive, suggest adding a short Proxy section linking to
Documentation/proxy.md — the same pattern the Logging section uses with
log_levels.md. Alternatively, a third exclusion bullet could cover variables
whose semantics are defined outside gRPC, which would also account for
GOOGLE_APPLICATION_CREDENTIALS and the OTEL_* resource variables read
indirectly by the observability plugins.

Did both, since they cover different cases.

Added a Proxy section for HTTPS_PROXY and NO_PROXY linking to Documentation/proxy.md, noting that the name matching is case-insensitive, that the lookup uses an https-scheme request so HTTP_PROXY is never consulted, and that a localhost host bypasses the proxy whether or not it is listed in NO_PROXY.

Also added a third exclusion bullet for variables whose semantics are defined outside gRPC and are only read through a dependency, which covers GOOGLE_APPLICATION_CREDENTIALS and the OTEL_* ones. The proxy variables did not seem to belong there since the behaviour around them is gRPC's own and already documented in the repo.

Nit: matching is strings.EqualFold(..., "json") (grpclog/loggerv2.go:81),
so JSON/Json etc. also work — could say "Set to json (case-insensitive)"
to mirror the precision elsewhere in the doc.

Fixed, now reads "Set to json (case-insensitive)".

This description is inverted relative to the code
(internal/resolver/dns/dns_resolver.go:293-303 and handleDNSError at
:278-291). When true (the default), the TXT lookup error is dropped and
lookupTXT returns nil immediately — nothing is logged; the logger.Info call
is inside handleDNSError, which for TXT errors is only reached in the false
branch. And when false, only transient errors reach the channel: permanent
DNS errors (e.g. a missing TXT record) are suppressed by handleDNSError
returning nil, so resolution still proceeds without a service config.

You are right, it was backwards. lookupTXT returns nil immediately when TXTErrIgnore is set, so nothing is logged in the true case, and handleDNSError (which holds the logger.Info call) is only reached in the false branch, where it also swallows permanent errors and returns nil.

Taken your wording almost verbatim.

nit: the limit is enforced per direction — separate client and server
semaphores are each sized to this value
(credentials/alts/internal/handshaker/handshaker.go:62-63), so a process that
performs both client- and server-side handshakes can have up to twice this
number in flight. Might be worth a sentence.

Added. Confirmed there are two separate semaphores, clientHandshakes and serverHandshakes, each sized to the variable, so a process doing both can have up to twice this many in flight.

Small precision gap: this variable is only consulted when the observability
config does not itself specify project_id —
ensureProjectIDInObservabilityConfig (gcp/observability/config.go:143-146)
is the sole caller of fetchDefaultProjectID. So the precedence is: config
project_id → GOOGLE_CLOUD_PROJECT → default credentials. Suggest: "Only
consulted when the observability config does not specify project_id. If this
variable is also unset, the project ID is taken from the default credentials."

Added. ensureProjectIDInObservabilityConfig only calls fetchDefaultProjectID when config.ProjectID is empty, so the precedence is config project_id, then this variable, then the default credentials. Worded it that way.