Adds parsers and handlers for Rpc abstraction and ports Dubbo and gRPC

instrumentation/benchmarks/src/main/java/brave/grpc/GrpcPropagationBenchmarks.java

@@ -66,13 +66,16 @@ public class GrpcPropagationBenchmarks {
       .build();
 
   static final Propagation<String> b3 = B3Propagation.FACTORY.get();
-  static final Injector<GrpcClientRequest> b3Injector = b3.injector(GrpcClientRequest.SETTER);
-  static final Extractor<GrpcServerRequest> b3Extractor = b3.extractor(GrpcServerRequest.GETTER);
+  static final Injector<GrpcClientRequest> b3Injector =
+    b3.injector(GrpcClientRequest::propagationField);
+  static final Extractor<GrpcServerRequest> b3Extractor =
+    b3.extractor(GrpcServerRequest::propagationField);
 
   static final Propagation<String> both = GrpcPropagation.create(B3Propagation.get());
-  static final Injector<GrpcClientRequest> bothInjector = both.injector(GrpcClientRequest.SETTER);
+  static final Injector<GrpcClientRequest> bothInjector =
+    both.injector(GrpcClientRequest::propagationField);
   static final Extractor<GrpcServerRequest> bothExtractor =
-    both.extractor(GrpcServerRequest.GETTER);
+    both.extractor(GrpcServerRequest::propagationField);
 
   static final TraceContext context = TraceContext.newBuilder()
     .traceIdHigh(HexCodec.lowerHexToUnsignedLong("67891233abcdef01"))

instrumentation/dubbo-rpc/README.md

@@ -85,3 +85,38 @@ Make sure the following line is in `META-INF/dubbo/com.alibaba.dubbo.common.exte
 ```
 tracing=com.yourcompany.dubbo.TracingExtensionFactory
 ```
+
+## Sampling and data policy
+
+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
+rpcTracing = rpcTracingBuilder
+  .clientRequestParser((req, context, span) -> {
+     RpcRequestParser.DEFAULT.parse(req, context, span);
+     if (req instanceof DubboRequest) {
+       tagArguments(((DubboRequest) req).invocation().getArguments());
+     }
+  }).build();
+```

instrumentation/dubbo-rpc/src/main/java/brave/dubbo/rpc/DubboClientRequest.java

@@ -14,26 +14,13 @@
 package brave.dubbo.rpc;
 
 import brave.Span;
-import brave.propagation.Propagation.Setter;
 import brave.rpc.RpcClientRequest;
 import com.alibaba.dubbo.common.URL;
 import com.alibaba.dubbo.rpc.Invocation;
 import com.alibaba.dubbo.rpc.Invoker;
 import java.util.Map;
 
-// intentionally not yet public until we add tag parsing functionality
 final class DubboClientRequest extends RpcClientRequest implements DubboRequest {
-  static final Setter<DubboClientRequest, String> SETTER =
-    new Setter<DubboClientRequest, String>() {
-      @Override public void put(DubboClientRequest request, String key, String value) {
-        request.propagationField(key, value);
-      }
-
-      @Override public String toString() {
-        return "DubboClientRequest::propagationField";
-      }
-    };
-
   final Invoker<?> invoker;
   final Invocation invocation;
   final Map<String, String> attachments;
@@ -61,25 +48,24 @@ final class DubboClientRequest extends RpcClientRequest implements DubboRequest
   }
 
   /**
-   * Returns the method name of the invocation or the first string arg of an "$invoke" or
-   * "$invokeAsync" method.
+   * Returns the method name of the invocation or the first string arg of an "$invoke" method.
    */
   @Override public String method() {
     return DubboParser.method(invocation);
   }
 
   /**
-   * Returns the {@link URL#getServiceInterface() service interface} of the invocation.
+   * Returns the {@link URL#getServiceInterface() service interface} of the invoker.
    */
   @Override public String service() {
-    return DubboParser.service(invocation);
+    return DubboParser.service(invoker);
   }
 
-  boolean parseRemoteIpAndPort(Span span) {
+  @Override public boolean parseRemoteIpAndPort(Span span) {
     return DubboParser.parseRemoteIpAndPort(span);
   }
 
-  void propagationField(String keyName, String value) {
+  @Override protected void propagationField(String keyName, String value) {
     attachments.put(keyName, value);
   }
 }

instrumentation/dubbo-rpc/src/main/java/brave/dubbo/rpc/DubboClientResponse.java

@@ -13,13 +13,12 @@
  */
 package brave.dubbo.rpc;
 
-import brave.Response;
-import brave.Span;
 import brave.internal.Nullable;
+import brave.rpc.RpcClientResponse;
 import com.alibaba.dubbo.rpc.Result;
 import com.alibaba.dubbo.rpc.RpcException;
 
-final class DubboClientResponse extends Response implements DubboResponse {
+final class DubboClientResponse extends RpcClientResponse implements DubboResponse {
   final DubboClientRequest request;
   @Nullable final Result result;
   @Nullable final Throwable error;
@@ -40,10 +39,6 @@ final class DubboClientResponse extends Response implements DubboResponse {
     return result;
   }
 
-  @Override public Span.Kind spanKind() {
-    return Span.Kind.CLIENT;
-  }
-
   @Override public DubboClientRequest request() {
     return request;
   }
@@ -53,7 +48,7 @@ final class DubboClientResponse extends Response implements DubboResponse {
   }
 
   /** Returns the string form of the {@link RpcException#getCode()} */
-  String errorCode() {
+  @Override public String errorCode() {
     return DubboParser.errorCode(error);
   }
 }

instrumentation/dubbo-rpc/src/main/java/brave/dubbo/rpc/DubboParser.java

@@ -45,13 +45,11 @@ final class DubboParser {
   }
 
   /**
-   * Returns the {@link URL#getServiceInterface() service interface} of the invocation.
+   * Returns the {@link URL#getServiceInterface() service interface} of the invoker.
    *
    * <p>This was chosen as the {@link URL#getServiceName() service name} is deprecated for it.
    */
-  static @Nullable String service(Invocation invocation) {
-    Invoker<?> invoker = invocation.getInvoker();
-    if (invoker == null) return null;
+  @Nullable static String service(Invoker<?> invoker) {
     URL url = invoker.getUrl();
     if (url == null) return null;
     String service = url.getServiceInterface();
@@ -63,8 +61,8 @@ static boolean parseRemoteIpAndPort(Span span) {
     InetSocketAddress remoteAddress = rpcContext.getRemoteAddress();
     if (remoteAddress == null) return false;
     return span.remoteIpAndPort(
-      Platform.get().getHostString(remoteAddress),
-      remoteAddress.getPort()
+        Platform.get().getHostString(remoteAddress),
+        remoteAddress.getPort()
     );
   }
 

instrumentation/dubbo-rpc/src/main/java/brave/dubbo/rpc/DubboRequest.java

@@ -15,6 +15,7 @@
 
 import brave.rpc.RpcClientRequest;
 import brave.rpc.RpcServerRequest;
+import brave.rpc.RpcTracing;
 import com.alibaba.dubbo.rpc.Invocation;
 import com.alibaba.dubbo.rpc.Invoker;
 
@@ -35,12 +36,15 @@
  * <p>Note: Do not implement this type directly. An implementation will be
  * either as {@link RpcClientRequest} or an {@link RpcServerRequest}.
  *
+ * @see RpcTracing#clientRequestParser()
+ * @see RpcTracing#serverRequestParser()
+ * @see DubboResponse
  * @since 5.12
  */
 // Note: Unlike Apache Dubbo, Alibaba Dubbo is Java 1.6+.
 // This means we cannot add default methods later. However, Alibaba Dubbo is
 // deprecated, so there should not be cause to add methods later.
-interface DubboRequest { // TODO: make public after #999
+public interface DubboRequest {
   Invoker<?> invoker();
 
   Invocation invocation();

instrumentation/dubbo-rpc/src/main/java/brave/dubbo/rpc/DubboResponse.java

@@ -14,6 +14,9 @@
 package brave.dubbo.rpc;
 
 import brave.internal.Nullable;
+import brave.rpc.RpcClientResponse;
+import brave.rpc.RpcServerResponse;
+import brave.rpc.RpcTracing;
 import com.alibaba.dubbo.rpc.Result;
 
 /**
@@ -33,9 +36,15 @@
  *   }).build();
  * }</pre>
  *
+ * <p>Note: Do not implement this type directly. An implementation will be
+ * either as {@link RpcClientResponse} or an {@link RpcServerResponse}.
+ *
+ * @see RpcTracing#clientResponseParser()
+ * @see RpcTracing#serverResponseParser()
+ * @see DubboResponse
  * @since 5.12
  */
-interface DubboResponse { // TODO: make public after #999
+public interface DubboResponse {
   DubboRequest request();
 
   @Nullable Result result();

instrumentation/dubbo-rpc/src/main/java/brave/dubbo/rpc/DubboServerRequest.java

@@ -14,25 +14,12 @@
 package brave.dubbo.rpc;
 
 import brave.Span;
-import brave.propagation.Propagation.Getter;
 import brave.rpc.RpcServerRequest;
 import com.alibaba.dubbo.common.URL;
 import com.alibaba.dubbo.rpc.Invocation;
 import com.alibaba.dubbo.rpc.Invoker;
 
-// intentionally not yet public until we add tag parsing functionality
 final class DubboServerRequest extends RpcServerRequest implements DubboRequest {
-  static final Getter<DubboServerRequest, String> GETTER =
-    new Getter<DubboServerRequest, String>() {
-      @Override public String get(DubboServerRequest request, String key) {
-        return request.propagationField(key);
-      }
-
-      @Override public String toString() {
-        return "DubboServerRequest::propagationField";
-      }
-    };
-
   final Invoker<?> invoker;
   final Invocation invocation;
 
@@ -64,17 +51,17 @@ final class DubboServerRequest extends RpcServerRequest implements DubboRequest
   }
 
   /**
-   * Returns the {@link URL#getServiceInterface() service interface} of the invocation.
+   * Returns the {@link URL#getServiceInterface() service interface} of the invoker.
    */
   @Override public String service() {
-    return DubboParser.service(invocation);
+    return DubboParser.service(invoker);
   }
 
-  boolean parseRemoteIpAndPort(Span span) {
+  @Override public boolean parseRemoteIpAndPort(Span span) {
     return DubboParser.parseRemoteIpAndPort(span);
   }
 
-  String propagationField(String keyName) {
+  @Override protected String propagationField(String keyName) {
     return invocation.getAttachment(keyName);
   }
 }

instrumentation/dubbo-rpc/src/main/java/brave/dubbo/rpc/DubboServerResponse.java

@@ -13,13 +13,12 @@
  */
 package brave.dubbo.rpc;
 
-import brave.Response;
-import brave.Span;
 import brave.internal.Nullable;
+import brave.rpc.RpcServerResponse;
 import com.alibaba.dubbo.rpc.Result;
 import com.alibaba.dubbo.rpc.RpcException;
 
-final class DubboServerResponse extends Response implements DubboResponse {
+final class DubboServerResponse extends RpcServerResponse implements DubboResponse {
   final DubboServerRequest request;
   @Nullable final Result result;
   @Nullable final Throwable error;
@@ -32,10 +31,6 @@ final class DubboServerResponse extends Response implements DubboResponse {
     this.error = error;
   }
 
-  @Override public Span.Kind spanKind() {
-    return Span.Kind.SERVER;
-  }
-
   @Override public Result result() {
     return result;
   }
@@ -53,7 +48,7 @@ final class DubboServerResponse extends Response implements DubboResponse {
   }
 
   /** Returns the string form of the {@link RpcException#getCode()} */
-  String errorCode() {
+  @Override public String errorCode() {
     return DubboParser.errorCode(error);
   }
 }