Merge github.com:grpc/grpc into epex7

2 files changed, 29 insertions, 6 deletions

diff --git a/doc/PROTOCOL-HTTP2.md b/doc/PROTOCOL-HTTP2.md
index 68af1f2ca1..29d3cc2e76 100644
--- a/doc/PROTOCOL-HTTP2.md
+++ b/doc/PROTOCOL-HTTP2.md
@@ -24,7 +24,8 @@ Request-Headers are delivered as HTTP2 headers in HEADERS + CONTINUATION frames.
 * **Call-Definition** → Method Scheme Path TE [Authority] [Timeout] Content-Type [Message-Type] [Message-Encoding] [Message-Accept-Encoding] [User-Agent]
 * **Method** →  ":method POST"
 * **Scheme** → ":scheme "  ("http" / "https")
-* **Path** → ":path"  {_path identifying method within exposed API_}
+* **Path** → ":path" "/" Service-Name "/" {_method name_}
+* **Service-Name** → {_IDL-specific service name_}
 * **Authority** → ":authority" {_virtual host name of authority_}
 * **TE** → "te" "trailers"  # Used to detect incompatible proxies
 * **Timeout** → "grpc-timeout" TimeoutValue TimeoutUnit
@@ -51,6 +52,13 @@ Request-Headers are delivered as HTTP2 headers in HEADERS + CONTINUATION frames.
 
 HTTP2 requires that reserved headers, ones starting with ":" appear before all other headers. Additionally implementations should send **Timeout** immediately after the reserved headers and they should send the **Call-Definition** headers before sending **Custom-Metadata**.
 
+Some gRPC implementations may allow the **Path** format shown above
+to be overridden, but this functionality is strongly discouraged.
+gRPC does not go out of its way to break users that are using this kind
+of override, but we do not actively support it, and some functionality
+(e.g., service config support) will not work when the path is not of
+the form shown above.
+
 If **Timeout** is omitted a server should assume an infinite timeout. Client implementations are free to send a default minimum timeout based on their deployment requirements.
 
 **Custom-Metadata** is an arbitrary set of key-value pairs defined by the application layer. Header names starting with "grpc-" but not listed here are reserved for future GRPC use and should not be used by applications as **Custom-Metadata**.
@@ -238,10 +246,10 @@ If a detectable connection failure occurs on the client all calls will be closed
 
 ### Appendix A - GRPC for Protobuf
 
-The service interfaces declared by protobuf are easily mapped onto GRPC by code generation extensions to protoc. The following defines the mapping to be used
-
+The service interfaces declared by protobuf are easily mapped onto GRPC by
+code generation extensions to protoc. The following defines the mapping
+to be used.
 
-* **Path** → / Service-Name / {_method name_}
 * **Service-Name** → ?( {_proto package name_} "." ) {_service name_}
 * **Message-Type** → {_fully qualified proto message name_}
 * **Content-Type** → "application/grpc+proto"
diff --git a/doc/environment_variables.md b/doc/environment_variables.md
index dce434ff30..0a289ac94d 100644
--- a/doc/environment_variables.md
+++ b/doc/environment_variables.md
@@ -51,8 +51,6 @@ some configuration as environment variables that can be set.
   - flowctl - traces http2 flow control
   - op_failure - traces error information when failure is pushed onto a
     completion queue
-  - pending_tags - [debug builds only] traces still-in-progress tags on
-    completion queues
   - round_robin - traces the round_robin load balancing policy
   - glb - traces the grpclb load balancer
   - queue_pluck
@@ -63,6 +61,23 @@ some configuration as environment variables that can be set.
   - transport_security - traces metadata about secure channel establishment
   - tcp - traces bytes in and out of a channel
 
+  The following tracers will only run in binaries built in DEBUG mode. This is
+  accomplished by invoking `CONFIG=dbg make <target>`
+  - metadata - tracks creation and mutation of metadata
+  - closure - tracks closure creation, scheduling, and completion
+  - pending_tags - traces still-in-progress tags on completion queues
+  - polling - traces the selected polling engine
+  - queue_refcount
+  - error_refcount
+  - stream_refcount
+  - workqueue_refcount
+  - fd_refcount
+  - auth_context_refcount
+  - security_connector_refcount
+  - resolver_refcount
+  - lb_policy_refcount
+  - chttp2_refcount
+
   'all' can additionally be used to turn all traces on.
   Individual traces can be disabled by prefixing them with '-'.