Introduces OpenTelemetry instrumentation for the ActiveJ framework, enabling distributed tracing and context propagation for ActiveJ-based HTTP servers

Author: kcsurapaneni

instrumentation/activej-http/javaagent/README.md

@@ -0,0 +1,50 @@
+# OpenTelemetry Java Agent for ActiveJ Framework
+
+This repository provides an OpenTelemetry Java agent specifically designed to instrument applications built on the [ActiveJ framework](https://activej.io/). The agent enables distributed tracing, context propagation, and telemetry data collection for ActiveJ-based HTTP servers, making it easier to monitor and debug applications in distributed systems.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Features](#features)
+3. [Prerequisites](#prerequisites)
+4. [Installation & Usage](#installation)
+
+---
+
+## Overview
+
+The OpenTelemetry Java agent for ActiveJ integrates with the OpenTelemetry API to provide automatic instrumentation for ActiveJ HTTP servers. It captures trace context from incoming HTTP requests, propagates it through responses, and enriches telemetry data with HTTP-specific attributes such as request methods, headers, status codes, and URL components.
+
+This agent is particularly useful for applications that rely on ActiveJ's high-performance, event-driven architecture and need observability in distributed systems.
+
+---
+
+## Features
+
+- **Distributed Tracing**: Automatically propagates trace context across service boundaries using the `traceparent` header.
+- **HTTP Attribute Extraction**: Captures detailed HTTP attributes (e.g., method, path, query, headers) for enriched telemetry data.
+- **Error Handling**: Handles exceptions and maps them to appropriate HTTP status codes for better error visibility.
+- **Compatibility**: Works seamlessly with OpenTelemetry's Java instrumentation framework and exporters (e.g., Jaeger, Zipkin, HyperDX).
+
+---
+
+## Prerequisites
+
+Before using this agent, ensure you have the following:
+
+- Java 8 or higher
+- ActiveJ framework
+- An OpenTelemetry collector or backend (e.g., Jaeger, Zipkin, HyperDX) for visualizing traces
+
+---
+
+## Installation
+
+### Using the Java Agent JAR
+
+1. Download the latest release of the OpenTelemetry Java agent JAR file.
+2. Add the agent to your application's JVM arguments:
+
+   ```bash
+   java -javaagent:/path/to/opentelemetry-java-agent.jar -jar your-application.jar
+   ```

instrumentation/activej-http/javaagent/build.gradle.kts

@@ -0,0 +1,16 @@
+plugins {
+  id("otel.javaagent-instrumentation")
+}
+
+muzzle {
+  pass {
+    group.set("io.activej:activej-http")
+    module.set("activej-http")
+
+    versions.set("[1.0,)")
+  }
+}
+
+dependencies {
+  library("io.activej:activej-http:6.0-beta2")
+}

instrumentation/activej-http/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/activejhttp/ActiveJHttpServerConnectionInstrumentation.java

@@ -0,0 +1,158 @@
+package io.opentelemetry.javaagent.instrumentation.activejhttp;
+
+import static io.opentelemetry.javaagent.bootstrap.Java8BytecodeBridge.currentContext;
+import static io.opentelemetry.javaagent.extension.matcher.AgentElementMatchers.hasSuperType;
+import static io.opentelemetry.javaagent.instrumentation.activejhttp.ActiveJHttpServerConnectionSingletons.instrumenter;
+import static net.bytebuddy.matcher.ElementMatchers.isInterface;
+import static net.bytebuddy.matcher.ElementMatchers.isMethod;
+import static net.bytebuddy.matcher.ElementMatchers.named;
+import static net.bytebuddy.matcher.ElementMatchers.not;
+import static net.bytebuddy.matcher.ElementMatchers.takesArgument;
+import static net.bytebuddy.matcher.ElementMatchers.takesArguments;
+
+import io.activej.http.AsyncServlet;
+import io.activej.http.HttpHeaders;
+import io.activej.http.HttpRequest;
+import io.activej.http.HttpResponse;
+import io.activej.promise.Promise;
+import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.context.Context;
+import io.opentelemetry.context.Scope;
+import io.opentelemetry.javaagent.extension.instrumentation.TypeInstrumentation;
+import io.opentelemetry.javaagent.extension.instrumentation.TypeTransformer;
+import net.bytebuddy.asm.Advice;
+import net.bytebuddy.description.type.TypeDescription;
+import net.bytebuddy.matcher.ElementMatcher;
+
+/**
+ * <p>This class provides instrumentation for ActiveJ HTTP server connections by applying advice to the
+ * {@code serve} method of classes that extend {@code io.activej.http.AsyncServlet}. The instrumentation is
+ * designed to integrate with OpenTelemetry for distributed tracing, capturing and propagating trace context
+ * through HTTP requests and responses.</p>
+ *
+ * @author Krishna Chaitanya Surapaneni
+ */
+public class ActiveJHttpServerConnectionInstrumentation implements TypeInstrumentation {
+
+  /**
+   * Matches classes that extend {@code io.activej.http.AsyncServlet} but are not interfaces.
+   *
+   * @return An {@code ElementMatcher} that identifies target classes for instrumentation.
+   */
+  @Override
+  public ElementMatcher<TypeDescription> typeMatcher() {
+    return hasSuperType(named("io.activej.http.AsyncServlet"))
+        .and(not(isInterface()));
+  }
+
+  /**
+   * Applies advice to the {@code serve} method of the matched classes. The advice captures trace context
+   * at the start of the method and propagates it through the response.
+   *
+   * @param transformer The {@code TypeTransformer} used to apply the advice.
+   */
+  @Override
+  public void transform(TypeTransformer transformer) {
+    transformer.applyAdviceToMethod(
+        isMethod().and(named("serve")).and(takesArguments(1)
+            .and(takesArgument(0, named("io.activej.http.HttpRequest")))),
+        this.getClass().getName() + "$ServeAdvice");
+  }
+
+  /**
+   * <p>Inner class containing the advice logic for the {@code serve} method. This class defines two methods:</p>
+   * <ul>
+   *   <li>{@code methodEnter}: Captures the trace context at the start of the method.</li>
+   *   <li>{@code methodExit}: Propagates the trace context to the response and ends the span.</li>
+   * </ul>
+   */
+  @SuppressWarnings("unused")
+  public static class ServeAdvice {
+
+    /**
+     * Advice executed at the start of the {@code serve} method. Captures the current trace context and
+     * starts a new span if tracing is enabled for the request.
+     *
+     * @param asyncServlet The {@code AsyncServlet} instance handling the request.
+     * @param request The incoming HTTP request.
+     * @param context Local variable to store the OpenTelemetry context.
+     * @param scope Local variable to store the OpenTelemetry scope.
+     * @param httpRequest Local variable to store the HTTP request.
+     */
+    @Advice.OnMethodEnter(suppress = Throwable.class)
+    public static void methodEnter(
+        @Advice.This AsyncServlet asyncServlet,
+        @Advice.Argument(0) HttpRequest request,
+        @Advice.Local("otelContext") Context context,
+        @Advice.Local("otelScope") Scope scope,
+        @Advice.Local("httpRequest") HttpRequest httpRequest) {
+      Context parentContext = currentContext();
+      httpRequest = request;
+      if (!instrumenter().shouldStart(parentContext, request)) {
+        return;
+      }
+      context = instrumenter().start(parentContext, request);
+      scope = context.makeCurrent();
+    }
+
+    /**
+     * Advice executed at the end of the {@code serve} method. Propagates the trace context to the response,
+     * handles exceptions, and ends the span.
+     *
+     * @param asyncServlet The {@code AsyncServlet} instance handling the request.
+     * @param responsePromise The promise representing the HTTP response.
+     * @param throwable Any exception thrown during the execution of the method.
+     * @param context Local variable storing the OpenTelemetry context.
+     * @param scope Local variable storing the OpenTelemetry scope.
+     * @param httpRequest Local variable storing the HTTP request.
+     */
+    @Advice.OnMethodExit(onThrowable = Throwable.class, suppress = Throwable.class)
+    public static void methodExit(
+        @Advice.This AsyncServlet asyncServlet,
+        @Advice.Return(readOnly = false) Promise<HttpResponse> responsePromise,
+        @Advice.Thrown(readOnly = false) Throwable throwable,
+        @Advice.Local("otelContext") Context context,
+        @Advice.Local("otelScope") Scope scope,
+        @Advice.Local("httpRequest") HttpRequest httpRequest) {
+      if (context == null || scope == null || httpRequest == null) {
+        return;
+      }
+      String traceId = Span.fromContext(context).getSpanContext().getTraceId();
+      String spanId = Span.fromContext(context).getSpanContext().getSpanId();
+      String traceFlags = Span.fromContext(context).getSpanContext().getTraceFlags().asHex()
+          .substring(0, 2);
+      String traceparent = String.format("00-%s-%s-%s", traceId, spanId, traceFlags);
+
+      scope.close();
+      String traceparentHeader = "traceparent";
+      if (responsePromise != null) {
+        HttpResponse httpResponse = responsePromise.getResult();
+        Throwable error = throwable;
+        if (responsePromise.isException()) {
+          error = responsePromise.getException();
+        }
+        httpResponse = ActiveJHttpServerHelper.createResponse(error, traceparent, httpResponse);
+        instrumenter().end(context, httpRequest, httpResponse, error);
+        responsePromise = Promise.of(httpResponse);
+      } else if (throwable != null) {
+        HttpResponse httpResponse = HttpResponse.builder()
+            .withCode(500)
+            .withPlainText(throwable.getMessage())
+            .withHeader(HttpHeaders.of(traceparentHeader), traceparent)
+            .build();
+        instrumenter().end(context, httpRequest, httpResponse,
+            throwable);
+        responsePromise = Promise.of(httpResponse);
+        throwable = null;
+      } else {
+        HttpResponse httpResponse = HttpResponse.notFound404()
+            .withHeader(HttpHeaders.of(traceparentHeader), traceparent)
+            .build();
+        instrumenter().end(context, httpRequest, httpResponse,
+            throwable);
+        responsePromise = Promise.of(httpResponse);
+      }
+    }
+  }
+
+}

instrumentation/activej-http/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/activejhttp/ActiveJHttpServerConnectionInstrumentationModule.java

@@ -0,0 +1,59 @@
+package io.opentelemetry.javaagent.instrumentation.activejhttp;
+
+import static java.util.Collections.singletonList;
+
+import com.google.auto.service.AutoService;
+import io.opentelemetry.javaagent.extension.instrumentation.HelperResourceBuilder;
+import io.opentelemetry.javaagent.extension.instrumentation.InstrumentationModule;
+import io.opentelemetry.javaagent.extension.instrumentation.TypeInstrumentation;
+import java.util.List;
+
+/**
+ * <p>This class is an instrumentation module for ActiveJ HTTP server connections. It integrates with
+ * OpenTelemetry to provide distributed tracing capabilities for applications using the ActiveJ HTTP server.</p>
+ *
+ * <p>The module is annotated with {@code @AutoService(InstrumentationModule.class)}, which automatically
+ * registers it as a service provider for the OpenTelemetry instrumentation framework. This allows the module
+ * to be discovered and loaded dynamically during runtime.</p>
+ *
+ * @author Krishna Chaitanya Surapaneni
+ */
+@AutoService(InstrumentationModule.class)
+public class ActiveJHttpServerConnectionInstrumentationModule extends InstrumentationModule {
+
+  /**
+   * Constructs the instrumentation module with the specified instrumentation names. These names are used to
+   * identify the instrumentation in the OpenTelemetry framework.
+   *
+   * <p>In this case, the module is identified by the names "activej-http" and "activej-http-server".</p>
+   */
+  public ActiveJHttpServerConnectionInstrumentationModule() {
+    super("activej-http", "activej-http-server");
+  }
+
+  /**
+   * Returns a list of type instrumentation's provided by this module. Each type instrumentation applies advice
+   * to specific methods or classes to capture trace context and propagate it through HTTP requests and responses.
+   *
+   * @return A list containing the {@code ActiveJHttpServerConnectionInstrumentation} instance.
+   */
+  @Override
+  public List<TypeInstrumentation> typeInstrumentations() {
+    return singletonList(new ActiveJHttpServerConnectionInstrumentation());
+  }
+
+  /**
+   * Registers helper resources required for the instrumentation. Helper resources are typically utility classes
+   * or configurations that support the instrumentation logic.
+   *
+   * <p>In this case, the {@code ActiveJHttpServerHelper} class is registered as a helper resource. This class
+   * provides utilities for creating HTTP responses with trace context.</p>
+   *
+   * @param helperResourceBuilder The builder used to register helper resources.
+   */
+  @Override
+  public void registerHelperResources(HelperResourceBuilder helperResourceBuilder) {
+    helperResourceBuilder.register(ActiveJHttpServerHelper.class.getName());
+  }
+
+}

instrumentation/activej-http/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/activejhttp/ActiveJHttpServerConnectionSingletons.java

@@ -0,0 +1,37 @@
+package io.opentelemetry.javaagent.instrumentation.activejhttp;
+
+import io.activej.http.HttpRequest;
+import io.activej.http.HttpResponse;
+import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
+import io.opentelemetry.javaagent.bootstrap.internal.JavaagentHttpServerInstrumenters;
+
+/**
+ * <p>This class provides singleton instances and utilities for ActiveJ HTTP server instrumentation. It is
+ * designed to centralize the creation and access of OpenTelemetry-related components, such as the
+ * {@code Instrumenter} used for tracing HTTP requests and responses.</p>
+ *
+ * @author Krishna Chaitanya Surapaneni
+ */
+public class ActiveJHttpServerConnectionSingletons {
+
+  /**
+   * The name of the instrumentation, used to identify this module in the OpenTelemetry framework.
+   */
+  private static final String INSTRUMENTATION_NAME = "io.opentelemetry.activej-http";
+
+  private static final Instrumenter<HttpRequest, HttpResponse> INSTRUMENTER;
+
+  static {
+    INSTRUMENTER =
+        JavaagentHttpServerInstrumenters.create(
+            INSTRUMENTATION_NAME,
+            new ActiveJHttpServerHttpAttributesGetter(),
+            ActiveJHttpServerHeaders.INSTANCE);
+  }
+
+  public static Instrumenter<HttpRequest, HttpResponse> instrumenter() {
+    return INSTRUMENTER;
+  }
+
+  private ActiveJHttpServerConnectionSingletons() {}
+}

instrumentation/activej-http/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/activejhttp/ActiveJHttpServerHeaders.java

@@ -0,0 +1,52 @@
+package io.opentelemetry.javaagent.instrumentation.activejhttp;
+
+import io.activej.http.HttpHeader;
+import io.activej.http.HttpHeaderValue;
+import io.activej.http.HttpHeaders;
+import io.activej.http.HttpRequest;
+import io.opentelemetry.context.propagation.internal.ExtendedTextMapGetter;
+import java.util.ArrayList;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+/**
+ * <p>This enum implements the {@code ExtendedTextMapGetter<HttpRequest>} interface and provides methods for
+ * extracting HTTP headers from an ActiveJ {@code HttpRequest}. It is used in the context of OpenTelemetry
+ * instrumentation to propagate trace context across service boundaries.</p>
+ *
+ * @author Krishna Chaitanya Surapaneni
+ */
+enum ActiveJHttpServerHeaders implements ExtendedTextMapGetter<HttpRequest> {
+  INSTANCE;
+
+  @Override
+  public Iterable<String> keys(HttpRequest httpRequest) {
+    return httpRequest.getHeaders().stream()
+        .map(h -> h.getKey().toString())
+        .collect(Collectors.toList());
+  }
+
+  @Override
+  public String get(HttpRequest carrier, String key) {
+    if (carrier == null) {
+      return null;
+    }
+    return carrier.getHeader(HttpHeaders.of(key));
+  }
+
+  @Override
+  public Iterator<String> getAll(HttpRequest carrier, String key) {
+    List<String> values = new ArrayList<>();
+    if (carrier != null) {
+      for (Map.Entry<HttpHeader, HttpHeaderValue> entry : carrier.getHeaders()) {
+        if (entry.getKey().toString().equalsIgnoreCase(key)) {
+          values.add(entry.getValue().toString());
+        }
+      }
+    }
+    return values.iterator();
+  }
+
+}