doc/environment_variables.md

   1 gRPC environment variables
   2 --------------------------
   3
   4 gRPC C core based implementations (those contained in this repository) expose
   5 some configuration as environment variables that can be set.
   6
   7 * grpc_proxy, https_proxy, http_proxy
   8   The URI of the proxy to use for HTTP CONNECT support. These variables are
   9   checked in order, and the first one that has a value is used.
  10
  11 * no_grpc_proxy, no_proxy
  12   A comma separated list of hostnames to connect to without using a proxy even
  13   if a proxy is set. These variables are checked in order, and the first one
  14   that has a value is used.
  15
  16 * GRPC_ABORT_ON_LEAKS
  17   A debugging aid to cause a call to abort() when gRPC objects are leaked past
  18   grpc_shutdown(). Set to 1 to cause the abort, if unset or 0 it does not
  19   abort the process.
  20
  21 * GOOGLE_APPLICATION_CREDENTIALS
  22   The path to find the credentials to use when Google credentials are created
  23
  24 * GRPC_SSL_CIPHER_SUITES
  25   A colon separated list of cipher suites to use with OpenSSL
  26   Defaults to:
  27     ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384
  28
  29 * GRPC_DEFAULT_SSL_ROOTS_FILE_PATH
  30   PEM file to load SSL roots from
  31
  32 * GRPC_POLL_STRATEGY [posix-style environments only]
  33   Declares which polling engines to try when starting gRPC.
  34   This is a comma-separated list of engines, which are tried in priority order
  35   first -> last.
  36   Available polling engines include:
  37   - epoll (linux-only) - a polling engine based around the epoll family of
  38     system calls
  39   - poll - a portable polling engine based around poll(), intended to be a
  40     fallback engine when nothing better exists
  41   - legacy - the (deprecated) original polling engine for gRPC
  42
  43 * GRPC_TRACE
  44   A comma separated list of tracers that provide additional insight into how
  45   gRPC C core is processing requests via debug logs. Available tracers include:
  46   - api - traces api calls to the C core
  47   - bdp_estimator - traces behavior of bdp estimation logic
  48   - call_error - traces the possible errors contributing to final call status
  49   - cares_resolver - traces operations of the c-ares based DNS resolver
  50   - cares_address_sorting - traces operations of the c-ares based DNS
  51     resolver's resolved address sorter
  52   - cds_lb - traces cds LB policy
  53   - channel - traces operations on the C core channel stack
  54   - client_channel_call - traces client channel call batch activity
  55   - client_channel_routing - traces client channel call routing, including
  56     resolver and load balancing policy interaction
  57   - compression - traces compression operations
  58   - connectivity_state - traces connectivity state changes to channels
  59   - cronet - traces state in the cronet transport engine
  60   - executor - traces grpc's internal thread pool ('the executor')
  61   - glb - traces the grpclb load balancer
  62   - handshaker - traces handshaking state
  63   - health_check_client - traces health checking client code
  64   - http - traces state in the http2 transport engine
  65   - http2_stream_state - traces all http2 stream state mutations.
  66   - http1 - traces HTTP/1.x operations performed by gRPC
  67   - inproc - traces the in-process transport
  68   - http_keepalive - traces gRPC keepalive pings
  69   - flowctl - traces http2 flow control
  70   - op_failure - traces error information when failure is pushed onto a
  71     completion queue
  72   - pick_first - traces the pick first load balancing policy
  73   - plugin_credentials - traces plugin credentials
  74   - pollable_refcount - traces reference counting of 'pollable' objects (only
  75     in DEBUG)
  76   - priority_lb - traces priority LB policy
  77   - resource_quota - trace resource quota objects internals
  78   - ring_hash_lb - traces the ring hash load balancing policy
  79   - round_robin - traces the round_robin load balancing policy
  80   - queue_pluck
  81   - server_channel - lightweight trace of significant server channel events
  82   - secure_endpoint - traces bytes flowing through encrypted channels
  83   - subchannel - traces the connectivity state of subchannel
  84   - subchannel_pool - traces subchannel pool
  85   - timer - timers (alarms) in the grpc internals
  86   - timer_check - more detailed trace of timer logic in grpc internals
  87   - transport_security - traces metadata about secure channel establishment
  88   - tcp - traces bytes in and out of a channel
  89   - tsi - traces tsi transport security
  90   - weighted_target_lb - traces weighted_target LB policy
  91   - xds_client - traces xds client
  92   - xds_cluster_manager_lb - traces cluster manager LB policy
  93   - xds_cluster_impl_lb - traces cluster impl LB policy
  94   - xds_cluster_resolver_lb - traces xds cluster resolver LB policy
  95   - xds_resolver - traces xds resolver
  96
  97   The following tracers will only run in binaries built in DEBUG mode. This is
  98   accomplished by invoking `CONFIG=dbg make <target>`
  99   - alarm_refcount - refcounting traces for grpc_alarm structure
 100   - metadata - tracks creation and mutation of metadata
 101   - combiner - traces combiner lock state
 102   - call_combiner - traces call combiner state
 103   - closure - tracks closure creation, scheduling, and completion
 104   - fd_trace - traces fd create(), shutdown() and close() calls for channel fds.
 105     Also traces epoll fd create()/close() calls in epollex polling engine
 106     traces epoll-fd creation/close calls for epollex polling engine
 107   - pending_tags - traces still-in-progress tags on completion queues
 108   - polling - traces the selected polling engine
 109   - polling_api - traces the api calls to polling engine
 110   - subchannel_refcount
 111   - queue_refcount
 112   - error_refcount
 113   - stream_refcount
 114   - workqueue_refcount
 115   - fd_refcount
 116   - cq_refcount
 117   - auth_context_refcount
 118   - security_connector_refcount
 119   - resolver_refcount
 120   - lb_policy_refcount
 121   - chttp2_refcount
 122
 123   'all' can additionally be used to turn all traces on.
 124   Individual traces can be disabled by prefixing them with '-'.
 125
 126   'refcount' will turn on all of the tracers for refcount debugging.
 127
 128   if 'list_tracers' is present, then all of the available tracers will be
 129   printed when the program starts up.
 130
 131   Example:
 132   export GRPC_TRACE=all,-pending_tags
 133
 134 * GRPC_VERBOSITY
 135   Default gRPC logging verbosity - one of:
 136   - DEBUG - log all gRPC messages
 137   - INFO - log INFO and ERROR message
 138   - ERROR - log only errors (default)
 139   - NONE - won't log any
 140
 141 * GRPC_STACKTRACE_MINLOGLEVEL
 142   Minimum loglevel to print the stack-trace - one of DEBUG, INFO, ERROR, and NONE.
 143   NONE is a default value.
 144
 145 * GRPC_TRACE_FUZZER
 146   if set, the fuzzers will output trace (it is usually suppressed).
 147
 148 * GRPC_DNS_RESOLVER
 149   Declares which DNS resolver to use. The default is ares if gRPC is built with
 150   c-ares support. Otherwise, the value of this environment variable is ignored.
 151   Available DNS resolver include:
 152   - ares (default on most platforms except iOS, Android or Node)- a DNS
 153     resolver based around the c-ares library
 154   - native - a DNS resolver based around getaddrinfo(), creates a new thread to
 155     perform name resolution
 156
 157 * GRPC_CLIENT_CHANNEL_BACKUP_POLL_INTERVAL_MS
 158   Default: 5000
 159   Declares the interval between two backup polls on client channels. These polls
 160   are run in the timer thread so that gRPC can process connection failures while
 161   there is no active polling thread. They help reconnect disconnected client
 162   channels (mostly due to idleness), so that the next RPC on this channel won't
 163   fail. Set to 0 to turn off the backup polls.
 164
 165 * GRPC_EXPERIMENTAL_DISABLE_FLOW_CONTROL
 166   if set, flow control will be effectively disabled. Max out all values and
 167   assume the remote peer does the same. Thus we can ignore any flow control
 168   bookkeeping, error checking, and decision making
 169
 170 * grpc_cfstream
 171   set to 1 to turn on CFStream experiment. With this experiment gRPC uses CFStream API to make TCP
 172   connections. The option is only available on iOS platform and when macro GRPC_CFSTREAM is defined.