diff --git a/azure-functions-java-opentelemetry/README.md b/azure-functions-java-opentelemetry/README.md index 27d2b59..885f704 100644 --- a/azure-functions-java-opentelemetry/README.md +++ b/azure-functions-java-opentelemetry/README.md @@ -2,12 +2,12 @@ # Azure Functions OpenTelemetry Integration (Java) -This library integrates [OpenTelemetry](https://opentelemetry.io/) with Java-based Azure Functions. It automatically: +This library provides [OpenTelemetry](https://opentelemetry.io/) integration for Java-based Azure Functions when running with an OpenTelemetry agent. It automatically: -1. Initializes the OpenTelemetry SDK on-demand. -2. Merges resource attributes for Azure Functions (e.g., function name, region, resource group). -3. Optionally configures Azure Monitor if the environment variable `APPLICATIONINSIGHTS_CONNECTION_STRING` is set. -4. Provides a middleware that creates a new span for each function invocation. +1. Creates spans for each function invocation with proper trace context propagation. +2. Provides convenient helper methods for creating custom spans. + +**Note:** This library requires an OpenTelemetry Java agent to be present. It does not initialize or configure the OpenTelemetry SDK itself. --- @@ -15,8 +15,8 @@ This library integrates [OpenTelemetry](https://opentelemetry.io/) with Java-bas * [Key Classes](#key-classes) * [Installation](#installation) +* [Prerequisites](#prerequisites) * [How It Works](#how-it-works) -* [Azure Monitor Integration (Optional)](#azure-monitor-integration-optional) * [Usage in Azure Functions](#usage-in-azure-functions) * [Local Development](#local-development) * [Testing](#testing) @@ -26,20 +26,12 @@ This library integrates [OpenTelemetry](https://opentelemetry.io/) with Java-bas ## Key Classes 1. **`FunctionsOpenTelemetry`** + * Provides helper methods like `startSpan(...)` which work with the global OpenTelemetry instance configured by the agent. + * Accepts either an OpenTelemetry `Context` or an Azure Functions `TraceContext`. - * Provides a static `sdk()` method to lazily initialize the SDK. - * Offers helper methods like `startSpan(...)` which accept either an OpenTelemetry `Context` or an Azure Functions `TraceContext`. - -2. **`FunctionsResourceDetector`** - - * Detects standard Azure Functions environment variables (e.g. `WEBSITE_SITE_NAME`) and builds resource attributes like `service.name`, `cloud.provider`, etc. - * Fallbacks to `java-function-app` for `service.name` if not running on Azure. - -3. **`OpenTelemetryInvocationMiddleware`** - - * Implements Azure Functions middleware (`com.microsoft.azure.functions.internal.spi.middleware.Middleware`). - * Initializes a static OTel SDK during when it is loaded in by the Java Worker during Worker Initialization. - * Starts a span on each function invocation and propagates existing trace context from the Azure Functions host. +2. **`OpenTelemetryInvocationMiddleware`** + * Implements Azure Functions middleware (`com.microsoft.azure.functions.internal.spi.middleware.Middleware`). + * Starts a span for each function invocation and propagates trace context from the Azure Functions host. --- @@ -59,52 +51,75 @@ Add the library to your `pom.xml`: --- -## How It Works +## Prerequisites -1. **Lazy Initialization** - When you first call `FunctionsOpenTelemetry.sdk()`, it constructs an `OpenTelemetrySdk` via `AutoConfiguredOpenTelemetrySdk.builder()`. +This library requires an OpenTelemetry Java agent to be present and configured. The agent handles: - * Merges Azure Functions resource attributes. - * Registers a shutdown hook to cleanly close the tracer provider on JVM exit. +* OpenTelemetry SDK initialization and configuration +* Exporter setup (e.g., OTLP, Azure Monitor, Jaeger) +* Instrumentation of HTTP clients, databases, etc. -2. **Span Creation** +To run your Azure Functions with the agent: - * `FunctionsOpenTelemetry.startSpan(...)` can start spans for custom logic. - * `OpenTelemetryInvocationMiddleware` automatically starts a span for each function invocation and tags it with `faas.invocation_id` and `faas.name`. +```bash +# Download the OpenTelemetry Java agent +wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar ---- +# Run with the agent +func start --java-options="-javaagent:opentelemetry-javaagent.jar" +``` + +For Azure deployment, configure the agent via application settings: +``` +JAVA_OPTS=-javaagent:opentelemetry-javaagent.jar +OTEL_SERVICE_NAME=my-function-app +OTEL_EXPORTER_OTLP_ENDPOINT=https://your-collector-endpoint +``` -## Azure Monitor Integration (Optional) +--- -If you set `APPLICATIONINSIGHTS_CONNECTION_STRING` and also set `JAVA_APPLICATIONINSIGHTS_ENABLE_TELEMETRY=true`, this library tries to reflectively call `com.azure.monitor.opentelemetry.autoconfigure.AzureMonitorAutoConfigure`. +## How It Works -* If that class is found, Azure Monitor is configured to export traces, metrics, and logs. -* If not present, the initialization logs a warning and continues without Azure Monitor. +1. **Agent Detection** + The library checks if an OpenTelemetry agent has configured the global OpenTelemetry instance. If no agent is detected, it throws an `IllegalStateException`. -This approach avoids a hard compile-time dependency on the Azure Monitor library. +2. **Span Creation** + * `OpenTelemetryInvocationMiddleware` automatically creates a span for each function invocation with `faas.invocation_id` and `faas.name` attributes. + * `FunctionsOpenTelemetry.startSpan(...)` provides convenient methods for creating custom spans. --- ## Usage in Azure Functions -1. **Middleware Registration** - - * Azure Functions Java Worker auto-discovers middleware. Make sure `OpenTelemetryInvocationMiddleware` is on your classpath. - * Once loaded, each invocation automatically has a new span, parented by any incoming trace context from the host. +1. **Automatic Middleware** + The middleware is automatically registered and creates spans for all function invocations. 2. **Custom Spans** - ```java - Span customSpan = FunctionsOpenTelemetry.startSpan( - "myTracer", - "mySpan", - someTraceContext, // or null - SpanKind.INTERNAL // or null -> defaults to INTERNAL - ); - try (Scope scope = customSpan.makeCurrent()) { - // do your work - } finally { - customSpan.end(); + import com.microsoft.azure.functions.opentelemetry.FunctionsOpenTelemetry; + import io.opentelemetry.api.trace.Span; + import io.opentelemetry.api.trace.SpanKind; + import io.opentelemetry.context.Scope; + + @FunctionName("MyFunction") + public HttpResponseMessage run( + @HttpTrigger(name = "req", methods = {HttpMethod.GET}) HttpRequestMessage> request, + final ExecutionContext context) { + + // Create a custom span + Span customSpan = FunctionsOpenTelemetry.startSpan( + "business-logic", + context.getTraceContext(), + SpanKind.INTERNAL + ); + + try (Scope scope = customSpan.makeCurrent()) { + // Your business logic here + customSpan.setAttribute("user.id", "12345"); + return request.createResponseBuilder(HttpStatus.OK).body("Hello World").build(); + } finally { + customSpan.end(); + } } ``` @@ -112,9 +127,44 @@ This approach avoids a hard compile-time dependency on the Azure Monitor library ## Local Development -* If `WEBSITE_SITE_NAME` is not set, `FunctionsResourceDetector` defaults `service.name` to `"java-function-app"`. -* All other Azure-specific attributes (e.g., region, resource group) remain unset if the corresponding environment variables do not exist. -* You do **not** need to set Azure Monitor or any other exporters unless you want local telemetry exporting. +* Make sure to run with the OpenTelemetry agent even during local development. +* Configure the agent with appropriate exporters for local testing (e.g., console exporter). + +--- + +## Testing + +This repo includes unit tests under `src/test/java/...`. Key points: + +1. **Agent Simulation** + Tests may need to mock the global OpenTelemetry instance since the agent won't be present during unit testing. + +2. **Disabling Default Exporters** + We disable exporters in tests to avoid configuration issues: + + ```java + @BeforeAll + static void setUp() { + System.setProperty("otel.metrics.exporter", "none"); + System.setProperty("otel.traces.exporter", "none"); + System.setProperty("otel.logs.exporter", "none"); + } + ``` + +3. **Middleware Testing** + We use [Mockito](https://site.mockito.org/) to mock `MiddlewareContext` and verify the middleware behavior. + +--- + +## Migration from SDK-based Versions + +If you were using a previous version that initialized its own SDK: + +1. **Remove manual initialization** - Delete any calls to `FunctionsOpenTelemetry.initialize()` +2. **Add OpenTelemetry agent** - Configure your deployment to use the OpenTelemetry Java agent +3. **Move configuration to agent** - Move exporter and instrumentation configuration to agent properties (environment variables starting with `OTEL_`) + +The span creation APIs remain unchanged, so your custom instrumentation code should continue to work. --- @@ -151,4 +201,4 @@ This repo includes simple unit tests under `src/test/java/...`. Key points: This allows verifying resource attributes without polluting global environment variables. 3. **Middleware Testing** - We use [Mockito](https://site.mockito.org/) to mock `MiddlewareContext` and confirm `OpenTelemetryInvocationMiddleware` properly invokes the chain and handles exceptions. \ No newline at end of file + We use [Mockito](https://site.mockito.org/) to mock `MiddlewareContext` and confirm `OpenTelemetryInvocationMiddleware` properly invokes the chain and handles exceptions. diff --git a/azure-functions-java-opentelemetry/pom.xml b/azure-functions-java-opentelemetry/pom.xml index e1f4af3..e8623a1 100644 --- a/azure-functions-java-opentelemetry/pom.xml +++ b/azure-functions-java-opentelemetry/pom.xml @@ -14,16 +14,16 @@ com.microsoft.azure.functions azure-functions-java-opentelemetry - 1.0.0 + 1.1.0 jar Microsoft Azure Functions Java OpenTelemetry Support - This package contains classes/interfaces for advanced SDK-based type bindings for Azure Functions Java Worker. + OpenTelemetry integration for Azure Functions Java runtime. Requires an OpenTelemetry agent. https://azure.microsoft.com/en-us/services/functions UTF-8 - 5.13.0 + 5.9.3 @@ -33,9 +33,6 @@ repo - - - com.microsoft.azure.functions @@ -49,17 +46,16 @@ 1.1.0 provided + io.opentelemetry opentelemetry-api 1.49.0 - provided io.opentelemetry - opentelemetry-sdk-extension-autoconfigure + opentelemetry-sdk-common 1.49.0 - provided org.junit.jupiter @@ -73,6 +69,18 @@ ${junit.jupiter.version} test + + org.junit.jupiter + junit-jupiter-engine + ${junit.jupiter.version} + test + + + org.junit.platform + junit-platform-launcher + 1.9.3 + test + org.mockito mockito-core @@ -95,6 +103,44 @@ maven-javadoc-plugin 3.4.1 + + org.apache.maven.plugins + maven-surefire-plugin + 3.0.0-M8 + + + org.apache.maven.plugins + maven-shade-plugin + 3.4.1 + + + package + + shade + + + + + io.opentelemetry + com.microsoft.azure.functions.opentelemetry.shaded.otel + + + + + *:* + + META-INF/*.SF + META-INF/*.DSA + META-INF/*.RSA + + + + true + ${project.build.directory}/dependency-reduced-pom.xml + + + + diff --git a/azure-functions-java-opentelemetry/samples/java-otel-cascade/.gitignore b/azure-functions-java-opentelemetry/samples/java-otel-cascade/.gitignore new file mode 100644 index 0000000..f508cf9 --- /dev/null +++ b/azure-functions-java-opentelemetry/samples/java-otel-cascade/.gitignore @@ -0,0 +1,38 @@ +# Build output +target/ +*.class + +# Log file +*.log + +# BlueJ files +*.ctxt + +# Mobile Tools for Java (J2ME) +.mtj.tmp/ + +# Package Files # +*.jar +*.war +*.ear +*.zip +*.tar.gz +*.rar + +# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml +hs_err_pid* + +# IDE +.idea/ +*.iml +.settings/ +.project +.classpath + +# macOS +.DS_Store + +# Azure Functions +local.settings.json +bin/ +obj/ diff --git a/azure-functions-java-opentelemetry/samples/java-otel-cascade/.vscode/extensions.json b/azure-functions-java-opentelemetry/samples/java-otel-cascade/.vscode/extensions.json new file mode 100644 index 0000000..8a0255c --- /dev/null +++ b/azure-functions-java-opentelemetry/samples/java-otel-cascade/.vscode/extensions.json @@ -0,0 +1,6 @@ +{ + "recommendations": [ + "ms-azuretools.vscode-azurefunctions", + "vscjava.vscode-java-debug" + ] +} \ No newline at end of file diff --git a/azure-functions-java-opentelemetry/samples/java-otel-cascade/.vscode/launch.json b/azure-functions-java-opentelemetry/samples/java-otel-cascade/.vscode/launch.json new file mode 100644 index 0000000..c071177 --- /dev/null +++ b/azure-functions-java-opentelemetry/samples/java-otel-cascade/.vscode/launch.json @@ -0,0 +1,13 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Attach to Java Functions", + "type": "java", + "request": "attach", + "hostName": "127.0.0.1", + "port": 5005, + "preLaunchTask": "func: host start" + } + ] +} \ No newline at end of file diff --git a/azure-functions-java-opentelemetry/samples/java-otel-cascade/.vscode/settings.json b/azure-functions-java-opentelemetry/samples/java-otel-cascade/.vscode/settings.json new file mode 100644 index 0000000..fd8ecb7 --- /dev/null +++ b/azure-functions-java-opentelemetry/samples/java-otel-cascade/.vscode/settings.json @@ -0,0 +1,8 @@ +{ + "azureFunctions.javaBuildTool": "maven", + "azureFunctions.deploySubpath": "target/azure-functions/java-otel-cascade-1756925571105", + "azureFunctions.projectLanguage": "Java", + "azureFunctions.projectRuntime": "~4", + "debug.internalConsoleOptions": "neverOpen", + "azureFunctions.preDeployTask": "package (functions)" +} \ No newline at end of file diff --git a/azure-functions-java-opentelemetry/samples/java-otel-cascade/.vscode/tasks.json b/azure-functions-java-opentelemetry/samples/java-otel-cascade/.vscode/tasks.json new file mode 100644 index 0000000..3876333 --- /dev/null +++ b/azure-functions-java-opentelemetry/samples/java-otel-cascade/.vscode/tasks.json @@ -0,0 +1,25 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "type": "func", + "label": "func: host start", + "command": "host start", + "problemMatcher": "$func-java-watch", + "isBackground": true, + "options": { + "cwd": "${workspaceFolder}/target/azure-functions/java-otel-cascade-1756925571105" + }, + "dependsOn": "package (functions)" + }, + { + "label": "package (functions)", + "command": "mvn clean package", + "type": "shell", + "group": { + "kind": "build", + "isDefault": true + } + } + ] +} \ No newline at end of file diff --git a/azure-functions-java-opentelemetry/samples/java-otel-cascade/host.json b/azure-functions-java-opentelemetry/samples/java-otel-cascade/host.json new file mode 100644 index 0000000..851e3cb --- /dev/null +++ b/azure-functions-java-opentelemetry/samples/java-otel-cascade/host.json @@ -0,0 +1,8 @@ +{ + "version": "2.0", + "extensionBundle": { + "id": "Microsoft.Azure.Functions.ExtensionBundle", + "version": "[4.*, 5.0.0)" + }, + "telemetryMode": "OpenTelemetry" +} diff --git a/azure-functions-java-opentelemetry/samples/java-otel-cascade/local.settings.json b/azure-functions-java-opentelemetry/samples/java-otel-cascade/local.settings.json new file mode 100644 index 0000000..5ee1327 --- /dev/null +++ b/azure-functions-java-opentelemetry/samples/java-otel-cascade/local.settings.json @@ -0,0 +1,24 @@ +{ + "IsEncrypted": false, + "Values": { + "AzureWebJobsStorage": "UseDevelopmentStorage=true", + "FUNCTIONS_WORKER_RUNTIME": "java", + "JAVA_ENABLE_OPENTELEMETRY": "true", + "APPLICATIONINSIGHTS_ENABLE_AGENT": "false", + "WEBSITE_SITE_NAME": "my-test-site", + "REGION_NAME": "my-test-region", + "WEBSITE_RESOURCE_GROUP": "my-test-resource-group", + "WEBSITE_OWNER_NAME": "my-test-owner-name", + "WEBSITE_SLOT_NAME": "my-test-slot", + "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otlp.nr-data.net", + "OTEL_RESOURCE_ATTRIBUTES": "testattribute=newtest", + "OTEL_SERVICE_NAME": "my-test-java-function", + "OTEL_EXPORTER_OTLP_HEADERS": "api-key=**", + "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf", + "OTEL_LOGS_EXPORTER": "otlp", + "OTEL_METRICS_EXPORTER": "otlp", + "OTEL_TRACES_EXPORTER": "otlp", + "ENABLE_INTERNAL_OTEL_SDK": "false", + "JAVA_OPTS": "-javaagent:\"..\\..\\..\\opentelemetry-javaagent.jar\"" + } +} \ No newline at end of file diff --git a/azure-functions-java-opentelemetry/samples/java-otel-cascade/opentelemetry-javaagent.jar b/azure-functions-java-opentelemetry/samples/java-otel-cascade/opentelemetry-javaagent.jar new file mode 100644 index 0000000..638ec88 Binary files /dev/null and b/azure-functions-java-opentelemetry/samples/java-otel-cascade/opentelemetry-javaagent.jar differ diff --git a/azure-functions-java-opentelemetry/samples/java-otel-cascade/pom.xml b/azure-functions-java-opentelemetry/samples/java-otel-cascade/pom.xml new file mode 100644 index 0000000..affd75f --- /dev/null +++ b/azure-functions-java-opentelemetry/samples/java-otel-cascade/pom.xml @@ -0,0 +1,113 @@ + + + 4.0.0 + + com.function + java-otel-cascade + 1.0-SNAPSHOT + jar + + Azure Java Functions + + + UTF-8 + 11 + 1.39.0 + 3.1.0 + java-otel-cascade-1756925571105 + + + + + com.microsoft.azure.functions + azure-functions-java-library + ${azure.functions.java.library.version} + + + com.microsoft.azure.functions + azure-functions-java-opentelemetry + 1.1.0 + + + + org.junit.jupiter + junit-jupiter + 5.4.2 + test + + + org.mockito + mockito-core + 2.23.4 + test + + + + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.8.1 + + ${java.version} + ${java.version} + ${project.build.sourceEncoding} + + + + com.microsoft.azure + azure-functions-maven-plugin + ${azure.functions.maven.plugin.version} + + + ${functionAppName} + + java-functions-group + + + westus + + java-functions-app-service-plan + + + + + + + + + windows + 17 + + + + FUNCTIONS_EXTENSION_VERSION + ~4 + + + + + + package-functions + + package + + + + + + + maven-clean-plugin + 3.1.0 + + + + obj + + + + + + + diff --git a/azure-functions-java-opentelemetry/samples/java-otel-cascade/src/main/java/com/function/Function.java b/azure-functions-java-opentelemetry/samples/java-otel-cascade/src/main/java/com/function/Function.java new file mode 100644 index 0000000..fba78b6 --- /dev/null +++ b/azure-functions-java-opentelemetry/samples/java-otel-cascade/src/main/java/com/function/Function.java @@ -0,0 +1,43 @@ +package com.function; + +import com.microsoft.azure.functions.ExecutionContext; +import com.microsoft.azure.functions.HttpMethod; +import com.microsoft.azure.functions.HttpRequestMessage; +import com.microsoft.azure.functions.HttpResponseMessage; +import com.microsoft.azure.functions.HttpStatus; +import com.microsoft.azure.functions.annotation.AuthorizationLevel; +import com.microsoft.azure.functions.annotation.FunctionName; +import com.microsoft.azure.functions.annotation.HttpTrigger; + +import java.util.Optional; + +/** + * Azure Functions with HTTP Trigger. + */ +public class Function { + /** + * This function listens at endpoint "/api/HttpExample". Two ways to invoke it using "curl" command in bash: + * 1. curl -d "HTTP Body" {your host}/api/HttpExample + * 2. curl "{your host}/api/HttpExample?name=HTTP%20Query" + */ + @FunctionName("HttpExample") + public HttpResponseMessage run( + @HttpTrigger( + name = "req", + methods = {HttpMethod.GET, HttpMethod.POST}, + authLevel = AuthorizationLevel.ANONYMOUS) + HttpRequestMessage> request, + final ExecutionContext context) { + context.getLogger().info("Java HTTP trigger processed a request: B"); + + // Parse query parameter + final String query = request.getQueryParameters().get("name"); + final String name = request.getBody().orElse(query); + + if (name == null) { + return request.createResponseBuilder(HttpStatus.BAD_REQUEST).body("Please pass a name on the query string or in the request body").build(); + } else { + return request.createResponseBuilder(HttpStatus.OK).body("Hello, " + name).build(); + } + } +} diff --git a/azure-functions-java-opentelemetry/samples/java-otel-cascade/src/main/java/com/function/HttpTriggerCaller.java b/azure-functions-java-opentelemetry/samples/java-otel-cascade/src/main/java/com/function/HttpTriggerCaller.java new file mode 100644 index 0000000..dcd39f3 --- /dev/null +++ b/azure-functions-java-opentelemetry/samples/java-otel-cascade/src/main/java/com/function/HttpTriggerCaller.java @@ -0,0 +1,71 @@ +package com.function; + +import java.net.URI; +import java.net.URLEncoder; +import java.net.http.HttpClient; +import java.net.http.HttpRequest; +import java.net.http.HttpResponse; +import java.nio.charset.StandardCharsets; +import java.util.*; + +import com.microsoft.azure.functions.annotation.*; +import com.microsoft.azure.functions.opentelemetry.FunctionsOpenTelemetry; +import com.microsoft.azure.functions.*; +import java.time.Duration; + +/** + * Azure Functions with HTTP Trigger. + */ +public class HttpTriggerCaller { + /** + * This function listens at endpoint "/api/HttpTriggerCaller". Two ways to invoke it using "curl" command in bash: + * 1. curl -d "HTTP Body" {your host}/api/HttpTriggerCaller + * 2. curl {your host}/api/HttpTriggerCaller?name=HTTP%20Query + */ + @FunctionName("HttpTriggerCaller") + public HttpResponseMessage run( + @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage> request, + final ExecutionContext context) { + var log = context.getLogger(); + + return runImpl(request, context, log); + } + + private HttpResponseMessage runImpl(HttpRequestMessage> request, ExecutionContext context, java.util.logging.Logger log) { + Map azureContext = FunctionsOpenTelemetry.getCurrentAzureContext(context.getFunctionName(), context.getInvocationId()); + log.info("Java HTTP trigger processed a request: A."); + String name = request.getQueryParameters().getOrDefault("name", "world"); + + // Base URL for B (override in Azure with env var if you like) + String base = Optional.ofNullable(System.getenv("B_URL")) + .orElse("http://localhost:7071"); + + String url = base + "/api/httpexample?name=" + URLEncoder.encode(name, StandardCharsets.UTF_8); + + try { + var client = HttpClient.newBuilder() + .connectTimeout(Duration.ofSeconds(5)) + .build(); + + var httpReq = HttpRequest.newBuilder(URI.create(url)) + .timeout(Duration.ofSeconds(10)) + .GET() + .build(); + + log.info("Making HTTP call to: " + url); + var resp = client.send(httpReq, HttpResponse.BodyHandlers.ofString()); + log.info("Received response with status: " + resp.statusCode()); + + return request.createResponseBuilder(HttpStatus.OK) + .header("Content-Type", "text/plain") + .body("A → B (" + url + ")\nB responded: " + resp.statusCode()) + .build(); + + } catch (Exception e) { + log.severe("Call to B failed: " + e); + return request.createResponseBuilder(HttpStatus.INTERNAL_SERVER_ERROR) + .body("A failed to call B: " + e.getMessage()) + .build(); + } + } +} diff --git a/azure-functions-java-opentelemetry/samples/java-otel-cascade/src/test/java/com/function/FunctionTest.java b/azure-functions-java-opentelemetry/samples/java-otel-cascade/src/test/java/com/function/FunctionTest.java new file mode 100644 index 0000000..6313251 --- /dev/null +++ b/azure-functions-java-opentelemetry/samples/java-otel-cascade/src/test/java/com/function/FunctionTest.java @@ -0,0 +1,53 @@ +package com.function; + +import com.microsoft.azure.functions.*; +import org.mockito.invocation.InvocationOnMock; +import org.mockito.stubbing.Answer; + +import java.util.*; +import java.util.logging.Logger; + +import org.junit.jupiter.api.Test; +import static org.junit.jupiter.api.Assertions.*; +import static org.mockito.ArgumentMatchers.*; +import static org.mockito.Mockito.*; + + +/** + * Unit test for Function class. + */ +public class FunctionTest { + /** + * Unit test for HttpTriggerJava method. + */ + @Test + public void testHttpTriggerJava() throws Exception { + // Setup + @SuppressWarnings("unchecked") + final HttpRequestMessage> req = mock(HttpRequestMessage.class); + + final Map queryParams = new HashMap<>(); + queryParams.put("name", "Azure"); + doReturn(queryParams).when(req).getQueryParameters(); + + final Optional queryBody = Optional.empty(); + doReturn(queryBody).when(req).getBody(); + + doAnswer(new Answer() { + @Override + public HttpResponseMessage.Builder answer(InvocationOnMock invocation) { + HttpStatus status = (HttpStatus) invocation.getArguments()[0]; + return new HttpResponseMessageMock.HttpResponseMessageBuilderMock().status(status); + } + }).when(req).createResponseBuilder(any(HttpStatus.class)); + + final ExecutionContext context = mock(ExecutionContext.class); + doReturn(Logger.getGlobal()).when(context).getLogger(); + + // Invoke + final HttpResponseMessage ret = new Function().run(req, context); + + // Verify + assertEquals(HttpStatus.OK, ret.getStatus()); + } +} diff --git a/azure-functions-java-opentelemetry/samples/java-otel-cascade/src/test/java/com/function/HttpResponseMessageMock.java b/azure-functions-java-opentelemetry/samples/java-otel-cascade/src/test/java/com/function/HttpResponseMessageMock.java new file mode 100644 index 0000000..d69fb03 --- /dev/null +++ b/azure-functions-java-opentelemetry/samples/java-otel-cascade/src/test/java/com/function/HttpResponseMessageMock.java @@ -0,0 +1,81 @@ +package com.function; + +import com.microsoft.azure.functions.*; + +import java.util.Map; +import java.util.HashMap; + +/** + * The mock for HttpResponseMessage, can be used in unit tests to verify if the + * returned response by HTTP trigger function is correct or not. + */ +public class HttpResponseMessageMock implements HttpResponseMessage { + private int httpStatusCode; + private HttpStatusType httpStatus; + private Object body; + private Map headers; + + public HttpResponseMessageMock(HttpStatusType status, Map headers, Object body) { + this.httpStatus = status; + this.httpStatusCode = status.value(); + this.headers = headers; + this.body = body; + } + + @Override + public HttpStatusType getStatus() { + return this.httpStatus; + } + + @Override + public int getStatusCode() { + return httpStatusCode; + } + + @Override + public String getHeader(String key) { + return this.headers.get(key); + } + + @Override + public Object getBody() { + return this.body; + } + + public static class HttpResponseMessageBuilderMock implements HttpResponseMessage.Builder { + private Object body; + private int httpStatusCode; + private Map headers = new HashMap<>(); + private HttpStatusType httpStatus; + + public Builder status(HttpStatus status) { + this.httpStatusCode = status.value(); + this.httpStatus = status; + return this; + } + + @Override + public Builder status(HttpStatusType httpStatusType) { + this.httpStatusCode = httpStatusType.value(); + this.httpStatus = httpStatusType; + return this; + } + + @Override + public HttpResponseMessage.Builder header(String key, String value) { + this.headers.put(key, value); + return this; + } + + @Override + public HttpResponseMessage.Builder body(Object body) { + this.body = body; + return this; + } + + @Override + public HttpResponseMessage build() { + return new HttpResponseMessageMock(this.httpStatus, this.headers, this.body); + } + } +} diff --git a/azure-functions-java-opentelemetry/src/main/java/com/microsoft/azure/functions/opentelemetry/FunctionsOpenTelemetry.java b/azure-functions-java-opentelemetry/src/main/java/com/microsoft/azure/functions/opentelemetry/FunctionsOpenTelemetry.java index b29e8d3..ce79202 100644 --- a/azure-functions-java-opentelemetry/src/main/java/com/microsoft/azure/functions/opentelemetry/FunctionsOpenTelemetry.java +++ b/azure-functions-java-opentelemetry/src/main/java/com/microsoft/azure/functions/opentelemetry/FunctionsOpenTelemetry.java @@ -6,154 +6,217 @@ import io.opentelemetry.api.trace.SpanKind; import io.opentelemetry.context.Context; import io.opentelemetry.context.propagation.TextMapGetter; -import io.opentelemetry.sdk.OpenTelemetrySdk; -import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk; -import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdkBuilder; - -import java.lang.reflect.Method; -import java.util.logging.Level; -import java.util.logging.Logger; - - +import io.opentelemetry.sdk.resources.Resource; +import java.util.HashMap; +import java.util.Map; + +/** + * OpenTelemetry integration for Azure Functions. + * + *

