RATIS-2393 Add Span Context to RaftRpcRequestProto

pom.xml

@@ -189,6 +189,9 @@
     <shaded.protobuf.version>3.25.8</shaded.protobuf.version>
     <shaded.grpc.version>1.77.1</shaded.grpc.version>
 
+    <!-- OpenTelemetry versions -->
+    <opentelemetry.version>1.59.0</opentelemetry.version>
+    <opentelemetry-semconv.version>1.40.0</opentelemetry-semconv.version>
     <!-- Test properties -->
     <maven.test.redirectTestOutputToFile>true</maven.test.redirectTestOutputToFile>
     <test.exclude.pattern>_</test.exclude.pattern>
@@ -398,7 +401,35 @@
         <artifactId>jakarta.annotation-api</artifactId>
         <version>${jakarta.annotation.version}</version>
       </dependency>
+
+      <!-- OpenTelemetry dependencies -->
+      <dependency>
+        <groupId>io.opentelemetry</groupId>
+        <artifactId>opentelemetry-api</artifactId>
+        <version>${opentelemetry.version}</version>
+      </dependency>
+      <dependency>
+        <groupId>io.opentelemetry</groupId>
+        <artifactId>opentelemetry-sdk</artifactId>
+        <version>${opentelemetry.version}</version>
+      </dependency>
+      <dependency>
+        <groupId>io.opentelemetry</groupId>
+        <artifactId>opentelemetry-sdk-testing</artifactId>
+        <version>${opentelemetry.version}</version>
+      </dependency>
+      <dependency>
+        <groupId>io.opentelemetry.semconv</groupId>
+        <artifactId>opentelemetry-semconv</artifactId>
+        <version>${opentelemetry-semconv.version}</version>
+      </dependency>
+      <dependency>
+        <groupId>io.opentelemetry</groupId>
+        <artifactId>opentelemetry-context</artifactId>
+        <version>${opentelemetry.version}</version>
+      </dependency>
     </dependencies>
+
   </dependencyManagement>
 
   <build>

ratis-client/src/main/java/org/apache/ratis/client/impl/ClientProtoUtils.java

