AWS SDK v2 -> OpenTelemetry metrics bridge

[evg-tso]

AWS SDK v2 -> OpenTelemetry metrics bridge

This PR adds an OpenTelemetryMetricPublisher that implements
software.amazon.awssdk.metrics.MetricPublisher and converts the internal AWS SDK v2 metric stream into OpenTelemetry instruments.

Why?

• Today the AWS SDK instrumentation ships traces only.
  Metrics such as ApiCallDuration, RetryCount, or HttpStatusCode (see the official metric list) are available inside the SDK but cannot be exported to OTel without custom plumbing.
• Bridging these metrics lets clients correlate latency/error-rate spikes in CloudWatch/Prometheus/OTLP-backed dashboards (DataDog in my company's case) with the traces they already get from the OTel Java agent.

Key features

• Full metric coverage: supports request/attempt/HTTP-level metrics defined by the AWS SDK Developer Guide.
• Semantic mapping: MetricSpec maps every AWS metric to the correct OpenTelemetry instrument type (histograms, mostly) with unit, description, and attribute set.
• Low-GC attribute caching: frequently repeated attribute sets (service + operation + status, etc.) are cached to minimize allocations.
• Configurable: metric-name prefix (aws.sdk by default), executor for asynchronous publishing, and optional static attributes such as env, tenant, and more.
• Opt-in and independent: works with or without AWS tracing; users simply register the publisher in ClientOverrideConfiguration, with no agent flag required.

Usage

// Minimal – common ForkJoinPool, prefix "aws.sdk"
MetricPublisher publisher = OpenTelemetryMetricPublisher.create(openTelemetry);

S3Client s3 = S3Client.builder()
    .overrideConfiguration(cfg -> cfg.addMetricPublisher(publisher))
    .build();

Optional customization:

Executor executor = Executors.newFixedThreadPool(4);
Attributes staticAttrs = Attributes.of(AttributeKey.stringKey("env"), "prod");

MetricPublisher publisher =
        new OpenTelemetryMetricPublisher(openTelemetry,
                                         "mycompany.aws.sdk",
                                         executor,
                                         staticAttrs);

Open questions (these should be cleared by the maintainers):

• Should I update an additional README to reference these additions?
• Is the request/attempt/http grouping correct? AWS's code, MetricCategory.java doesn't map 1-to-1 to their service client metrics.

Closes #12259.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: evg-tso / name: Yevgeni Tsodikov (d39a7d1, 95ebc74, 44c7f71, 7942f2b, 41e5e3e, 542fdbf, 18c46ea, d48609b)

[evg-tso]

@breedx-splk , @trask - sorry for the mention, but may I request a code review?

[laurit]

did you consider building the metric publisher through AwsSdkTelemetry?

[evg-tso]

I thought about it, and it seems the AwsSdkTelemetry is more focused on tracing and propagation.
It could be as simple as the attached patch.
The main pros are the unified access point, but the con is that a person who only requires metrics will have to initiate an AwsSdkTelemetry via the builder, which contains many irrelevant fields.

Subject: Metrics in `AwsSdkTelemetry`
---
Index: instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/AwsSdkTelemetry.java
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/AwsSdkTelemetry.java b/instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/AwsSdkTelemetry.java
--- a/instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/AwsSdkTelemetry.java	(revision 542fdbf96ace578a0f4eb74a497b66a180adf069)
+++ b/instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/AwsSdkTelemetry.java	(date 1746692159838)
@@ -6,6 +6,7 @@
 package io.opentelemetry.instrumentation.awssdk.v2_2;
 
 import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.common.Attributes;
 import io.opentelemetry.api.logs.Logger;
 import io.opentelemetry.context.propagation.TextMapPropagator;
 import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
@@ -16,12 +17,15 @@
 import io.opentelemetry.instrumentation.awssdk.v2_2.internal.SqsProcessRequest;
 import io.opentelemetry.instrumentation.awssdk.v2_2.internal.SqsReceiveRequest;
 import io.opentelemetry.instrumentation.awssdk.v2_2.internal.TracingExecutionInterceptor;
+import io.opentelemetry.instrumentation.awssdk.v2_2.metrics.OpenTelemetryMetricPublisher;
 import io.opentelemetry.javaagent.tooling.muzzle.NoMuzzle;
 import java.util.List;
+import java.util.concurrent.Executor;
 import javax.annotation.Nullable;
 import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration;
 import software.amazon.awssdk.core.interceptor.ExecutionAttributes;
 import software.amazon.awssdk.core.interceptor.ExecutionInterceptor;
+import software.amazon.awssdk.metrics.MetricPublisher;
 import software.amazon.awssdk.services.bedrockruntime.BedrockRuntimeAsyncClient;
 import software.amazon.awssdk.services.sqs.SqsAsyncClient;
 import software.amazon.awssdk.services.sqs.SqsClient;
@@ -61,6 +65,7 @@
     return new AwsSdkTelemetryBuilder(openTelemetry);
   }
 
+  private final OpenTelemetry openTelemetry;
   private final Instrumenter<ExecutionAttributes, Response> requestInstrumenter;
   private final Instrumenter<SqsReceiveRequest, Response> consumerReceiveInstrumenter;
   private final Instrumenter<SqsProcessRequest, Response> consumerProcessInstrumenter;
@@ -96,6 +101,7 @@
             messagingReceiveInstrumentationEnabled,
             useXrayPropagator);
 
+    this.openTelemetry = openTelemetry;
     this.requestInstrumenter = instrumenterFactory.requestInstrumenter();
     this.consumerReceiveInstrumenter = instrumenterFactory.consumerReceiveInstrumenter();
     this.consumerProcessInstrumenter = instrumenterFactory.consumerProcessInstrumenter();
@@ -154,4 +160,20 @@
       BedrockRuntimeAsyncClient bedrockClient) {
     return BedrockRuntimeImpl.wrap(bedrockClient, eventLogger, genAiCaptureMessageContent);
   }
+  
+  public MetricPublisher createMetricPublisher() {
+    return new OpenTelemetryMetricPublisher(openTelemetry);
+  }
+
+  public MetricPublisher createMetricPublisher(String metricPrefix) {
+    return new OpenTelemetryMetricPublisher(openTelemetry, metricPrefix);
+  }
+
+  public MetricPublisher createMetricPublisher(String metricPrefix, Executor executor) {
+    return new OpenTelemetryMetricPublisher(openTelemetry, metricPrefix, executor);
+  }
+
+  public MetricPublisher createMetricPublisher(String metricPrefix, Executor executor, Attributes baseAttributes) {
+    return new OpenTelemetryMetricPublisher(openTelemetry, metricPrefix, executor, baseAttributes);
+  }
 }

[evg-tso]

Personally, I don't like these additions to the AwsSdkTelemetry. They muddy that class and force some odd fields into its builder that are unrelated to its traces aspect.
Example: the Executor executor and Attributesn't baseAttributes are used by the metrics but not by the traces.
@laurit, what do you think?

[laurit]

My understanding it that the intention was that end users will interact Telemetry classes to apply the manual instrumentation libraries. If you disagree with that approach you are welcome to raise this at the SIG meeting. Java SIG meeting is on Thursday, you can find the time in the OTEL community calendar. @open-telemetry/java-instrumentation-approvers do you have any suggestions?

[evg-tso]

I don't disagree with that approach, it makes plenty of sense from the end-user perspective.
I'll need to refactor the AwsSdkTelemetry class and expand the scope of this PR to address that, though.
Let me think if I can find a clean approach here.
Any specific suggestions are welcome :)