diff --git a/environment_variables.md b/environment_variables.md new file mode 100644 index 000000000000..6bc00d9f4143 --- /dev/null +++ b/environment_variables.md @@ -0,0 +1,169 @@ +# gRPC-Go Environment Variables + +This document lists the environment variables supported by the grpc-go +implementation. + +This list is intended to be exhaustive, with two deliberate exclusions: + +* Variables whose names contain `EXPERIMENTAL`. They guard features that are + still in development, and they may change behavior, change defaults, or be + removed entirely in any release without notice. +* Variables whose names contain `TEST_ONLY`. They exist to support gRPC's own + tests and are not intended for use by applications. + +Unless stated otherwise, boolean variables are case-insensitive and only the +values `true` and `false` are recognized; any other value leaves the default +in effect. + +## Logging + +See [Log Levels](Documentation/log_levels.md) for a description of the log +severities and how they are used. + +* `GRPC_GO_LOG_SEVERITY_LEVEL` + + The minimum severity of log messages written to stderr by the default + logger. One of `ERROR`, `WARNING` or `INFO` (e.g. `INFO` enables info, + warning and error logs). Defaults to `ERROR`. Has no effect if the + application replaces the default logger via + [`grpclog.SetLoggerV2`](https://pkg.go.dev/google.golang.org/grpc/grpclog#SetLoggerV2). + + Note that unlike the boolean variables above, an unrecognized value here + does not leave the default in effect: it silences the default logger + entirely, so that no message of any severity is written. `FATAL` is not a + recognized value and has this effect. Fatal-severity logging still + terminates the process in that case; only the log output is suppressed. + +* `GRPC_GO_LOG_VERBOSITY_LEVEL` + + The verbosity of info log messages, as a non-negative integer. Info logs + at verbosity levels less than or equal to this value are emitted (subject + to `GRPC_GO_LOG_SEVERITY_LEVEL` enabling info logs). Defaults to `0`. + +* `GRPC_GO_LOG_FORMATTER` + + Set to `json` to make the default logger emit log messages as JSON + objects. Any other value uses the default plain-text format. + +## Binary logging + +* `GRPC_BINARY_LOG_FILTER` + + Enables binary logging and selects which methods are logged, as described + in [gRFC A16](https://github.com/grpc/proposal/blob/master/A16-binary-logging.md). + The value is a comma-separated list of method patterns, e.g. `*` (all + methods), `package.Service/Method`, `package.Service/*`, or + `-package.Service/Method` to exclude a method. A pattern may be suffixed + with `{h[:len]}`, `{m[:len]}` or `{h[:len];m[:len]}` to limit the logged + header and message sizes. Unset or empty disables binary logging. + +## Name resolution + +* `GRPC_ENABLE_TXT_SERVICE_CONFIG` + + Whether the DNS resolver performs TXT record lookups to retrieve the + service config, as described in + [gRFC A2](https://github.com/grpc/proposal/blob/master/A2-service-configs-in-dns.md). + Defaults to `true`. + +* `GRPC_GO_IGNORE_TXT_ERRORS` + + Whether the DNS resolver ignores errors from TXT record lookups. When + `true`, TXT lookup failures are logged but resolution proceeds without a + service config; when `false`, the error is reported to the channel. + Defaults to `true`. + +## xDS + +* `GRPC_XDS_BOOTSTRAP` + + Path to a file containing the xDS bootstrap configuration in JSON format. + Takes precedence over `GRPC_XDS_BOOTSTRAP_CONFIG` if both are set. + +* `GRPC_XDS_BOOTSTRAP_CONFIG` + + The xDS bootstrap configuration itself, in JSON format. Used only if + `GRPC_XDS_BOOTSTRAP` is unset. + +## Load balancing + +* `GRPC_RING_HASH_CAP` + + The maximum ring size for the + [`ring_hash`](https://github.com/grpc/proposal/blob/master/A42-xds-ring-hash-lb-policy.md) + load balancing policy. Configured ring sizes are capped at this value. + Defaults to `4096`; values are clamped to the range `[1, 8388608]` (8M). + This does not affect config validation, which rejects ring sizes larger + than 8M. + +* `GRPC_XDS_ENDPOINT_HASH_KEY_BACKWARD_COMPAT` + + Set to `true` to restore the behavior that predates the endpoint hash key + support from + [gRFC A76](https://github.com/grpc/proposal/blob/master/A76-ring-hash-improvements.md), + ignoring the hash key from EDS endpoint metadata. Defaults to `false`. + This variable is transitional and will be removed in a future release. + +## Security + +* `GRPC_ENFORCE_ALPN_ENABLED` + + Whether TLS connections to peers that do not negotiate ALPN are rejected. + HTTP/2 requires ALPN; this variable exists only for backward compatibility + with non-compliant peers, and may be removed in a future release. Defaults + to `true`. + +* `GRPC_ALTS_MAX_CONCURRENT_HANDSHAKES` + + The maximum number of concurrent ALTS handshakes. Defaults to `100`; + values are clamped to the range `[1, 100]`. + +## Server + +* `GRPC_GO_SERVER_GOROUTINE_LABELS` + + Controls the [runtime/pprof labels](https://pkg.go.dev/runtime/pprof#Labels) + set on goroutines spawned by `grpc.Server` to handle incoming requests. + The value is a comma-separated list of `label=true|false` entries; + `grpc.method` is currently the only supported label. The values `all` and + `none` enable and disable all supported labels. Defaults to no labels. + +## GCP observability + +Used by the [gcp/observability](https://pkg.go.dev/google.golang.org/grpc/gcp/observability) +package; see its documentation for the configuration schema. + +* `GRPC_GCP_OBSERVABILITY_CONFIG_FILE` + + Path to a file containing the observability configuration in JSON format. + Takes precedence over `GRPC_GCP_OBSERVABILITY_CONFIG` if both are set. + +* `GRPC_GCP_OBSERVABILITY_CONFIG` + + The observability configuration itself, in JSON format. Used only if + `GRPC_GCP_OBSERVABILITY_CONFIG_FILE` is unset. + +* `GOOGLE_CLOUD_PROJECT` + + The GCP project ID to report observability data against. If unset, the + project ID is taken from the default credentials. + +## CSM observability + +Used by the [stats/opentelemetry/csm](https://pkg.go.dev/google.golang.org/grpc/stats/opentelemetry/csm) +package to label telemetry for Cloud Service Mesh. Each defaults to the literal +string `unknown` when unset. + +* `CSM_CANONICAL_SERVICE_NAME` + + The canonical service name of the workload, recorded as the + `csm.workload_canonical_service` label and sent in metadata exchange. + +* `CSM_WORKLOAD_NAME` + + The name of the workload, sent in metadata exchange. Only used when running + on GCE or GKE. + +* `CSM_MESH_ID` + + The mesh ID, recorded as the `csm.mesh_id` label.