@@ -128,6 +128,7 @@ static RaftRpcRequestProto.Builder toRaftRpcRequestProtoBuilder(RaftClientReques
 
     Optional.ofNullable(request.getSlidingWindowEntry()).ifPresent(b::setSlidingWindowEntry);
     Optional.ofNullable(request.getRoutingTable()).map(RoutingTable::toProto).ifPresent(b::setRoutingTable);
+    Optional.ofNullable(request.getSpanContext()).ifPresent(b::setSpanContext);
 
     return b.setCallId(request.getCallId())
         .setToLeader(request.isToLeader())
@@ -188,6 +189,9 @@ static RaftClientRequest toRaftClientRequest(RaftClientRequestProto p) {
     if (request.hasSlidingWindowEntry()) {
       b.setSlidingWindowEntry(request.getSlidingWindowEntry());
     }
+    if (request.hasSpanContext()) {
+      b.setSpanContext(request.getSpanContext());
+    }
     return b.setClientId(ClientId.valueOf(request.getRequestorId()))
         .setGroupId(ProtoUtils.toRaftGroupId(request.getRaftGroupId()))
         .setCallId(request.getCallId())

ratis-common/pom.xml

@@ -38,6 +38,31 @@
       <artifactId>slf4j-api</artifactId>
     </dependency>
 
+    <dependency>
+      <groupId>io.opentelemetry</groupId>
+      <artifactId>opentelemetry-api</artifactId>
+    </dependency>
+
+    <dependency>
+      <groupId>io.opentelemetry</groupId>
+      <artifactId>opentelemetry-sdk</artifactId>
+    </dependency>
+
+    <dependency>
+      <groupId>io.opentelemetry.semconv</groupId>
+      <artifactId>opentelemetry-semconv</artifactId>
+    </dependency>
+
+    <dependency>
+      <groupId>io.opentelemetry</groupId>
+      <artifactId>opentelemetry-context</artifactId>
+    </dependency>
+
+    <dependency>
+      <groupId>io.opentelemetry</groupId>
+      <artifactId>opentelemetry-sdk-testing</artifactId>
+    </dependency>
+
     <dependency>
       <groupId>org.junit.jupiter</groupId>
       <artifactId>junit-jupiter-api</artifactId>

ratis-common/src/main/java/org/apache/ratis/protocol/RaftClientRequest.java

@@ -24,6 +24,7 @@
 import org.apache.ratis.proto.RaftProtos.ReadRequestTypeProto;
 import org.apache.ratis.proto.RaftProtos.ReplicationLevel;
 import org.apache.ratis.proto.RaftProtos.SlidingWindowEntry;
+import org.apache.ratis.proto.RaftProtos.SpanContextProto;
 import org.apache.ratis.proto.RaftProtos.StaleReadRequestTypeProto;
 import org.apache.ratis.proto.RaftProtos.WatchRequestTypeProto;
 import org.apache.ratis.proto.RaftProtos.WriteRequestTypeProto;
@@ -305,6 +306,7 @@ public static class Builder {
     private SlidingWindowEntry slidingWindowEntry;
     private RoutingTable routingTable;
     private long timeoutMs;
+    private SpanContextProto spanContext;
 
     public RaftClientRequest build() {
       return new RaftClientRequest(this);
@@ -366,6 +368,11 @@ public Builder setTimeoutMs(long timeoutMs) {
       this.timeoutMs = timeoutMs;
       return this;
     }
+
+    public Builder setSpanContext(SpanContextProto spanContext) {
+      this.spanContext = spanContext;
+      return this;
+    }
   }
 
   public static Builder newBuilder() {
@@ -397,6 +404,8 @@ public static RaftClientRequest toWriteRequest(RaftClientRequest r, Message mess
 
   private final boolean toLeader;
 
+  private final SpanContextProto spanContext;
+
   /** Construct a request for sending to the given server. */
   protected RaftClientRequest(ClientId clientId, RaftPeerId serverId, RaftGroupId groupId, long callId, Type type) {
     this(newBuilder()
@@ -429,6 +438,7 @@ private RaftClientRequest(Builder b) {
     this.slidingWindowEntry = b.slidingWindowEntry;
     this.routingTable = b.routingTable;
     this.timeoutMs = b.timeoutMs;
+    this.spanContext = b.spanContext;
   }
 
   @Override
@@ -472,6 +482,10 @@ public long getTimeoutMs() {
     return timeoutMs;
   }
 
+  public SpanContextProto getSpanContext() {
+    return spanContext;
+  }
+
   @Override
   public String toString() {
     return super.toString() + ", seq=" + ProtoUtils.toString(slidingWindowEntry) + ", "

ratis-common/src/main/java/org/apache/ratis/trace/ClientRequestSpanBuilder.java

@@ -0,0 +1,87 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.ratis.trace;
+
+import static org.apache.ratis.trace.RatisAttributes.ATTR_CALL_ID;
+import static org.apache.ratis.trace.RatisAttributes.ATTR_CLIENT_INVOCATION_ID;
+import static org.apache.ratis.trace.RatisAttributes.ATTR_MEMBER_ID;
+
+import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.api.trace.SpanBuilder;
+import io.opentelemetry.api.trace.SpanKind;
+import io.opentelemetry.context.Context;
+import org.apache.ratis.proto.RaftProtos.SpanContextProto;
+import org.apache.ratis.protocol.RaftClientRequest;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.function.Supplier;
+
+/**
+ * Construct {@link Span} instances originating from the client request.
+ */
+public class ClientRequestSpanBuilder implements Supplier<Span> {
+
+  private String name;
+  private Context remoteContext;
+  private final Map<AttributeKey<?>, Object> attributes = new HashMap<>();
+
+  @Override
+  public Span get() {
+    return build();
+  }
+
+  public ClientRequestSpanBuilder setAttributes(final RaftClientRequest request, final String memberId) {
+    remoteContext = TraceUtils.extractContextFromProto(request.getSpanContext());
+    setRequestAttributes(attributes, request, memberId);
+    return this;
+  }
+
+  public ClientRequestSpanBuilder setSpanName(final String spanName) {
+    this.name = spanName;
+    return this;
+  }
+
+  public ClientRequestSpanBuilder setRemoteContext(final SpanContextProto spanContextProto) {
+    remoteContext = TraceUtils.extractContextFromProto(spanContextProto);
+    return this;
+  }
+
+
+  @SuppressWarnings("unchecked")
+  public Span build() {
+    final SpanBuilder builder = TraceUtils.getGlobalTracer().spanBuilder(name).setParent(remoteContext)
+        .setSpanKind(SpanKind.SERVER);
+    attributes.forEach((k, v) -> builder.setAttribute((AttributeKey<? super Object>) k, v));
+    return builder.startSpan();
+  }
+
+  /**
+   * Static utility method that performs the primary logic of this builder. It is visible to other
+   * classes in this package so that other builders can use this functionality as a mix-in.
+   * @param attributes the attributes map to be populated.
+   */
+  static void setRequestAttributes(final Map<AttributeKey<?>, Object> attributes,
+      final RaftClientRequest request, final String memberId) {
+    attributes.put(ATTR_CLIENT_INVOCATION_ID, String.valueOf(request.getClientId()));
+    attributes.put(ATTR_CALL_ID, String.valueOf(request.getCallId()));
+    attributes.put(ATTR_MEMBER_ID, memberId);
+  }
+
+}

ratis-common/src/main/java/org/apache/ratis/trace/RatisAttributes.java

@@ -0,0 +1,36 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.ratis.trace;
+
+import io.opentelemetry.api.common.AttributeKey;
+
+/**
+ * The constants in this class correspond with the guidance outlined by the OpenTelemetry <a href=
+ * "https://github.com/open-telemetry/semantic-conventions">Semantic
+ * Conventions</a>.
+ */
+public final class RatisAttributes {
+  public static final AttributeKey<String> ATTR_CLIENT_INVOCATION_ID =
+      AttributeKey.stringKey("raft.client.invocation.id");
+  public static final AttributeKey<String> ATTR_MEMBER_ID = AttributeKey.stringKey("raft.member.id");
+  public static final AttributeKey<String> ATTR_CALL_ID = AttributeKey.stringKey("raft.call.id");
+
+
+  private RatisAttributes() {
+  }
+}