From c81a4656de1112db06bfd3fff058aee950096691 Mon Sep 17 00:00:00 2001 From: Jan Tattermusch Date: Fri, 6 Jul 2018 14:46:20 +0200 Subject: [PATCH 1/4] Add TROUBLESHOOTING.md --- TROUBLESHOOTING.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 TROUBLESHOOTING.md diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md new file mode 100644 index 00000000000..e2fd643ef41 --- /dev/null +++ b/TROUBLESHOOTING.md @@ -0,0 +1,42 @@ +# Troubleshooting gRPC + +This guide is for troubleshooting gRPC implementations based on C core library (sources for most of them are living in the `grpc/grpc` repository). + +## Enabling extra logging and traces + +Extra logging can be very useful for diagnosing problems. All gRPC implementations based on C core library support +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`). + +## 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 enable at once (use comma as separator). + +``` +# Enable debug logs for an application +GRPC_VERBOSITY=debug ./helloworld_application_using_grpc +``` + +``` +# Print info about invocations of low-level C core API. +# Note that trace logs of log level DEBUG won't be displayed +# as GRPC_VERBOSITY and GRPC_TRACE are 2 independent settings. +GRPC_TRACE=api ./helloworld_application_using_grpc +``` + +``` +# Print info from 3 different tracers, including tracing logs with log level DEBUG +GRPC_VERBOSITY=debug GRPC_TRACE=tcp,http,api ./helloworld_application_using_grpc +``` + +Known limitations: `GPRC_TRACE=tcp` is currently not implemented for Windows (you won't see any tcp traces). + +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. From a811fd63d186e02a364ccf6fcfc7a3249c1a1277 Mon Sep 17 00:00:00 2001 From: Jan Tattermusch Date: Fri, 6 Jul 2018 14:46:40 +0200 Subject: [PATCH 2/4] Update TROUBLESHOOTING.md --- TROUBLESHOOTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index e2fd643ef41..aab23f49dac 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -2,7 +2,7 @@ This guide is for troubleshooting gRPC implementations based on C core library (sources for most of them are living in the `grpc/grpc` repository). -## Enabling extra logging and traces +## Enabling extra logging and tracing Extra logging can be very useful for diagnosing problems. All gRPC implementations based on C core library support the `GRPC_VERBOSITY` and `GRPC_TRACE` environment variables that can be used to increase the amount of information From 19010459a0ceb766495598337f76b95d6950a16c Mon Sep 17 00:00:00 2001 From: Jan Tattermusch Date: Fri, 6 Jul 2018 14:52:34 +0200 Subject: [PATCH 3/4] Mention troubleshooting guide in top level README.md --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 23964e7fc63..1af9ec34f0a 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,10 @@ Please read [How to contribute](CONTRIBUTING.md) which will guide you through th the gRPC codebase. The document also contains info on how the contributing process works and contains best practices for creating contributions. +# Troubleshooting + +Sometimes things go wrong. Please check out the [Troubleshooting guide](TROUBLESHOOTING.md) if you are experiencing issues with gRPC. + # Performance See [Performance dashboard](http://performance-dot-grpc-testing.appspot.com/explore?dashboard=5636470266134528) for the performance numbers for the latest released version. From 4eb44f3dfb2b83c002100cb3b86ee0209dc66147 Mon Sep 17 00:00:00 2001 From: Jan Tattermusch Date: Mon, 9 Jul 2018 09:39:01 +0200 Subject: [PATCH 4/4] Address review comments. --- TROUBLESHOOTING.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index aab23f49dac..6ef4801528d 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -10,12 +10,12 @@ 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`). +`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). +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 enable at once (use comma as separator). ``` @@ -24,10 +24,11 @@ GRPC_VERBOSITY=debug ./helloworld_application_using_grpc ``` ``` -# Print info about invocations of low-level C core API. -# Note that trace logs of log level DEBUG won't be displayed -# as GRPC_VERBOSITY and GRPC_TRACE are 2 independent settings. -GRPC_TRACE=api ./helloworld_application_using_grpc +# Print information about invocations of low-level C core API. +# Note that trace logs of log level DEBUG won't be displayed. +# Also note that most tracers user log level INFO, so without setting +# GPRC_VERBOSITY accordingly, no traces will be printed. +GRPC_VERBOSITY=info GRPC_TRACE=api ./helloworld_application_using_grpc ``` ``` @@ -37,6 +38,6 @@ GRPC_VERBOSITY=debug GRPC_TRACE=tcp,http,api ./helloworld_application_using_grpc Known limitations: `GPRC_TRACE=tcp` is currently not implemented for Windows (you won't see any tcp traces). -Please note that the GRPC_TRACE environment variable has nothing to do with gRPC's "tracing" feature (= tracing RPCs in +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.