update snippets

sdk/clientcore/core/src/main/java/io/clientcore/core/instrumentation/Instrumentation.java

@@ -75,7 +75,7 @@ static Instrumentation create(InstrumentationOptions<?> applicationOptions,
      * Retrieves the instrumentation context from the given context. The type of the context is determined by the
      * instrumentation implementation.
      * <p>
-     * For OpenTelemetry, the context can be a {@code io.opentelemetry.api.trace.Span}, {@code io.opentelemetry.api.trace.SpanContext},
+     * When using OpenTelemetry, the context can be a {@code io.opentelemetry.api.trace.Span}, {@code io.opentelemetry.api.trace.SpanContext},
      * {@code io.opentelemetry.context.Context} or any implementation of {@link InstrumentationContext}.
      * <!-- src_embed io.clientcore.core.telemetry.fallback.correlationwithexplicitcontext -->
      * <pre>
@@ -91,6 +91,27 @@ static Instrumentation create(InstrumentationOptions<?> applicationOptions,
      * </pre>
      * <!-- end io.clientcore.core.telemetry.fallback.correlationwithexplicitcontext -->
      *
+     * <!-- src_embed io.clientcore.core.telemetry.correlationwithexplicitcontext -->
+     * <pre>
+     *
+     * Tracer tracer = GlobalOpenTelemetry.getTracer&#40;&quot;sample&quot;&#41;;
+     * Span span = tracer.spanBuilder&#40;&quot;my-operation&quot;&#41;
+     *     .startSpan&#40;&#41;;
+     * SampleClient client = new SampleClientBuilder&#40;&#41;.build&#40;&#41;;
+     *
+     * &#47;&#47; Propagating context implicitly is preferred way in synchronous code.
+     * &#47;&#47; However, in asynchronous code, context may need to be propagated explicitly using RequestOptions
+     * &#47;&#47; and explicit io.clientcore.core.util.Context.
+     *
+     * RequestOptions options = new RequestOptions&#40;&#41;
+     *     .setInstrumentationContext&#40;Instrumentation.createInstrumentationContext&#40;span&#41;&#41;;
+     *
+     * &#47;&#47; run on another thread - all telemetry will be correlated with the span created above
+     * client.clientCall&#40;options&#41;;
+     *
+     * </pre>
+     * <!-- end io.clientcore.core.telemetry.fallback.correlationwithexplicitcontext -->
+     *
      * @param context the context to retrieve the instrumentation context from.
      * @return the instrumentation context.
      * @param <T> the type of the context.

sdk/clientcore/core/src/main/java/io/clientcore/core/instrumentation/package-info.java

@@ -97,9 +97,9 @@
  * // and explicit io.clientcore.core.util.Context.
  *
  * RequestOptions options = new RequestOptions()
- *     .setContext(io.clientcore.core.util.Context.of(TRACE_CONTEXT_KEY, Context.current().with(span)));
+ *     .setInstrumentationContext(Instrumentation.createInstrumentationContext(span));
  *
- * // run on another thread
+ * // run on another thread - all telemetry will be correlated with the span created above
  * client.clientCall(options);
  *
  * </pre>

sdk/clientcore/core/src/samples/java/io/clientcore/core/models/ContextJavaDocCodeSnippets.java

@@ -18,11 +18,8 @@ public void constructContextObject() {
         // Create an empty context having no data
         Context emptyContext = Context.none();
 
-        // OpenTelemetry context can be optionally passed using PARENT_TRACE_CONTEXT_KEY
-        // when OpenTelemetry context is not provided explicitly, ambient
-        // io.opentelemetry.context.Context.current() is used
-
-        // Context contextWithSpan = new Context(PARENT_TRACE_CONTEXT_KEY, openTelemetryContext);
+        // Create a context with one key value pair
+        Context contextWithOnePair = Context.of("key", "value");
         // END: io.clientcore.core.util.context#object-object
     }
 
@@ -31,17 +28,15 @@ public void constructContextObject() {
      */
     public void putToContext() {
         // BEGIN: io.clientcore.core.util.context.addData#object-object
-        // Users can pass parent trace context information and additional metadata to attach to spans created by SDKs
         // using the io.clientcore.core.util.Context object.
+
+        Context originalContext = Context.none();
+
         final String hostNameValue = "host-name-value";
         final String entityPathValue = "entity-path-value";
 
-        // TraceContext represents a tracing solution context type - io.opentelemetry.context.Context for OpenTelemetry.
-        final TraceContext parentContext = TraceContext.root();
-        Context parentSpanContext = Context.of("PARENT_TRACE_CONTEXT_KEY", parentContext);
-
         // Add a new key value pair to the existing context object.
-        Context updatedContext = parentSpanContext.put("HOST_NAME_KEY", hostNameValue)
+        Context updatedContext = originalContext.put("HOST_NAME_KEY", hostNameValue)
             .put("ENTITY_PATH_KEY", entityPathValue);
 
         // Both key values found on the same updated context object

sdk/clientcore/optional-dependency-tests/src/samples/java/io/clientcore/core/instrumentation/TelemetryJavaDocCodeSnippets.java

@@ -7,24 +7,21 @@
 import io.clientcore.core.http.models.HttpRequest;
 import io.clientcore.core.http.models.RequestOptions;
 import io.clientcore.core.http.models.Response;
+import io.clientcore.core.http.pipeline.HttpInstrumentationPolicy;
 import io.clientcore.core.http.pipeline.HttpPipeline;
 import io.clientcore.core.http.pipeline.HttpPipelineBuilder;
-import io.clientcore.core.http.pipeline.InstrumentationPolicy;
 import io.clientcore.core.instrumentation.tracing.SpanKind;
 import io.clientcore.core.instrumentation.tracing.TracingScope;
 import io.opentelemetry.api.GlobalOpenTelemetry;
 import io.opentelemetry.api.OpenTelemetry;
 import io.opentelemetry.api.trace.Span;
 import io.opentelemetry.api.trace.Tracer;
-import io.opentelemetry.context.Context;
 import io.opentelemetry.context.Scope;
 import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;
 
 import java.io.IOException;
 import java.io.UncheckedIOException;
 
-import static io.clientcore.core.instrumentation.Instrumentation.TRACE_CONTEXT_KEY;
-
 /**
  * Application developers are expected to configure OpenTelemetry
  * to leverage instrumentation code in client libraries.
@@ -142,25 +139,25 @@ public void correlationWithExplicitContext() {
         // and explicit io.clientcore.core.util.Context.
 
         RequestOptions options = new RequestOptions()
-            .setContext(io.clientcore.core.util.Context.of(TRACE_CONTEXT_KEY, Context.current().with(span)));
+            .setInstrumentationContext(Instrumentation.createInstrumentationContext(span));
 
-        // run on another thread
+        // run on another thread - all telemetry will be correlated with the span created above
         client.clientCall(options);
 
         // END: io.clientcore.core.telemetry.correlationwithexplicitcontext
     }
 
     static class SampleClientBuilder {
         private InstrumentationOptions<?> instrumentationOptions;
-        // TODO (limolkova): do we need InstrumnetationTrait?
+        // TODO (limolkova): do we need InstrumentationTrait?
         public SampleClientBuilder instrumentationOptions(InstrumentationOptions<?> instrumentationOptions) {
             this.instrumentationOptions = instrumentationOptions;
             return this;
         }
 
         public SampleClient build() {
             return new SampleClient(instrumentationOptions, new HttpPipelineBuilder()
-                .policies(new InstrumentationPolicy(instrumentationOptions, null))
+                .policies(new HttpInstrumentationPolicy(instrumentationOptions, null))
                 .build());
         }
     }
@@ -181,14 +178,14 @@ public void clientCall() {
 
         @SuppressWarnings("try")
         public void clientCall(RequestOptions options) {
-            io.clientcore.core.instrumentation.tracing.Span span = tracer.spanBuilder("clientCall", SpanKind.CLIENT, options)
+            io.clientcore.core.instrumentation.tracing.Span span = tracer.spanBuilder("clientCall", SpanKind.CLIENT, null)
                 .startSpan();
 
             if (options == null) {
                 options = new RequestOptions();
             }
 
-            options.setContext(options.getContext().put(TRACE_CONTEXT_KEY, span));
+            options.setInstrumentationContext(span.getInstrumentationContext());
 
             try (TracingScope scope = span.makeCurrent()) {
                 Response<?> response = httpPipeline.send(new HttpRequest(HttpMethod.GET, "https://example.com"));

sdk/clientcore/optional-dependency-tests/src/test/java/io/clientcore/core/instrumentation/ContextPropagationTests.java

@@ -150,21 +150,6 @@ public void testExtractInvalid() {
         assertFalse(extracted.isValid());
     }
 
-    @Test
-    public void testExtractPreservesContext() {
-        /*Map<String, String> carrier = new HashMap<>();
-        carrier.put("traceparent", "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01");
-
-        Context original = Context.of("key", "value");
-        Context updated = contextPropagator.extract(original, carrier, GETTER);
-
-        io.opentelemetry.context.Context otelContext
-            = (io.opentelemetry.context.Context) updated.get(TRACE_CONTEXT_KEY);
-        assertTrue(io.opentelemetry.api.trace.Span.fromContext(otelContext).getSpanContext().isValid());
-
-        assertEquals("value", updated.get("key"));*/
-    }
-
     private String getTraceparent(Span span) {
         InstrumentationContext spanContext = span.getInstrumentationContext();
         return "00-" + spanContext.getTraceId() + "-" + spanContext.getSpanId() + "-" + spanContext.getTraceFlags();