From a214aca7686bb8ba0a104885c4e6ed869932e38f Mon Sep 17 00:00:00 2001
From: Michael Lumish <mlumish@google.com>
Date: Fri, 18 Jun 2021 14:37:26 -0700
Subject: [PATCH] Document environment variables, particularly for logging

---
 TROUBLESHOOTING.md           | 38 +++++++++++++++++++++++
 doc/environment_variables.md | 58 ++++++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+)
 create mode 100644 TROUBLESHOOTING.md
 create mode 100644 doc/environment_variables.md

diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
new file mode 100644
index 00000000..dd5bce7a
--- /dev/null
+++ b/TROUBLESHOOTING.md
@@ -0,0 +1,38 @@
+# Troubleshooting grpc-js
+
+This guide is for troubleshooting the `grpc-js` library for Node.js
+
+## Enabling extra logging and tracing
+
+Extra logging can be very useful for diagnosing problems. `grpc-js` supporst
+the `GRPC_VERBOSITY` and `GRPC_TRACE` environment variables that can be used to increase the amount of information
+that gets printed to stderr.
+
+## GRPC_VERBOSITY
+
+`GRPC_VERBOSITY` is used to set the minimum level of log messages printed by gRPC (supported values are `DEBUG`, `INFO` and `ERROR`). If this environment variable is unset, only `ERROR` logs will be printed.
+
+## GRPC_TRACE
+
+`GRPC_TRACE` can be used to enable extra logging for some internal gRPC components. Enabling the right traces can be invaluable
+for diagnosing for what is going wrong when things aren't working as intended. Possible values for `GRPC_TRACE` are listed in [Environment Variables Overview](doc/environment_variables.md).
+Multiple traces can be enabled at once (use comma as separator).
+
+```
+# Enable debug logs for an application
+GRPC_VERBOSITY=debug ./helloworld_application_using_grpc
+```
+
+```
+# Print information about channel state changes
+GRPC_VERBOSITY=debug GRPC_TRACE=connectivity_state ./helloworld_application_using_grpc
+```
+
+```
+# Print info from 3 different tracers, including tracing logs with log level DEBUG
+GRPC_VERBOSITY=debug GRPC_TRACE=channel,subchannel,call_stream ./helloworld_application_using_grpc
+```
+
+Please note that the `GRPC_TRACE` environment variable has nothing to do with gRPC's "tracing" feature (= tracing RPCs in
+microservice environment to gain insight about how requests are processed by deployment), it is merely used to enable printing
+of extra logs.
diff --git a/doc/environment_variables.md b/doc/environment_variables.md
new file mode 100644
index 00000000..f2a32294
--- /dev/null
+++ b/doc/environment_variables.md
@@ -0,0 +1,58 @@
+# grpc-js environment variables
+
+`@grpc/grpc-js` exposes some configuration as environment variables that
+can be set.
+
+*For the legacy `grpc` library, the environment variables are documented
+[in the main gRPC repository](https://github.com/grpc/grpc/blob/master/doc/environment_variables.md)*
+
+* grpc_proxy, https_proxy, http_proxy
+  The URI of the proxy to use for HTTP CONNECT support. These variables are
+  checked in order, and the first one that has a value is used.
+
+* no_grpc_proxy, no_proxy
+  A comma separated list of hostnames to connect to without using a proxy even
+  if a proxy is set. These variables are checked in order, and the first one
+  that has a value is used.
+
+* GRPC_SSL_CIPHER_SUITES
+  A colon separated list of cipher suites to use with OpenSSL
+  Defaults to the defaults for Node.js
+
+* GRPC_DEFAULT_SSL_ROOTS_FILE_PATH
+  PEM file to load SSL roots from
+
+* GRPC_NODE_TRACE, GRPC_TRACE
+  A comma separated list of tracers that provide additional insight into how
+  grpc-js is processing requests via debug logs. Available tracers include:
+  - `call_stream` - Traces client request internals
+  - `channel` - Traces channel events
+  - `connectivity_state` - Traces channel connectivity state changes
+  - `dns_resolver` - Traces DNS resolution
+  - `pick_first` - Traces the pick first load balancing policy
+  - `proxy` - Traces proxy operations
+  - `resolving_load_balancer` - Traces the resolving load balancer
+  - `round_robin` - Traces the round robin load balancing policy
+  - `server` - Traces high-level server events
+  - `server_call` - Traces server handling of individual requests
+  - `subchannel` - Traces subchannel connectivity state and errors
+  - `subchannel_refcount` - Traces subchannel refcount changes
+
+  The following tracers are added by the `@grpc/grpc-js-xds` library:
+  - `cds_balancer` - Traces the CDS load balancing policy
+  - `eds_balancer` - Traces the EDS load balancing policy
+  - `priority` - Traces the priority load balancing policy
+  - `weighted_target` - Traces the weighted target load balancing policy
+  - `xds_client` - Traces the xDS Client
+  - `xds_cluster_manager` - Traces the xDS cluster manager load balancing policy
+  - `xds_resolver` - Traces the xDS name resolver
+
+  'all' can additionally be used to turn all traces on.
+  Individual traces can be disabled by prefixing them with '-'.
+
+* GRPC_NODE_VERBOSITY, GRPC_VERBOSITY
+  Default gRPC logging verbosity - one of:
+  - DEBUG - log all gRPC messages
+  - INFO - log INFO and ERROR message
+  - ERROR - log only errors (default)
+  - NONE - won't log any
\ No newline at end of file