Clientcore: instrumentation convenience API (Azure#44006)

* Operation instrumentation conventience

Author: Liudmila Molkova

sdk/clientcore/core/src/main/java/io/clientcore/core/http/pipeline/HttpInstrumentationPolicy.java

@@ -29,8 +29,10 @@
 
 import java.io.IOException;
 import java.io.InputStream;
+import java.util.Arrays;
 import java.util.Collections;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Locale;
 import java.util.Map;
 import java.util.Properties;
@@ -164,11 +166,16 @@ public final class HttpInstrumentationPolicy implements HttpPipelinePolicy {
 
     private static final int MAX_BODY_LOG_SIZE = 1024 * 16;
     private static final String REDACTED_PLACEHOLDER = "REDACTED";
+
     // HTTP request duration metric is formally defined in the OpenTelemetry Semantic Conventions:
     // https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-metrics.md#metric-httpclientrequestduration
     private static final String REQUEST_DURATION_METRIC_NAME = "http.client.request.duration";
     private static final String REQUEST_DURATION_METRIC_DESCRIPTION = "Duration of HTTP client requests";
     private static final String REQUEST_DURATION_METRIC_UNIT = "s";
+    // the histogram boundaries are optimized for typical HTTP request durations and could be customized by users on
+    // the OTel side. These are the defaults documented in the OpenTelemetry Semantic Conventions (link above).
+    private static final List<Double> REQUEST_DURATION_BOUNDARIES_ADVICE = Collections.unmodifiableList(
+        Arrays.asList(0.005d, 0.01d, 0.025d, 0.05d, 0.075d, 0.1d, 0.25d, 0.5d, 0.75d, 1d, 2.5d, 5d, 7.5d, 10d));
 
     // request log level is low (verbose) since almost all request details are also
     // captured on the response log.
@@ -197,7 +204,7 @@ public HttpInstrumentationPolicy(HttpInstrumentationOptions instrumentationOptio
         this.tracer = instrumentation.createTracer();
         this.meter = instrumentation.createMeter();
         this.httpRequestDuration = meter.createDoubleHistogram(REQUEST_DURATION_METRIC_NAME,
-            REQUEST_DURATION_METRIC_DESCRIPTION, REQUEST_DURATION_METRIC_UNIT);
+            REQUEST_DURATION_METRIC_DESCRIPTION, REQUEST_DURATION_METRIC_UNIT, REQUEST_DURATION_BOUNDARIES_ADVICE);
         this.traceContextPropagator = instrumentation.getW3CTraceContextPropagator();
 
         HttpInstrumentationOptions optionsToUse

sdk/clientcore/core/src/main/java/io/clientcore/core/implementation/instrumentation/AttributeKeys.java

@@ -148,6 +148,13 @@ public final class AttributeKeys {
      */
     public static final String HTTP_RESPONSE_BODY_CONTENT_KEY = "http.request.body.content";
 
+    /**
+     * Key representing operation name. The value should be a string.
+     * When instrumenting client libraries, it should be language-agnostic operation name provided in typespec
+     * or swagger.
+     */
+    public static final String OPERATION_NAME_KEY = "operation.name";
+
     /**
      * Key representing maximum number of redirects or retries. It's reported when the number of redirects or retries
      * was exhausted.

…/tracing/NoopInstrumentationContext.java …entation/NoopInstrumentationContext.javasdk/clientcore/core/src/main/java/io/clientcore/core/instrumentation/tracing/NoopInstrumentationContext.java renamed to sdk/clientcore/core/src/main/java/io/clientcore/core/implementation/instrumentation/NoopInstrumentationContext.java sdk/clientcore/core/src/main/java/io/clientcore/core/instrumentation/tracing/NoopInstrumentationContext.java renamed to sdk/clientcore/core/src/main/java/io/clientcore/core/implementation/instrumentation/NoopInstrumentationContext.java

@@ -1,11 +1,15 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-package io.clientcore.core.instrumentation.tracing;
+package io.clientcore.core.implementation.instrumentation;
 
 import io.clientcore.core.instrumentation.InstrumentationContext;
+import io.clientcore.core.instrumentation.tracing.Span;
 
-final class NoopInstrumentationContext implements InstrumentationContext {
+/**
+ * No-op implementation of {@link InstrumentationContext}.
+ */
+public final class NoopInstrumentationContext implements InstrumentationContext {
     public static final NoopInstrumentationContext INSTANCE = new NoopInstrumentationContext();
 
     private NoopInstrumentationContext() {

sdk/clientcore/core/src/main/java/io/clientcore/core/implementation/instrumentation/NoopMeter.java

@@ -9,6 +9,7 @@
 import io.clientcore.core.instrumentation.metrics.LongCounter;
 import io.clientcore.core.instrumentation.metrics.Meter;
 
+import java.util.List;
 import java.util.Objects;
 
 /**
@@ -47,7 +48,8 @@ private NoopMeter() {
      * {@inheritDoc}
      */
     @Override
-    public DoubleHistogram createDoubleHistogram(String name, String description, String unit) {
+    public DoubleHistogram createDoubleHistogram(String name, String description, String unit,
+        List<Double> bucketBoundaries) {
         Objects.requireNonNull(name, "'name' cannot be null.");
         Objects.requireNonNull(description, "'description' cannot be null.");
         Objects.requireNonNull(unit, "'unit' cannot be null.");
@@ -83,8 +85,4 @@ public LongCounter createLongUpDownCounter(String name, String description, Stri
     public boolean isEnabled() {
         return false;
     }
-
-    @Override
-    public void close() {
-    }
 }

sdk/clientcore/core/src/main/java/io/clientcore/core/implementation/instrumentation/fallback/FallbackAttributes.java

@@ -0,0 +1,43 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package io.clientcore.core.implementation.instrumentation.fallback;
+
+import io.clientcore.core.instrumentation.InstrumentationAttributes;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Objects;
+
+class FallbackAttributes implements InstrumentationAttributes {
+    private final Map<String, Object> attributes;
+
+    FallbackAttributes(Map<String, Object> attributes) {
+        if (attributes == null) {
+            this.attributes = Collections.emptyMap();
+            return;
+        }
+
+        for (Map.Entry<String, Object> entry : attributes.entrySet()) {
+            Objects.requireNonNull(entry.getKey(), "attribute key cannot be null.");
+            Objects.requireNonNull(entry.getValue(), "attribute value cannot be null.");
+        }
+        this.attributes = Collections.unmodifiableMap(attributes);
+    }
+
+    @Override
+    public InstrumentationAttributes put(String key, Object value) {
+        Objects.requireNonNull(key, "'key' cannot be null.");
+        Objects.requireNonNull(value, "'value' cannot be null.");
+
+        Map<String, Object> newAttributes = new HashMap<>((int) ((attributes.size() + 1) * 1.5));
+        newAttributes.putAll(attributes);
+        newAttributes.put(key, value);
+        return new FallbackAttributes(newAttributes);
+    }
+
+    Map<String, Object> getAttributes() {
+        return attributes;
+    }
+}

sdk/clientcore/core/src/main/java/io/clientcore/core/implementation/instrumentation/fallback/FallbackInstrumentation.java

@@ -3,19 +3,20 @@
 
 package io.clientcore.core.implementation.instrumentation.fallback;
 
-import io.clientcore.core.implementation.instrumentation.NoopAttributes;
+import io.clientcore.core.implementation.instrumentation.LibraryInstrumentationOptionsAccessHelper;
 import io.clientcore.core.implementation.instrumentation.NoopMeter;
 import io.clientcore.core.instrumentation.Instrumentation;
 import io.clientcore.core.instrumentation.InstrumentationAttributes;
 import io.clientcore.core.instrumentation.InstrumentationContext;
 import io.clientcore.core.instrumentation.InstrumentationOptions;
 import io.clientcore.core.instrumentation.LibraryInstrumentationOptions;
 import io.clientcore.core.instrumentation.metrics.Meter;
+import io.clientcore.core.instrumentation.tracing.Span;
+import io.clientcore.core.instrumentation.tracing.SpanKind;
 import io.clientcore.core.instrumentation.tracing.TraceContextPropagator;
 import io.clientcore.core.instrumentation.tracing.Tracer;
 
 import java.util.Map;
-import java.util.Objects;
 
 /**
  * Fallback implementation of {@link Instrumentation} which implements basic correlation and context propagation
@@ -26,6 +27,8 @@ public class FallbackInstrumentation implements Instrumentation {
 
     private final InstrumentationOptions instrumentationOptions;
     private final LibraryInstrumentationOptions libraryOptions;
+    private final boolean allowNestedSpans;
+    private final boolean isTracingEnabled;
 
     /**
      * Creates a new instance of {@link FallbackInstrumentation}.
@@ -36,6 +39,9 @@ public FallbackInstrumentation(InstrumentationOptions instrumentationOptions,
         LibraryInstrumentationOptions libraryOptions) {
         this.instrumentationOptions = instrumentationOptions;
         this.libraryOptions = libraryOptions;
+        this.allowNestedSpans = libraryOptions != null
+            && LibraryInstrumentationOptionsAccessHelper.isSpanSuppressionDisabled(libraryOptions);
+        this.isTracingEnabled = instrumentationOptions == null || instrumentationOptions.isTracingEnabled();
     }
 
     /**
@@ -58,15 +64,12 @@ public Meter createMeter() {
         return NoopMeter.INSTANCE;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public InstrumentationAttributes createAttributes(Map<String, Object> attributes) {
-        if (attributes != null) {
-            for (Map.Entry<String, Object> entry : attributes.entrySet()) {
-                Objects.requireNonNull(entry.getKey(), "attribute key cannot be null.");
-                Objects.requireNonNull(entry.getValue(), "attribute value cannot be null.");
-            }
-        }
-        return NoopAttributes.INSTANCE;
+        return new FallbackAttributes(attributes);
     }
 
     /**
@@ -94,4 +97,36 @@ public <T> InstrumentationContext createInstrumentationContext(T context) {
             return FallbackSpanContext.INVALID;
         }
     }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public boolean shouldInstrument(SpanKind spanKind, InstrumentationContext context) {
+        if (!isTracingEnabled) {
+            return false;
+        }
+
+        if (allowNestedSpans) {
+            return true;
+        }
+
+        return spanKind != tryGetSpanKind(context);
+    }
+
+    /**
+     * Retrieves the span kind from the given context if and only if the context is a {@link FallbackSpanContext}
+     * i.e. was created by this instrumentation.
+     * @param context the context to get the span kind from
+     * @return the span kind or {@code null} if the context is not recognized
+     */
+    private SpanKind tryGetSpanKind(InstrumentationContext context) {
+        if (context instanceof FallbackSpanContext) {
+            Span span = context.getSpan();
+            if (span instanceof FallbackSpan) {
+                return ((FallbackSpan) span).getSpanKind();
+            }
+        }
+        return null;
+    }
 }

sdk/clientcore/core/src/main/java/io/clientcore/core/implementation/instrumentation/fallback/FallbackSpan.java

@@ -6,6 +6,7 @@
 import io.clientcore.core.instrumentation.InstrumentationContext;
 import io.clientcore.core.instrumentation.logging.ClientLogger;
 import io.clientcore.core.instrumentation.tracing.Span;
+import io.clientcore.core.instrumentation.tracing.SpanKind;
 import io.clientcore.core.instrumentation.tracing.TracingScope;
 
 import static io.clientcore.core.implementation.instrumentation.AttributeKeys.ERROR_TYPE_KEY;
@@ -18,11 +19,14 @@ final class FallbackSpan implements Span {
     private final ClientLogger.LoggingEvent log;
     private final long startTime;
     private final FallbackSpanContext spanContext;
+    private final SpanKind kind;
     private String errorType;
 
-    FallbackSpan(ClientLogger.LoggingEvent log, FallbackSpanContext parentSpanContext, boolean isRecording) {
+    FallbackSpan(ClientLogger.LoggingEvent log, SpanKind spanKind, FallbackSpanContext parentSpanContext,
+        boolean isRecording) {
         this.log = log;
         this.startTime = isRecording ? System.nanoTime() : 0;
+        this.kind = spanKind;
         this.spanContext = FallbackSpanContext.fromParent(parentSpanContext, isRecording, this);
         if (log != null && log.isEnabled()) {
             this.log.addKeyValue(TRACE_ID_KEY, spanContext.getTraceId())
@@ -77,6 +81,10 @@ public void end(Throwable error) {
         log.log(null);
     }
 
+    public SpanKind getSpanKind() {
+        return kind;
+    }
+
     /**
      * {@inheritDoc}
      */

sdk/clientcore/core/src/main/java/io/clientcore/core/implementation/instrumentation/fallback/FallbackSpanBuilder.java

@@ -3,12 +3,15 @@
 
 package io.clientcore.core.implementation.instrumentation.fallback;
 
+import io.clientcore.core.instrumentation.InstrumentationAttributes;
 import io.clientcore.core.instrumentation.InstrumentationContext;
 import io.clientcore.core.instrumentation.logging.ClientLogger;
 import io.clientcore.core.instrumentation.tracing.Span;
 import io.clientcore.core.instrumentation.tracing.SpanBuilder;
 import io.clientcore.core.instrumentation.tracing.SpanKind;
 
+import java.util.Map;
+
 import static io.clientcore.core.implementation.instrumentation.AttributeKeys.SPAN_KIND_KEY;
 import static io.clientcore.core.implementation.instrumentation.AttributeKeys.SPAN_NAME_KEY;
 import static io.clientcore.core.implementation.instrumentation.AttributeKeys.SPAN_PARENT_ID_KEY;
@@ -17,15 +20,18 @@ final class FallbackSpanBuilder implements SpanBuilder {
     static final FallbackSpanBuilder NOOP = new FallbackSpanBuilder();
     private final ClientLogger.LoggingEvent log;
     private final FallbackSpanContext parentSpanContext;
+    private final SpanKind spanKind;
 
     private FallbackSpanBuilder() {
         this.log = null;
         this.parentSpanContext = FallbackSpanContext.INVALID;
+        this.spanKind = null;
     }
 
     FallbackSpanBuilder(ClientLogger logger, String spanName, SpanKind spanKind,
         InstrumentationContext instrumentationContext) {
         this.parentSpanContext = FallbackSpanContext.fromInstrumentationContext(instrumentationContext);
+        this.spanKind = spanKind;
         this.log = logger.atVerbose();
         if (log.isEnabled()) {
             log.addKeyValue(SPAN_NAME_KEY, spanName).addKeyValue(SPAN_KIND_KEY, spanKind.name());
@@ -46,13 +52,26 @@ public SpanBuilder setAttribute(String key, Object value) {
         return this;
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public SpanBuilder setAllAttributes(InstrumentationAttributes attributes) {
+        if (log != null && attributes instanceof FallbackAttributes) {
+            for (Map.Entry<String, Object> entry : ((FallbackAttributes) attributes).getAttributes().entrySet()) {
+                log.addKeyValue(entry.getKey(), entry.getValue());
+            }
+        }
+        return this;
+    }
+
     /**
      * {@inheritDoc}
      */
     @Override
     public Span startSpan() {
         if (log != null) {
-            return new FallbackSpan(log, parentSpanContext, log.isEnabled());
+            return new FallbackSpan(log, spanKind, parentSpanContext, log.isEnabled());
         }
 
         return Span.noop();