Finishes README files

instrumentation/dubbo-rpc/README.md

@@ -86,10 +86,29 @@ Make sure the following line is in `META-INF/dubbo/com.alibaba.dubbo.common.exte
 tracing=com.yourcompany.dubbo.TracingExtensionFactory
 ```
 
-### Custom parsing
+## Sampling and data policy
 
-The `DubboRequest` and `DubboResponse` types can be used to add Dubbo-specific
-data even with the portable parser code.
+Please read the [RPC documentation](../rpc/README.md) before proceeding, as it
+covers important topics such as which tags are added to spans, and how traces
+are sampled.
+
+### RPC model mapping
+
+As mentioned above, the RPC model types `RpcRequest` and `RpcResponse` allow
+portable sampling decisions and tag parsing.
+
+Dubbo maps to this model as follows:
+* `RpcRequest.service()` - `Invoker.url.serviceInterface`
+  * Ex. "GreeterService" for a URL "dubbo://localhost:9090?interface=brave.dubbo.GreeterService"
+* `RpcRequest.method()` - `Invocation.methodName`
+  * When absent, this falls back to the string arg[0] to the "$invoke" method.
+* `RpcResponse.errorCode()` - The constant name for `RpcException.code`.
+  * Ex. "FORBIDDEN_EXCEPTION" when `RpcException.code == 4`
+
+### Dubbo-specific model
+
+The `DubboRequest` and `DubboResponse` are available for custom sampling and
+tag parsing.
 
 Here is an example that adds default tags, and if Dubbo, Java arguments:
 ```java

instrumentation/dubbo/README.md

@@ -86,10 +86,29 @@ Make sure the following line is in `META-INF/dubbo/org.apache.dubbo.common.exten
 tracing=com.yourcompany.dubbo.TracingExtensionFactory
 ```
 
-### Custom parsing
+## Sampling and data policy
 
-The `DubboRequest` and `DubboResponse` types can be used to add Dubbo-specific
-data even with the portable parser code.
+Please read the [RPC documentation](../rpc/README.md) before proceeding, as it
+covers important topics such as which tags are added to spans, and how traces
+are sampled.
+
+### RPC model mapping
+
+As mentioned above, the RPC model types `RpcRequest` and `RpcResponse` allow
+portable sampling decisions and tag parsing.
+
+Dubbo maps to this model as follows:
+* `RpcRequest.service()` - `Invoker.url.serviceInterface`
+  * Ex. "GreeterService" for a URL "dubbo://localhost:9090?interface=brave.dubbo.GreeterService"
+* `RpcRequest.method()` - `Invocation.methodName`
+  * When absent, this falls back to the string arg[0] to the "$invoke" or "$invokeAsync" methods.
+* `RpcResponse.errorCode()` - The constant name for `RpcException.code`.
+  * Ex. "FORBIDDEN_EXCEPTION" when `RpcException.code == 4`
+
+### Dubbo-specific model
+
+The `DubboRequest` and `DubboResponse` are available for custom sampling and
+tag parsing.
 
 Here is an example that adds default tags, and if Dubbo, Java arguments:
 ```java

instrumentation/grpc/README.md

@@ -27,23 +27,46 @@ ManagedChannel channel = ManagedChannelBuilder.forAddress("localhost", serverPor
     .build();
 ```
 
-## Span data policy
-By default, the following are added to both gRPC client and server spans:
-* Span.name as the full method name: ex "helloworld.greeter/sayhello"
-* Tags/binary annotations:
-  * "grpc.status_code" when the status is not OK.
-  * "error", when there is an exception or status is not OK.
+## Sampling and data policy
 
-If you just want to control span naming policy, override `spanName` in
-your client or server parser.
+Please read the [RPC documentation](../rpc/README.md) before proceeding, as it
+covers important topics such as which tags are added to spans, and how traces
+are sampled.
 
-Ex:
+### RPC model mapping
+
+As mentioned above, the RPC model types `RpcRequest` and `RpcResponse` allow
+portable sampling decisions and tag parsing.
+
+gRPC maps to this model as follows:
+* `RpcRequest.service()` - text preceding the first slash ('/') in `MethodDescriptor.fullMethodName`
+  * Ex. "helloworld.Greeter" for a full method name "helloworld.Greeter/SayHello"
+* `RpcRequest.method()` - text following the first slash ('/') in `MethodDescriptor.fullMethodName`
+  * Ex. "SayHello" for a full method name "helloworld.Greeter/SayHello"
+* `RpcResponse.errorCode()` - `Status.Code.name()` when not `Status.isOk()`
+  * Ex. `null` for `Status.Code.OK` and `UNKNOWN` for `Status.Code.UNKNOWN`
+
+### gRPC-specific model
+
+The `GrpcRequest` and `GrpcResponse` are available for custom sampling and tag
+parsing.
+
+Here is an example that adds default tags, and if gRPC, the method type (ex "UNARY"):
 ```java
-overrideSpanName = new GrpcClientParser() {
-  @Override protected <ReqT, RespT> String spanName(MethodDescriptor<ReqT, RespT> methodDescriptor) {
-    return methodDescriptor.getType().name();
+Tag<GrpcRequest> methodType = new Tag<GrpcRequest>("grpc.method_type") {
+  @Override protected String parseValue(GrpcRequest input, TraceContext context) {
+    return input.methodDescriptor().getType().name();
   }
 };
+
+RpcRequestParser addMethodType = (req, context, span) -> {
+  RpcRequestParser.DEFAULT.parse(req, context, span);
+  if (req instanceof GrpcRequest) methodType.tag((GrpcRequest) req, span);
+};
+
+grpcTracing = GrpcTracing.create(RpcTracing.newBuilder(tracing)
+    .clientRequestParser(addMethodType)
+    .serverRequestParser(addMethodType).build());
 ```
 
 ## Message processing
@@ -81,30 +104,6 @@ managedChannelBuilder.intercept(new ClientInterceptor() {
 }, grpcTracing.newClientInterceptor());
 ```
 
-## Sampling Policy
-The default sampling policy is to use the default (trace ID) sampler for
-server and client requests.
-
-You can use an [RpcRuleSampler](../rpc/README.md) to override this based on
-gRPC service or method names.
-
-Ex. Here's a sampler that traces 100 "GetUserToken" requests per second. This
-doesn't start new traces for requests to the health check service. Other
-requests will use a global rate provided by the tracing component.
-
-```java
-import static brave.rpc.RpcRequestMatchers.methodEquals;
-import static brave.rpc.RpcRequestMatchers.serviceEquals;
-import static brave.sampler.Matchers.and;
-
-rpcTracing = rpcTracingBuilder.serverSampler(RpcRuleSampler.newBuilder()
-  .putRule(serviceEquals("grpc.health.v1.Health"), Sampler.NEVER_SAMPLE)
-  .putRule(and(serviceEquals("users.UserService"), methodEquals("GetUserToken")), RateLimitingSampler.create(100))
-  .build()).build();
-
-grpcTracing = GrpcTracing.create(rpcTracing);
-```
-
 ## gRPC Propagation Format (Census interop)
 
 gRPC defines a [binary encoded propagation format](https://github.com/census-instrumentation/opencensus-specs/blob/master/encodings/BinaryEncoding.md) which is implemented