Provides span creation methods and context attribute utilities that work with OpenTelemetry agents. + * This library assumes an OpenTelemetry agent is present and configured. + */ public final class FunctionsOpenTelemetry { + /** Default tracer name for Azure Functions spans. */ + private static final String DEFAULT_TRACER_NAME = "azure.functions.worker"; - private static Logger LOGGER = Logger.getLogger(FunctionsOpenTelemetry.class.getSimpleName()); - private static volatile OpenTelemetrySdk sdk; - - public static void setLogger(Logger logger) { - LOGGER = logger; - } + /** TextMapGetter for Azure Functions TraceContext. */ + private static final TextMapGetter TRACE_CONTEXT_GETTER = TraceContextTextMapGetter.INSTANCE; + + /** Cached Azure resource attributes (loaded once, shared across all invocations) */ + private static volatile Map cachedAzureResourceAttributes = null; /** - * Ensures that the OpenTelemetry SDK is created. + * Returns the OpenTelemetry instance for tracing operations. + * Assumes an OpenTelemetry agent has configured the global instance. + * + * @return the global OpenTelemetry instance + * @throws IllegalStateException if no OpenTelemetry agent is detected or if an error occurs while getting the SDK */ - public static void initialize() { - if (sdk == null) { - synchronized (FunctionsOpenTelemetry.class) { - if (sdk == null) { - sdk = buildSdk(); - } + public static io.opentelemetry.api.OpenTelemetry getOpenTelemetry() { + try { + io.opentelemetry.api.OpenTelemetry otel = GlobalOpenTelemetry.get(); + + if (isNoOp(otel)) { + throw new IllegalStateException( + "No OpenTelemetry agent detected. This library requires an OpenTelemetry agent to be present. " + + "Please ensure your application is running with an OpenTelemetry Java agent." + ); } + + return otel; + } catch (IllegalStateException e) { + // Re-throw our own IllegalStateException + throw e; + } catch (Exception e) { + throw new IllegalStateException( + "Failed to get OpenTelemetry instance: " + e.getMessage() + + ". Please ensure your application is running with a properly configured OpenTelemetry Java agent.", + e + ); } } - public static OpenTelemetrySdk sdk() { - return sdk; + /** + * Checks if the given OpenTelemetry instance is a no-op implementation. + */ + private static boolean isNoOp(io.opentelemetry.api.OpenTelemetry otel) { + if (otel == null) { + return true; + } + // Check class name to detect no-op implementations + String className = otel.getClass().getName(); + return className.contains("Noop") || + className.contains("NoOp") || + className.contains("DefaultOpenTelemetry") || + className.contains("ObfuscatedOpenTelemetry"); // Default GlobalOpenTelemetry wrapper } /** - * Creates an SDK, optionally enriching it with Azure Monitor if the - * environment variable
- * {@code APPLICATIONINSIGHTS_CONNECTION_STRING} - * is present and not null. - * - *

Reflection is used only for the optional - * {@code AzureMonitorAutoConfigure} class so that users are free to exclude - * it (or pull it in transitively) without breaking compilation.

+ * Validates that a string parameter is non-null and non-empty. */ - private static OpenTelemetrySdk buildSdk() { - LOGGER.info("Initializing OpenTelemetry SDK ..."); - OpenTelemetrySdk sdk; - - try { - final AutoConfiguredOpenTelemetrySdkBuilder builder = - AutoConfiguredOpenTelemetrySdk.builder(); - - builder.addResourceCustomizer( - (existing, unused) -> existing.merge(FunctionsResourceDetector.getResource())); - - if (isAppInsightsEnabled()) { - final String connStr = System.getenv("APPLICATIONINSIGHTS_CONNECTION_STRING"); - applyAzureMonitor(builder, connStr); - } - - sdk = builder.build().getOpenTelemetrySdk(); - GlobalOpenTelemetry.set(sdk); - - LOGGER.info("OpenTelemetry SDK initialised successfully."); - - } catch (Exception ex) { - LOGGER.log(Level.SEVERE, - "Failed to initialise OpenTelemetry SDK – falling back to no-op", ex); - - sdk = OpenTelemetrySdk.builder().build(); - GlobalOpenTelemetry.set(sdk); + private static void validateNonEmpty(String value, String paramName) { + if (value == null || value.isEmpty()) { + throw new IllegalArgumentException(paramName + " must be non-null and non-empty"); } - - // ---- Add shutdown hook (needs a final reference) -------------------------- - final OpenTelemetrySdk finalSdk = sdk; - Runtime.getRuntime().addShutdownHook( - new Thread(() -> finalSdk.getSdkTracerProvider().shutdown())); - - return sdk; } - private static boolean isAppInsightsEnabled() { - return Boolean.parseBoolean( - System.getenv("JAVA_APPLICATIONINSIGHTS_ENABLE_TELEMETRY")); + /** + * Creates and starts a new span with Azure Functions context. + * + *

This method automatically sets Azure Functions attributes on the span: + *

    + *
  • Azure resource attributes (service.name, cloud.provider, etc.)
    • + *
  • Function-specific attributes (faas.name, faas.invocation_id)
    • + *
+ * + * @param spanName the name of the span + * @param functionName the Azure Functions function name + * @param invocationId the unique invocation ID + * @param traceContext the Azure Functions trace context (optional) + * @param kind the span kind + * @return the started span with Azure attributes already set + */ + public static Span startSpan(String spanName, String functionName, String invocationId, + TraceContext traceContext, SpanKind kind) { + validateNonEmpty(spanName, "spanName"); + + // Determine parent context + Context parent = Context.current(); + if (traceContext != null) { + parent = getOpenTelemetry().getPropagators() + .getTextMapPropagator() + .extract(Context.current(), traceContext, TRACE_CONTEXT_GETTER); + } + + // Create the span + Span span = getOpenTelemetry().getTracer(DEFAULT_TRACER_NAME) + .spanBuilder(spanName) + .setParent(parent) + .setSpanKind(kind == null ? SpanKind.INTERNAL : kind) + .startSpan(); + + // Automatically set Azure attributes using the same API users will use for logs + getCurrentAzureContext(functionName, invocationId).forEach(span::setAttribute); + + return span; } - private static void applyAzureMonitor(AutoConfiguredOpenTelemetrySdkBuilder builder, String connStr) { - - try { - ClassLoader cl = FunctionsOpenTelemetry.class.getClassLoader(); - - // Resolve the types we need with the same CL - Class autoCfgClass = Class.forName( - "com.azure.monitor.opentelemetry.autoconfigure.AzureMonitorAutoConfigure", false, cl); - - Class customizerIfc = Class.forName( - "io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizer", false, cl); - - // Directly look up the exact overload we expect - Method customize = - autoCfgClass.getMethod("customize", customizerIfc, String.class); - - customize.invoke(null, builder, connStr); - LOGGER.info("AzureMonitorAutoConfigure applied via reflection"); - - } catch (ClassNotFoundException e) { - LOGGER.fine("azure-monitor-opentelemetry-autoconfigure not present – skipping"); - } catch (NoSuchMethodException e) { - LOGGER.warning("AzureMonitorAutoConfigure.customize(...) not found – " - + "library version may have changed"); - } catch (Throwable t) { - LOGGER.log(Level.WARNING, "Failed to apply AzureMonitorAutoConfigure", t); + /** + * Gets Azure Functions context attributes for log correlation. + * + *

This method returns a map of key-value pairs that can be used to correlate logs + * with Azure Functions context and the current OpenTelemetry span. The attributes include: + * + *

    + *
  • Azure resource attributes: service.name, cloud.provider, cloud.region, etc.
    • + *
  • Function-specific attributes: faas.name, faas.invocation_id (if provided)
    • + *
+ * + *

Usage examples: + * 

{@code
+     * // With SLF4J structured logging
+     * Map context = FunctionsOpenTelemetry.getCurrentAzureContext("myFunction", "inv-123");
+     * logger.info("Processing request", context);
+     * 
+     * // With MDC
+     * Map context = FunctionsOpenTelemetry.getCurrentAzureContext("myFunction", "inv-123");
+     * context.forEach(MDC::put);
+     * logger.info("Processing request");
+     * MDC.clear();
+     * 
+     * // With custom formatting
+     * Map context = FunctionsOpenTelemetry.getCurrentAzureContext("myFunction", "inv-123");
+     * logger.info("Processing request - {}", context);
+     * }
+ * + * @param functionName the name of the Azure Function (optional) + * @param invocationId the unique invocation ID for this function execution (optional) + * @return a map of context attributes that can be used for log correlation + */ + public static Map getCurrentAzureContext(String functionName, String invocationId) { + Map attributes = new HashMap<>(); + + // Add cached Azure resource attributes + addAzureResourceAttributes(attributes); + + // Add function-specific attributes if provided + if (functionName != null && !functionName.isEmpty()) { + attributes.put("faas.name", functionName); + } + if (invocationId != null && !invocationId.isEmpty()) { + attributes.put("faas.invocation_id", invocationId); } + + return attributes; } - private static final TextMapGetter TRACE_CONTEXT_GETTER = TraceContextTextMapGetter.INSTANCE; - - public static Span startSpan( - String tracerName, - String spanName, - Context parent, - SpanKind kind) { - - if (spanName == null || spanName.isEmpty()) { - throw new IllegalArgumentException("spanName must be non-null and non-empty"); - } - if (tracerName == null || tracerName.isEmpty()) { - throw new IllegalArgumentException("tracerName must be non-null and non-empty"); + /** + * Gets Azure resource attributes, initializing cache if needed. + */ + private static Map getAzureResourceAttributes() { + if (cachedAzureResourceAttributes == null) { + synchronized (FunctionsOpenTelemetry.class) { + if (cachedAzureResourceAttributes == null) { + cachedAzureResourceAttributes = initializeAzureResourceAttributes(); + } + } } + return cachedAzureResourceAttributes; + } - return sdk().getTracer(tracerName) - .spanBuilder(spanName) - .setParent(parent == null ? Context.current() : parent) - .setSpanKind(kind == null ? SpanKind.INTERNAL : kind) - .startSpan(); + /** + * Initializes Azure resource attributes from the environment. + */ + private static Map initializeAzureResourceAttributes() { + Map attributes = new HashMap<>(); + + try { + Resource azureResource = FunctionsResourceDetector.getResource(); + azureResource.getAttributes().forEach((key, value) -> { + if (value != null) { + attributes.put(key.getKey(), value.toString()); + } + }); + } catch (Exception e) { + // If resource detection fails, add basic attributes + attributes.put("service.name", "java-function-app"); + } + + return attributes; } - public static Span startSpan( - String tracerName, - String spanName, - TraceContext traceContext, - SpanKind kind) { + /** + * Adds cached Azure resource attributes to the given map. + */ + private static void addAzureResourceAttributes(Map attributes) { + attributes.putAll(getAzureResourceAttributes()); + } - Context parent = sdk().getPropagators() - .getTextMapPropagator() - .extract(Context.current(), traceContext, TRACE_CONTEXT_GETTER); - return startSpan(tracerName, spanName, parent, kind); + /** + * Private constructor to prevent instantiation. + */ + private FunctionsOpenTelemetry() { } } diff --git a/azure-functions-java-opentelemetry/src/main/java/com/microsoft/azure/functions/opentelemetry/FunctionsResourceDetector.java b/azure-functions-java-opentelemetry/src/main/java/com/microsoft/azure/functions/opentelemetry/FunctionsResourceDetector.java index 17e373e..cba144a 100644 --- a/azure-functions-java-opentelemetry/src/main/java/com/microsoft/azure/functions/opentelemetry/FunctionsResourceDetector.java +++ b/azure-functions-java-opentelemetry/src/main/java/com/microsoft/azure/functions/opentelemetry/FunctionsResourceDetector.java @@ -5,52 +5,86 @@ import io.opentelemetry.sdk.resources.Resource; /** - * Detects a set of well-known Azure Functions environment variables and maps them - * to OpenTelemetry - * semantic resource attributes. - *

- * The detector is intentionally simple—no network calls or reflection—so it can - * be invoked very early in the worker start-up sequence. When running locally, - * only {@code service.name} is set; when running on the platform, additional - * cloud-specific attributes are included. - *

+ * Detects Azure Functions environment variables and maps them to OpenTelemetry resource attributes. + * + *

This detector implements Azure Functions resource detection according to the + * OpenTelemetry + * semantic resource conventions. It provides a lightweight, no-dependency approach + * to resource detection that can be invoked early in the worker startup sequence. + * + *

The detector operates in two modes: + *

    + *
  • Local development: Only {@code service.name} is set to a default value
    • + *
  • Azure-hosted: Full cloud resource attributes are populated from environment variables
    • + *
+ * + *

Detected attributes follow OpenTelemetry semantic conventions: + *

    + *
  • {@code service.name} - Logical service identifier (function app name)
    • + *
  • {@code cloud.provider} - Cloud provider ("azure")
    • + *
  • {@code cloud.platform} - Cloud platform ("azure_functions")
    • + *
  • {@code cloud.region} - Azure region (e.g., "westus2")
    • + *
  • {@code cloud.resource.id} - Full ARM resource ID
    • + *
  • {@code deployment.environment} - Deployment slot name
    • + *
*/ public final class FunctionsResourceDetector { - /** {@code cloud.provider} – fixed to {@code "azure"} when running on Azure. */ + // OpenTelemetry semantic convention attribute names + + /** OpenTelemetry attribute: {@code cloud.provider} - Cloud provider name. */ public static final String CLOUD_PROVIDER = "cloud.provider"; - /** {@code cloud.platform} – {@code "azure_functions"} for hosted apps. */ + + /** OpenTelemetry attribute: {@code cloud.platform} - Cloud platform identifier. */ public static final String CLOUD_PLATFORM = "cloud.platform"; - /** {@code cloud.region} – Azure region (e.g. {@code westus2}). */ + + /** OpenTelemetry attribute: {@code cloud.region} - Cloud region identifier. */ public static final String CLOUD_REGION = "cloud.region"; - /** {@code cloud.resource.id} – Full ARM resource ID of the function app. */ + + /** OpenTelemetry attribute: {@code cloud.resource.id} - Cloud resource identifier. */ public static final String CLOUD_RESOURCE_ID = "cloud.resource.id"; - /** {@code deployment.environment} – Function slot name (e.g. {@code production}). */ + + /** OpenTelemetry attribute: {@code deployment.environment} - Deployment environment name. */ public static final String DEPLOYMENT_ENVIRONMENT = "deployment.environment"; - /** {@code service.name} – Logical service identifier (function-app name). */ + + /** OpenTelemetry attribute: {@code service.name} - Logical service name. */ public static final String SERVICE_NAME = "service.name"; - // ─── Well-known Azure Functions environment variables ──────────────────────── + // Azure Functions environment variable names + + /** Azure Functions environment variable: Function app name. */ public static final String WEBSITE_SITE_NAME = "WEBSITE_SITE_NAME"; + + /** Azure Functions environment variable: Azure region name. */ public static final String REGION_NAME = "REGION_NAME"; + + /** Azure Functions environment variable: Resource group name. */ public static final String WEBSITE_RESOURCE_GROUP = "WEBSITE_RESOURCE_GROUP"; + + /** Azure Functions environment variable: Subscription and stamp information. */ public static final String WEBSITE_OWNER_NAME = "WEBSITE_OWNER_NAME"; + + /** Azure Functions environment variable: Deployment slot name. */ public static final String WEBSITE_SLOT_NAME = "WEBSITE_SLOT_NAME"; /** - * Builds an {@link io.opentelemetry.sdk.resources.Resource Resource} populated - * with attributes derived from the current process environment. + * Creates a Resource populated with Azure Functions-specific attributes. + * + *

This method examines well-known Azure Functions environment variables and + * maps them to OpenTelemetry semantic resource attributes. The detection is + * designed to be lightweight and free of external dependencies. + * + *

Resource construction behavior: + *

    + *
  • Always includes: {@code service.name} (function app name or default)
    • + *
  • Azure-hosted apps: Cloud provider, platform, region, and resource ID
    • + *
  • Local development: Only basic service identification
    • + *
  • Deployment environment: Slot name or "production" default
    • + *
* - * @return a new immutable {@code Resource} instance. - *
    - *
  • Always contains at least {@code service.name}.
    • - *
  • Contains {@code cloud.*} attributes when running on Azure Functions.
    • - *
  • Defaults {@code deployment.environment} to {@code production} if the - * slot name is not present.
    • - *
+ * @return an immutable Resource containing detected attributes */ public static Resource getResource() { - final String siteName = System.getenv(WEBSITE_SITE_NAME); final String region = System.getenv(REGION_NAME); final String resourceGroup = System.getenv(WEBSITE_RESOURCE_GROUP); @@ -59,7 +93,7 @@ public static Resource getResource() { final AttributesBuilder attrBuilder = Attributes.builder(); - // ─── Basic service + cloud metadata ────────────────────────────────────── + // Service identification and cloud metadata if (siteName != null && !siteName.isEmpty()) { attrBuilder.put(SERVICE_NAME, siteName) .put(CLOUD_PROVIDER, "azure") @@ -73,7 +107,7 @@ public static Resource getResource() { attrBuilder.put(CLOUD_REGION, region); } - // Construct fully-qualified ARM resource ID when all pieces are present + // Construct fully-qualified ARM resource ID when all components are available final String subscriptionId = extractSubscriptionId(ownerName); if (subscriptionId != null && resourceGroup != null && siteName != null) { String resourceId = String.format( @@ -82,7 +116,7 @@ public static Resource getResource() { attrBuilder.put(CLOUD_RESOURCE_ID, resourceId); } - // ─── Deployment slot / environment ─────────────────────────────────────── + // Deployment environment (slot name) if (slotName == null || slotName.isEmpty()) { slotName = "production"; } @@ -92,11 +126,14 @@ public static Resource getResource() { } /** - * Utility that parses {@code WEBSITE_OWNER_NAME} to extract the subscription ID. - *

The variable normally has the form {@code +}.

+ * Extracts the Azure subscription ID from the WEBSITE_OWNER_NAME environment variable. + * + *

The {@code WEBSITE_OWNER_NAME} variable typically contains the subscription ID + * followed by a stamp identifier in the format: {@code +}. + * This method extracts only the subscription ID portion. * - * @param ownerName the raw {@code WEBSITE_OWNER_NAME} value - * @return the subscription ID, or {@code null} if it cannot be parsed + * @param ownerName the raw value of the WEBSITE_OWNER_NAME environment variable + * @return the subscription ID if successfully parsed, null otherwise */ public static String extractSubscriptionId(final String ownerName) { if (ownerName == null || ownerName.isEmpty()) { @@ -106,6 +143,8 @@ public static String extractSubscriptionId(final String ownerName) { return (idx > 0) ? ownerName.substring(0, idx) : null; } - // Prevent instantiation + /** + * Private constructor to prevent instantiation of this utility class. + */ private FunctionsResourceDetector() { } } diff --git a/azure-functions-java-opentelemetry/src/main/java/com/microsoft/azure/functions/opentelemetry/OpenTelemetryInvocationMiddleware.java b/azure-functions-java-opentelemetry/src/main/java/com/microsoft/azure/functions/opentelemetry/OpenTelemetryInvocationMiddleware.java index c27d10b..16bf490 100644 --- a/azure-functions-java-opentelemetry/src/main/java/com/microsoft/azure/functions/opentelemetry/OpenTelemetryInvocationMiddleware.java +++ b/azure-functions-java-opentelemetry/src/main/java/com/microsoft/azure/functions/opentelemetry/OpenTelemetryInvocationMiddleware.java @@ -9,38 +9,68 @@ import io.opentelemetry.api.trace.StatusCode; import io.opentelemetry.context.Scope; - /** - * Middleware that starts a Span for every function invocation, - * using the trace context from the host if available. + * OpenTelemetry middleware that creates spans for Azure Functions invocations. + * + *

This middleware creates a span for each function invocation and adds Azure Functions + * specific attributes. It assumes an OpenTelemetry agent is present and configured. + * + *

Note: For log correlation, users should use the utility methods in + * {@link FunctionsOpenTelemetry#getCurrentAzureContext(String, String)} to get context attributes + * and add them to their logs in the way that best fits their logging framework. */ public class OpenTelemetryInvocationMiddleware implements Middleware { - public OpenTelemetryInvocationMiddleware() { - FunctionsOpenTelemetry.initialize(); - } - + /** + * Creates a span for the function invocation with tracing context and Azure Functions attributes. + * + *

The span includes the following attributes: + *

    + *
  • {@code faas.name} - The function name
    • + *
  • {@code faas.invocation_id} - The unique invocation ID
    • + *
  • Azure resource attributes - service.name, cloud.provider, cloud.region, etc.
    • + *
+ * + * @param context the middleware context containing function metadata + * @param chain the middleware chain to continue execution + * @throws Exception if span creation fails or the function execution throws an exception + */ @Override public void invoke(MiddlewareContext context, MiddlewareChain chain) throws Exception { - String spanName = context.getFunctionName(); - String tracerName = "azure.functions.worker"; + Span invocationSpan = null; + + try { + String spanName = "Invoke"; + + // Create and start the function invocation span with Azure attributes automatically set + invocationSpan = FunctionsOpenTelemetry.startSpan( + spanName, + context.getFunctionName(), + context.getInvocationId(), + context.getTraceContext(), + SpanKind.INTERNAL + ); + + try (Scope ignored = invocationSpan.makeCurrent()) { + // Continue with the middleware chain + chain.doNext(context); - FunctionsOpenTelemetry.setLogger(context.getLogger()); - Span invocationSpan = FunctionsOpenTelemetry.startSpan(spanName, tracerName, context.getTraceContext(), SpanKind.INTERNAL); - - try (Scope ignored = invocationSpan.makeCurrent()) { - invocationSpan.setAttribute("faas.invocation_id", context.getInvocationId()); - invocationSpan.setAttribute("faas.name", context.getFunctionName()); - - // Delegate to the rest of the chain + } catch (Throwable throwable) { + // Record exception and set error status + invocationSpan.recordException(throwable); + invocationSpan.setStatus(StatusCode.ERROR, throwable.getMessage()); + throw throwable; + } + + } catch (Exception spanCreationException) { + // If span creation fails, continue without tracing to avoid breaking function execution + // This could happen if OpenTelemetry agent is misconfigured or has issues chain.doNext(context); - - } catch (Throwable throwable) { // capture any user exception - invocationSpan.recordException(throwable); - invocationSpan.setStatus(StatusCode.ERROR, throwable.getMessage()); - throw throwable; // keep behaviour unchanged } finally { - invocationSpan.end(); + // End the span if it was successfully created + if (invocationSpan != null) { + invocationSpan.end(); + } } } } diff --git a/azure-functions-java-opentelemetry/src/main/java/com/microsoft/azure/functions/opentelemetry/TraceContextTextMapGetter.java b/azure-functions-java-opentelemetry/src/main/java/com/microsoft/azure/functions/opentelemetry/TraceContextTextMapGetter.java index 5e03204..05d1bb7 100644 --- a/azure-functions-java-opentelemetry/src/main/java/com/microsoft/azure/functions/opentelemetry/TraceContextTextMapGetter.java +++ b/azure-functions-java-opentelemetry/src/main/java/com/microsoft/azure/functions/opentelemetry/TraceContextTextMapGetter.java @@ -4,15 +4,12 @@ import io.opentelemetry.context.propagation.TextMapGetter; /** - * A singleton {@link TextMapGetter} that adapts an Azure Functions - * {@link TraceContext} to OpenTelemetry’s propagation API. - * - *

Implementation is deliberately allocation-free: - * the enum constant {@link #INSTANCE} is reused for every extraction call.

+ * TextMapGetter that extracts trace context from Azure Functions TraceContext. + * Uses enum singleton pattern for performance. */ public enum TraceContextTextMapGetter implements TextMapGetter { - /** The single shared instance. */ + /** Singleton instance. */ INSTANCE; @Override @@ -25,14 +22,14 @@ public String get(final TraceContext carrier, final String key) { if (carrier == null || key == null) { return null; } - // Match W3C header names first + // Check W3C headers first if ("traceparent".equalsIgnoreCase(key)) { return carrier.getTraceparent(); } if ("tracestate".equalsIgnoreCase(key)) { return carrier.getTracestate(); } - // Fallback to custom attributes + // Fall back to custom attributes return carrier.getAttributes().get(key); } } diff --git a/azure-functions-java-opentelemetry/src/test/java/com/microsoft/azure/functions/opentelemetry/tests/FunctionsOpenTelemetryTest.java b/azure-functions-java-opentelemetry/src/test/java/com/microsoft/azure/functions/opentelemetry/tests/FunctionsOpenTelemetryTest.java index c9fc4e5..642cc9f 100644 --- a/azure-functions-java-opentelemetry/src/test/java/com/microsoft/azure/functions/opentelemetry/tests/FunctionsOpenTelemetryTest.java +++ b/azure-functions-java-opentelemetry/src/test/java/com/microsoft/azure/functions/opentelemetry/tests/FunctionsOpenTelemetryTest.java @@ -1,9 +1,7 @@ package com.microsoft.azure.functions.opentelemetry.tests; import com.microsoft.azure.functions.opentelemetry.FunctionsOpenTelemetry; -import io.opentelemetry.api.trace.Span; import io.opentelemetry.api.trace.SpanKind; -import io.opentelemetry.sdk.OpenTelemetrySdk; import org.junit.jupiter.api.BeforeAll; import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.Test; @@ -19,23 +17,32 @@ static void setUp() { } @Test - void testSdkInitialization() { - OpenTelemetrySdk sdk = FunctionsOpenTelemetry.sdk(); - Assertions.assertNotNull(sdk, "Expected a non-null OpenTelemetrySdk instance"); + void testAgentDetectionThrowsException() { + // Since no agent is present during testing, we expect an IllegalStateException + Exception exception = Assertions.assertThrows(IllegalStateException.class, () -> { + FunctionsOpenTelemetry.getOpenTelemetry(); + }); + + Assertions.assertTrue(exception.getMessage().contains("No OpenTelemetry agent detected")); } @Test - void testStartSpanWithNullTraceContext() { - Span span = FunctionsOpenTelemetry.startSpan("testTracer", "testSpan", (com.microsoft.azure.functions.TraceContext) null, SpanKind.INTERNAL); - Assertions.assertNotNull(span, "Expected a non-null Span object"); - span.end(); + void testStartSpanThrowsExceptionWithoutAgent() { + // Since no agent is present during testing, we expect an IllegalStateException + Exception exception = Assertions.assertThrows(IllegalStateException.class, () -> { + FunctionsOpenTelemetry.startSpan("testSpan", "testFunction", "testInvocation", (com.microsoft.azure.functions.TraceContext) null, SpanKind.INTERNAL); + }); + + Assertions.assertTrue(exception.getMessage().contains("No OpenTelemetry agent detected")); } @Test - void testStartSpanWithDefaultSpanKind() { - // Passing null for SpanKind should default to INTERNAL - Span span = FunctionsOpenTelemetry.startSpan("defaultTracer", "defaultSpan", (com.microsoft.azure.functions.TraceContext) null, null); - Assertions.assertNotNull(span, "Expected a non-null Span object"); - span.end(); + void testStartSpanWithInternalSpanKindThrowsExceptionWithoutAgent() { + // Since no agent is present during testing, we expect an IllegalStateException + Exception exception = Assertions.assertThrows(IllegalStateException.class, () -> { + FunctionsOpenTelemetry.startSpan("internalSpan", "testFunction", "testInvocation", (com.microsoft.azure.functions.TraceContext) null, SpanKind.INTERNAL); + }); + + Assertions.assertTrue(exception.getMessage().contains("No OpenTelemetry agent detected")); } } diff --git a/azure-functions-java-opentelemetry/src/test/java/com/microsoft/azure/functions/opentelemetry/tests/OpenTelemetryInvocationMiddlewareTest.java b/azure-functions-java-opentelemetry/src/test/java/com/microsoft/azure/functions/opentelemetry/tests/OpenTelemetryInvocationMiddlewareTest.java index 3d32d19..cfb35da 100644 --- a/azure-functions-java-opentelemetry/src/test/java/com/microsoft/azure/functions/opentelemetry/tests/OpenTelemetryInvocationMiddlewareTest.java +++ b/azure-functions-java-opentelemetry/src/test/java/com/microsoft/azure/functions/opentelemetry/tests/OpenTelemetryInvocationMiddlewareTest.java @@ -14,8 +14,8 @@ public class OpenTelemetryInvocationMiddlewareTest { - @Test - void testInvokeCallsNextAndEndsSpan() throws Exception { + @Test + void testInvokeGracefullyHandlesNoAgent() throws Exception { // Mock context MiddlewareContext context = Mockito.mock(MiddlewareContext.class); Mockito.when(context.getFunctionName()).thenReturn("myFunction"); @@ -27,39 +27,38 @@ void testInvokeCallsNextAndEndsSpan() throws Exception { MiddlewareChain chain = Mockito.mock(MiddlewareChain.class); OpenTelemetryInvocationMiddleware middleware = new OpenTelemetryInvocationMiddleware(); - middleware.invoke(context, chain); - - // Verify chain.doNext was called + + // Since no agent is present during testing, middleware should gracefully continue without tracing + // This should not throw an exception, allowing the function to execute normally + Assertions.assertDoesNotThrow(() -> { + middleware.invoke(context, chain); + }); + + // Verify chain.doNext was called even though span creation failed Mockito.verify(chain, Mockito.times(1)).doNext(context); - - // We can’t directly assert the state of the internal Span easily - // but we can ensure no exceptions and that the code path was taken. - Assertions.assertTrue(true, "Middleware invoked successfully"); } @Test - void testInvokeRecordsExceptionOnThrowable() throws Exception { + void testInvokeContinuesChainExecutionWithoutAgent() throws Exception { // Mock context MiddlewareContext context = Mockito.mock(MiddlewareContext.class); - Mockito.when(context.getFunctionName()).thenReturn("failingFunction"); + Mockito.when(context.getFunctionName()).thenReturn("testFunction"); Mockito.when(context.getInvocationId()).thenReturn("9876"); Mockito.when(context.getLogger()).thenReturn(Logger.getLogger("testLogger")); Mockito.when(context.getTraceContext()).thenReturn(dummyTraceContext()); - // Mock chain to throw + // Mock chain MiddlewareChain chain = Mockito.mock(MiddlewareChain.class); - Mockito.doThrow(new RuntimeException("Simulated failure")).when(chain).doNext(context); OpenTelemetryInvocationMiddleware middleware = new OpenTelemetryInvocationMiddleware(); - RuntimeException thrown = Assertions.assertThrows( - RuntimeException.class, - () -> middleware.invoke(context, chain) - ); - Assertions.assertEquals("Simulated failure", thrown.getMessage()); - - // Not easy to directly verify Span is marked with ERROR, but we know code calls setStatus. - // If we wanted to ensure the Span's status is updated, we'd have to capture the Span object. + // The middleware should gracefully handle the lack of agent and continue execution + Assertions.assertDoesNotThrow(() -> { + middleware.invoke(context, chain); + }); + + // Verify chain.doNext was called even without an agent + Mockito.verify(chain, Mockito.times(1)).doNext(context); } private TraceContext dummyTraceContext() {