tracing and endpoint baseclass forward from main

akka-javasdk-testkit/src/main/scala/akka/javasdk/testkit/impl/TestKitCommandContextTimed.scala

@@ -5,14 +5,13 @@
 package akka.javasdk.testkit.impl
 
 import akka.javasdk.Metadata
+import akka.javasdk.Tracing
 import akka.javasdk.impl.InternalContext
 import akka.javasdk.testkit.MockRegistry
 import akka.javasdk.timedaction.CommandContext
-import io.opentelemetry.api.OpenTelemetry
-import io.opentelemetry.api.trace.Tracer
 
 /**
- * INTERNAL API Used by the generated testkit
+ * INTERNAL API Used by the testkit
  */
 final class TestKitCommandContextTimed(metadata: Metadata, mockRegistry: MockRegistry = MockRegistry.EMPTY)
     extends AbstractTestKitContext(mockRegistry)
@@ -29,5 +28,5 @@ final class TestKitCommandContextTimed(metadata: Metadata, mockRegistry: MockReg
 
   override def metadata() = metadata
 
-  override def getTracer: Tracer = OpenTelemetry.noop().getTracer("noop")
+  override def tracing(): Tracing = TestKitTracing
 }

akka-javasdk-testkit/src/main/scala/akka/javasdk/testkit/impl/TestKitEventSourcedEntityCommandContext.scala

@@ -5,6 +5,7 @@
 package akka.javasdk.testkit.impl
 
 import akka.javasdk.Metadata
+import akka.javasdk.Tracing
 import akka.javasdk.eventsourcedentity.CommandContext
 import akka.javasdk.impl.InternalContext
 
@@ -22,6 +23,8 @@ final class TestKitEventSourcedEntityCommandContext(
     this(metadata = metadata, commandName = "stubCommandName")
   }
 
+  override def tracing(): Tracing = TestKitTracing
+
 }
 
 object TestKitEventSourcedEntityCommandContext {

akka-javasdk-testkit/src/main/scala/akka/javasdk/testkit/impl/TestKitEventSourcedEntityContext.scala

@@ -8,7 +8,7 @@ import akka.javasdk.eventsourcedentity.EventSourcedEntityContext
 import akka.javasdk.testkit.MockRegistry
 
 /**
- * INTERNAL API Used by the generated testkit
+ * INTERNAL API Used by the testkit
  */
 final class TestKitEventSourcedEntityContext(
     override val entityId: String,

akka-javasdk-testkit/src/main/scala/akka/javasdk/testkit/impl/TestKitEventSourcedEntityEventContext.scala

@@ -7,7 +7,7 @@ package akka.javasdk.testkit.impl
 import akka.javasdk.eventsourcedentity.EventContext
 
 /**
- * INTERNAL API Used by the generated testkit
+ * INTERNAL API Used by the testkit
  */
 final class TestKitEventSourcedEntityEventContext extends EventContext {
   override def entityId = "testkit-entity-id"

akka-javasdk-testkit/src/main/scala/akka/javasdk/testkit/impl/TestKitKeyValueEntityCommandContext.scala

@@ -5,12 +5,13 @@
 package akka.javasdk.testkit.impl
 
 import akka.javasdk.Metadata
+import akka.javasdk.Tracing
 import akka.javasdk.keyvalueentity.CommandContext
 import akka.javasdk.keyvalueentity.KeyValueEntityContext
 import akka.javasdk.testkit.MockRegistry
 
 /**
- * INTERNAL API Used by the generated testkit
+ * INTERNAL API Used by the testkit
  */
 final class TestKitKeyValueEntityCommandContext(
     override val entityId: String,
@@ -26,4 +27,6 @@ final class TestKitKeyValueEntityCommandContext(
     this(entityId = entityId, metadata = metadata, commandName = "stubCommandName")
   }
 
+  override def tracing(): Tracing = TestKitTracing
+
 }

akka-javasdk-testkit/src/main/scala/akka/javasdk/testkit/impl/TestKitKeyValueEntityContext.scala

@@ -8,7 +8,7 @@ import akka.javasdk.keyvalueentity.KeyValueEntityContext
 import akka.javasdk.testkit.MockRegistry
 
 /**
- * INTERNAL API Used by the generated testkit
+ * INTERNAL API Used by the testkit
  */
 final class TestKitKeyValueEntityContext(override val entityId: String, mockRegistry: MockRegistry = MockRegistry.EMPTY)
     extends AbstractTestKitContext(mockRegistry)

akka-javasdk-testkit/src/main/scala/akka/javasdk/testkit/impl/TestKitTracing.scala

@@ -0,0 +1,20 @@
+/*
+ * Copyright (C) 2021-2024 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package akka.javasdk.testkit.impl
+
+import akka.javasdk.Tracing
+import io.opentelemetry.api.trace.Span
+
+import java.util.Optional
+
+/**
+ * INTERNAL API
+ */
+object TestKitTracing extends Tracing {
+
+  override def startSpan(name: String): Optional[Span] = Optional.empty()
+
+  override def parentSpan(): Optional[Span] = Optional.empty()
+}

akka-javasdk-tests/src/test/java/akkajavasdk/components/jwt/HelloJwtEndpoint.java

@@ -8,7 +8,7 @@
 import akka.javasdk.annotations.JWT;
 import akka.javasdk.annotations.http.HttpEndpoint;
 import akka.javasdk.annotations.http.Get;
-import akka.javasdk.http.RequestContext;
+import akka.javasdk.http.AbstractHttpEndpoint;
 
 import java.util.concurrent.CompletionStage;
 import static java.util.concurrent.CompletableFuture.completedStage;
@@ -19,17 +19,12 @@
 // tag::bearer-token[]
 @HttpEndpoint("/hello")
 @JWT(validate = JWT.JwtMethodMode.BEARER_TOKEN, bearerTokenIssuers = "my-issuer-123", staticClaims = { @JWT.StaticClaim(claim = "sub", pattern = "my-subject-123")})
-public class HelloJwtEndpoint {
+public class HelloJwtEndpoint extends AbstractHttpEndpoint {
     // end::bearer-token[]
 
-    RequestContext context;
-    public HelloJwtEndpoint(RequestContext context){
-        this.context = context;
-    }
-
     @Get("/")
     public CompletionStage<String> helloWorld() {
-        var claims = context.getJwtClaims();
+        var claims = requestContext().getJwtClaims();
         var issuer = claims.issuer().get();
         var sub = claims.subject().get();
         return completedStage("issuer: " + issuer + ", subject: " + sub);

akka-javasdk-tests/src/test/java/akkajavasdk/components/jwt/MissingJwtEndpoint.java

@@ -19,6 +19,8 @@
 @HttpEndpoint("/missingjwt")
 public class MissingJwtEndpoint {
 
+    // Note: leaving this with injected request context rather than extend AbstractHttpEndpoint to keep
+    // some test coverage
     RequestContext context;
     public MissingJwtEndpoint(RequestContext context){
         this.context = context;

akka-javasdk/src/main/java/akka/javasdk/Metadata.java

@@ -213,13 +213,6 @@ public interface Metadata extends Iterable<Metadata.MetadataEntry> {
    */
   CloudEvent asCloudEvent(String id, URI source, String type);
 
-
-  /**
-   * Get the trace context associated with this request metadata.
-   * @return The trace context.
-   */
-  TraceContext traceContext();
-
   /**
    * Merge the given Metadata entries with this Metadata. If the same key is present in both, both values will be kept.
    *

akka-javasdk/src/main/java/akka/javasdk/Tracing.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright (C) 2021-2024 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package akka.javasdk;
+
+import akka.annotation.DoNotInherit;
+import io.opentelemetry.api.trace.Span;
+
+import java.util.Optional;
+
+/**
+ * Factory for manually creating open telemetry spans in addition to those automatically provided by
+ * the runtime and SDK.
+ *
+ * <p>Not for user extension. Injectable into endpoint constructors or available through component
+ * command contexts.
+ */
+@DoNotInherit
+public interface Tracing {
+  /**
+   * If tracing is enabled, create and start a new custom span with the given name, setting a parent
+   * for the span is done automatically so that the span is a child of the incoming request or
+   * component call.
+   *
+   * @return Optional of the span if tracing is enabled, empty option if tracing is not enabled.
+   */
+  Optional<Span> startSpan(String name);
+
+  /**
+   * If tracing is enabled, this returns the current parent span, to use for propagating trace
+   * parent through third party integrations. This span should only be used for observing, ending it
+   * or marking it as failed etc. is managed by the SDK and the runtime.
+   *
+   * @see {{@link #startSpan(String)}} for creating a custom span tied to some logic in a service.
+   */
+  Optional<Span> parentSpan();
+}

akka-javasdk/src/main/java/akka/javasdk/annotations/http/HttpEndpoint.java

@@ -24,6 +24,8 @@
  *   <li>{@link io.opentelemetry.api.trace.Span}</li>
  *   <li>Custom types provided by a {@link akka.javasdk.DependencyProvider} from the service setup</li>
  * </ul>
+ * <p>If the annotated class extends {@link akka.javasdk.http.AbstractHttpEndpoint} the request context
+ * is available without constructor injection.
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)

akka-javasdk/src/main/java/akka/javasdk/consumer/MessageContext.java

@@ -6,6 +6,7 @@
 
 import akka.javasdk.CloudEvent;
 import akka.javasdk.MetadataContext;
+import akka.javasdk.Tracing;
 import io.opentelemetry.api.trace.Tracer;
 
 import java.util.Optional;
@@ -19,11 +20,6 @@ public interface MessageContext extends MetadataContext {
    */
   Optional<String> eventSubject();
 
-  /**
-   * Get an OpenTelemetry tracer for the current message. This will allow for building and automatic
-   * exporting of spans.
-   *
-   * @return A tracer for the current message, if tracing is configured. Otherwise, a noops tracer.
-   */
-  Tracer getTracer();
+  /** Access to tracing for custom app specific tracing. */
+  Tracing tracing();
 }

akka-javasdk/src/main/java/akka/javasdk/eventsourcedentity/CommandContext.java

@@ -5,6 +5,7 @@
 package akka.javasdk.eventsourcedentity;
 
 import akka.javasdk.MetadataContext;
+import akka.javasdk.Tracing;
 
 /** An event sourced command context. */
 public interface CommandContext extends MetadataContext {
@@ -35,4 +36,7 @@ public interface CommandContext extends MetadataContext {
    * @return The entity id.
    */
   String entityId();
+
+  /** Access to tracing for custom app specific tracing. */
+  Tracing tracing();
 }

akka-javasdk/src/main/java/akka/javasdk/http/AbstractHttpEndpoint.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright (C) 2021-2024 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package akka.javasdk.http;
+
+import akka.annotation.InternalApi;
+
+/**
+ * Optional base class for HTTP endpoints giving access to a request context without additional constructor parameters
+ */
+abstract public class AbstractHttpEndpoint {
+
+  volatile private RequestContext context;
+
+  /**
+   * INTERNAL API
+   *
+   * @hidden
+   */
+  @InternalApi
+  final public void _internalSetRequestContext(RequestContext context) {
+    this.context = context;
+  }
+
+  /**
+   * Always available from request handling methods, not available from the constructor.
+   */
+  protected final RequestContext requestContext() {
+    if (context == null) {
+      throw new IllegalStateException("The request context can only be accessed from the request handling methods of the endpoint.");
+    }
+    return context;
+  }
+
+}