documentation

docs/src/main/asciidoc/opentelemetry.adoc

@@ -8,12 +8,12 @@ include::_attributes.adoc[]
 :categories: observability
 :summary: This guide explains how your Quarkus application can utilize OpenTelemetry to provide distributed tracing for interactive web applications.
 
-This guide explains how your Quarkus application can utilize https://opentelemetry.io/[OpenTelemetry] to provide
+This guide explains how your Quarkus application can utilize https://opentelemetry.io/[OpenTelemetry] (OTel) to provide
 distributed tracing for interactive web applications.
 
-OpenTelemetry Metrics and Logging are not yet supported.
-
+Extensions and the libraries they provide, are directly instrumented in Quarkus. The *use of the https://opentelemetry.io/docs/instrumentation/java/automatic/[OpenTelemetry Agent] is not needed nor recommended* due to context propagation issues between imperative and reactive libraries.
 
+OpenTelemetry Metrics and Logging are not yet supported.
 
 [NOTE]
 ====
@@ -108,10 +108,7 @@ endpoint will be traced without any required code changes.
 
 === Create the configuration
 
-
-
-To configure the default OTLP gRPC Exporter within the application you must set the
-properties within the `src/main/resources/application.properties` file:
+To configure the default OTLP gRPC Exporter within the application you must set the properties within the `src/main/resources/application.properties` file:
 
 [source,properties]
 ----
@@ -124,15 +121,15 @@ quarkus.http.access-log.pattern="...traceId=%{X,traceId} spanId=%{X,spanId}" //
 ----
 
 <1> All spans created from the application will include an OpenTelemetry `Resource` indicating the span was created by the `myservice` application. If not set, it will default to the artifact id.
-<2> gRPC endpoint for sending spans
+<2> gRPC endpoint to send spans
 <3> Add tracing information into log message.
 <4> You can also only put the trace info into the access log. In this case you must omit the info in the console log format.
 
 [NOTE]
 ====
 All configurations have been updated from `quarkus.opentelemetry.\*` -> `quarkus.otel.*`
 
-*The legacy configurations are now deprecated* but will still work during a transition period.
+The legacy configurations are now deprecated but will still work during a transition period.
 ====
 
 == Run the application
@@ -141,43 +138,11 @@ The first step is to configure and start the https://opentelemetry.io/docs/colle
 
 [NOTE]
 ====
-Jaeger supports the OTel protocols out of the box since version 1.35.
-In this case you do not need to install the collector but can directly send the trace data to Jaeger (after enabling OTLP receivers there, see e.g. this
+Jaeger-all-in-one includes the Jaeger agent, an OTel collector, and the query service/UI.
+You do not need to install a separated collector. You can directly send the trace data to Jaeger (after enabling OTLP receivers there, see e.g. this
 https://medium.com/jaegertracing/introducing-native-support-for-opentelemetry-in-jaeger-eb661be8183c[blog entry]).
 ====
 
-Configure the OpenTelemetry Collector by creating an `otel-collector-config.yaml` file:
-
-[source,yaml,subs="attributes"]
-----
-receivers:
-  otlp:
-    protocols:
-      grpc:
-        endpoint: otel-collector:4317
-
-exporters:
-  jaeger:
-    endpoint: jaeger-all-in-one:14250
-    tls:
-      insecure: true
-
-processors:
-  batch:
-
-extensions:
-  health_check:
-
-service:
-  extensions: [health_check]
-  pipelines:
-    traces:
-      receivers: [otlp]
-      processors: [batch]
-      exporters: [jaeger]
-
-----
-
 Start the OpenTelemetry Collector and Jaeger system via the following `docker-compose.yml` file that you can launch via `docker-compose up -d`:
 
 [source,yaml,subs="attributes"]
@@ -189,29 +154,23 @@ services:
   jaeger-all-in-one:
     image: jaegertracing/all-in-one:latest
     ports:
-      - "16686:16686"
-      - "14268:14268"
-      - "14250:14250"
-  # Collector
-  otel-collector:
-    image: otel/opentelemetry-collector:latest
-    command: ["--config=/etc/otel-collector-config.yaml"]
-    volumes:
-      - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml:Z
-    ports:
-      - "13133:13133" # Health_check extension
+      - "16686:16686" # Jaeger UI
+      - "14268:14268" # receive legacy OpenTracing traces, optional
       - "4317:4317"   # OTLP gRPC receiver
-    depends_on:
-      - jaeger-all-in-one
+      - "4318:4318"   # OTLP HTTP receiver, not yet used by Quarkus, optional
+      - "14250:14250" # receive from external otel-collector, optional
+    environment:
+      - COLLECTOR_OTLP_ENABLED=true
 ----
+You should remove the optional ports you don't need.
 
 Now we are ready to run our application. If using `application.properties` to configure the tracer:
 
 include::{includes}/devtools/dev.adoc[]
 
 or if configuring the OTLP gRPC endpoint via JVM arguments:
 
-:dev-additional-parameters: -Djvm.args="-Dquarkus.opentelemetry.tracer.exporter.otlp.endpoint=http://localhost:4317"
+:dev-additional-parameters: -Djvm.args="-Dquarkus.otel.exporter.otlp.traces.endpoint=http://localhost:4317"
 include::{includes}/devtools/dev.adoc[]
 :!dev-additional-parameters:
 
@@ -235,7 +194,7 @@ When the first request has been submitted, you will be able to see the tracing i
 
 Then visit the http://localhost:16686[Jaeger UI] to see the tracing information.
 
-Hit `CTRL+C` to stop the application.
+Hit `CTRL+C` or type `q` to stop the application.
 
 === JDBC
 

extensions/opentelemetry/deployment/src/main/java/io/quarkus/opentelemetry/deployment/OpenTelemetryProcessor.java

@@ -1,29 +1,16 @@
 package io.quarkus.opentelemetry.deployment;
 
+import static io.quarkus.opentelemetry.runtime.OpenTelemetryRecorder.OPEN_TELEMETRY_DRIVER;
 import static java.util.stream.Collectors.*;
 
 import java.io.IOException;
-import java.util.HashMap;
-import static io.quarkus.opentelemetry.runtime.OpenTelemetryRecorder.OPEN_TELEMETRY_DRIVER;
-
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Optional;
 import java.util.Set;
 
 import org.eclipse.microprofile.config.ConfigProvider;
 import org.eclipse.microprofile.config.ConfigValue;
-import io.opentelemetry.api.OpenTelemetry;
-import io.quarkus.runtime.RuntimeValue;
-import io.quarkus.deployment.builditem.ShutdownContextBuildItem;
-import io.quarkus.opentelemetry.deployment.tracing.TracerIdGeneratorBuildItem;
-import io.quarkus.opentelemetry.deployment.tracing.TracerResourceBuildItem;
-import io.quarkus.opentelemetry.deployment.tracing.TracerSamplerBuildItem;
-import io.quarkus.opentelemetry.deployment.tracing.TracerSpanExportersBuildItem;
-import io.quarkus.opentelemetry.deployment.tracing.TracerSpanProcessorsBuildItem;
-import io.quarkus.opentelemetry.runtime.config.build.OtelBuildConfig;
-import io.quarkus.opentelemetry.runtime.config.runtime.OtelRuntimeConfig;
-import io.quarkus.opentelemetry.runtime.tracing.intrumentation.InstrumentationRecorder;
 import org.jboss.jandex.AnnotationInstance;
 import org.jboss.jandex.AnnotationTarget;
 import org.jboss.jandex.AnnotationValue;
@@ -34,7 +21,6 @@
 import io.opentelemetry.instrumentation.annotations.SpanAttribute;
 import io.opentelemetry.instrumentation.annotations.WithSpan;
 import io.opentelemetry.sdk.autoconfigure.spi.traces.ConfigurableSpanExporterProvider;
-import io.opentelemetry.sdk.trace.SdkTracerProvider;
 import io.quarkus.agroal.spi.JdbcDataSourceBuildItem;
 import io.quarkus.agroal.spi.JdbcDriverBuildItem;
 import io.quarkus.arc.deployment.AdditionalBeanBuildItem;

extensions/opentelemetry/runtime/src/main/java/io/quarkus/opentelemetry/runtime/OpenTelemetryProducer.java

@@ -151,11 +151,13 @@ public void accept(String value) {
                     @Override
                     public Resource apply(Resource existingResource, ConfigProperties configProperties) {
                         if (tracesEnabled.orElse(TRUE)) {
-                            Resource consolidatedResource = existingResource.merge(Resource.create(delayedAttributes.get()));
+                            Resource consolidatedResource = existingResource.merge(
+                                    Resource.create(delayedAttributes.get())); // from cdi
                             // Merge resource instances with env attributes
                             Resource resource = resources.stream()
                                     .reduce(Resource.empty(), Resource::merge)
-                                    .merge(TracerUtil.mapResourceAttributes(resourceAttributes.orElse(emptyList())));
+                                    .merge(
+                                            TracerUtil.mapResourceAttributes(resourceAttributes.orElse(emptyList()))); // from properties
                             return consolidatedResource.merge(resource);
                         } else {
                             return Resource.builder().build();
@@ -180,7 +182,7 @@ public Sampler apply(Sampler existingSampler, ConfigProperties configProperties)
                             public SdkTracerProviderBuilder apply(SdkTracerProviderBuilder builder,
                                     ConfigProperties configProperties) {
                                 if (tracesEnabled.orElse(TRUE)) {
-                                    idGenerator.stream().findFirst().ifPresent(builder::setIdGenerator);
+                                    idGenerator.stream().findFirst().ifPresent(builder::setIdGenerator); // from cdi
                                     spanProcessors.stream().forEach(builder::addSpanProcessor);
                                 }
                                 return builder;

extensions/opentelemetry/runtime/src/main/java/io/quarkus/opentelemetry/runtime/OpenTelemetryRecorder.java

@@ -2,8 +2,6 @@
 
 import static org.apache.commons.lang3.StringUtils.isEmpty;
 
-import java.util.HashMap;
-import java.util.Map;
 import java.lang.reflect.InvocationTargetException;
 import java.sql.Driver;
 import java.util.function.Supplier;
@@ -12,7 +10,6 @@
 import javax.enterprise.inject.spi.BeanManager;
 
 import org.apache.commons.lang3.StringUtils;
-
 import org.jboss.logging.Logger;
 
 import io.opentelemetry.api.GlobalOpenTelemetry;

extensions/opentelemetry/runtime/src/main/java/io/quarkus/opentelemetry/runtime/config/build/TracesBuildConfig.java

@@ -29,11 +29,11 @@ public class TracesBuildConfig {
     /**
      * List of exporters supported by Quarkus.
      * <p>
-     * List of exporters to be used for tracing, separated by commas. none means no autoconfigured exporter.
-     * Has one of the values on {@link ExporterType} or the full qualified name of a class implementing
+     * List of exporters to be used for tracing, separated by commas.
+     * Has one of the values on {@link ExporterType} `otlp`, `cdi`, `none` or the full qualified name of a class implementing
      * {@link io.opentelemetry.sdk.trace.export.SpanExporter}
      * <p>
-     * Default is {@value ExporterType.Constants#CDI_VALUE}.
+     * Default on Quarkus is {@value ExporterType.Constants#CDI_VALUE}.
      *
      * @return
      */
@@ -43,11 +43,12 @@ public class TracesBuildConfig {
     /**
      * The sampler to use for tracing.
      * <p>
-     * Has one of the values on {@link SamplerType} or the full qualified name of a class implementing
-     * {@link io.opentelemetry.sdk.trace.samplers.Sampler}
+     * Has one of the values on {@link SamplerType} `always_on`, `always_off`, `traceidratio`, `parentbased_always_on`,
+     * `parentbased_always_off`, `parentbased_traceidratio` or the full qualified name of a class implementing the
+     * {@link io.opentelemetry.sdk.trace.samplers.Sampler} interface.
      * <p>
-     * Defaults to {@value SamplerType.Constants#PARENT_BASED_ALWAYS_ON} or
-     * the legacy quarkus.opentelemetry.tracer.sampler.sampler.name property
+     * Defaults to the legacy quarkus.opentelemetry.tracer.sampler.sampler.name property or
+     * {@value SamplerType.Constants#PARENT_BASED_ALWAYS_ON}
      */
     @ConfigItem(defaultValue = "${quarkus.opentelemetry.tracer.sampler:" + SamplerType.Constants.PARENT_BASED_ALWAYS_ON + "}")
     //    @ConvertWith(LegacySamplerNameConverter.class)

extensions/opentelemetry/runtime/src/main/java/io/quarkus/opentelemetry/runtime/config/runtime/exporter/OtlpExporterRuntimeConfig.java

@@ -12,10 +12,11 @@
 public class OtlpExporterRuntimeConfig {
 
     /**
-     * Sets the OTLP endpoint to connect to. If unset, defaults to {@value Constants#DEFAULT_GRPC_BASE_URL}.
+     * Sets the OTLP endpoint to connect to. If unset, defaults to {@value Constants#DEFAULT_GRPC_BASE_URI}.
+     * We are currently using just the traces, therefore traces.endpoint is recommended.
      */
     //    @WithConverter(TrimmedStringConverter.class)
-    @ConfigItem(defaultValue = Constants.DEFAULT_GRPC_BASE_URL)
+    @ConfigItem(defaultValue = Constants.DEFAULT_GRPC_BASE_URI)
     public Optional<String> endpoint;
 
     /**
@@ -33,12 +34,12 @@ public class OtlpExporterRuntimeConfig {
     @ConfigItem()
     public Optional<byte[]> certificate;
 
-    //    /**
-    //     * Sets ths client key and the certificate chain to use for verifying client when TLS is enabled.
-    //     * The key must be PKCS8, and both must be in PEM format.
-    //     */
-    //    @ConfigItem()
-    //    public Optional<ClientTlsConfig> client;
+//        /**
+//         * Sets ths client key and the certificate chain to use for verifying client when TLS is enabled.
+//         * The key must be PKCS8, and both must be in PEM format.
+//         */
+//        @ConfigItem()
+//        public Optional<ClientTlsConfig> client;
 
     /**
      * Add header to request. Optional.
@@ -89,7 +90,7 @@ public class OtlpExporterRuntimeConfig {
      * the OpenTelemetry Protocol Exporter configuration options</a>
      */
     public class Constants {
-        public static final String DEFAULT_GRPC_BASE_URL = "http://localhost:4317/";
-        public static final String DEFAULT_HTTP_BASE_URL = "http://localhost:4318/";
+        public static final String DEFAULT_GRPC_BASE_URI = "http://localhost:4317/";
+        public static final String DEFAULT_HTTP_BASE_URI = "http://localhost:4318/";
     }
 }

extensions/opentelemetry/runtime/src/main/java/io/quarkus/opentelemetry/runtime/config/runtime/exporter/OtlpExporterTracesConfig.java

@@ -1,6 +1,6 @@
 package io.quarkus.opentelemetry.runtime.config.runtime.exporter;
 
-import static io.quarkus.opentelemetry.runtime.config.runtime.exporter.OtlpExporterRuntimeConfig.Constants.DEFAULT_GRPC_BASE_URL;
+import static io.quarkus.opentelemetry.runtime.config.runtime.exporter.OtlpExporterRuntimeConfig.Constants.DEFAULT_GRPC_BASE_URI;
 
 import java.time.Duration;
 import java.util.Map;
@@ -13,16 +13,16 @@
 public class OtlpExporterTracesConfig extends OtelConnectionRuntimeConfig {
 
     /**
-     * OTLP Exporter specific. Will be concatenated after otel.exporter.otlp.endpoint.
+     * OTLP Exporter specific. Will override otel.exporter.otlp.endpoint, if set.
      * <p>
      * The old Quarkus configuration used the opentelemetry.tracer.exporter.otlp.endpoint system property
      * to define the full endpoint starting with http or https.
      * If the old property is set, we will use it until the transition period ends.
      * <p>
-     * Default value is {@value OtlpExporterTracesConfig.Constants#DEFAULT_GRPC_PATH}
+     * Default value is {@value OtlpExporterRuntimeConfig.Constants#DEFAULT_GRPC_BASE_URI}
      */
     //    @WithConverter(TrimmedStringConverter.class)
-    @ConfigItem(defaultValue = Constants.DEFAULT_GRPC_PATH)
+    @ConfigItem(defaultValue = DEFAULT_GRPC_BASE_URI)
     public Optional<String> endpoint;
 
     /**
@@ -32,7 +32,7 @@ public class OtlpExporterTracesConfig extends OtelConnectionRuntimeConfig {
     //    @WithConverter(TrimmedStringConverter.class)
     @Deprecated
     @ConfigItem(name = "legacy-endpoint", defaultValue = "${quarkus.opentelemetry.tracer.exporter.otlp.endpoint:" +
-            DEFAULT_GRPC_BASE_URL + Constants.DEFAULT_GRPC_PATH + "}")
+            DEFAULT_GRPC_BASE_URI + "}")
     public Optional<String> legacyEndpoint;
 
     /**
@@ -81,15 +81,6 @@ public class OtlpExporterTracesConfig extends OtelConnectionRuntimeConfig {
     @ConfigItem(defaultValue = Protocol.HTTP_PROTOBUF)
     public Optional<String> protocol;
 
-    /**
-     * From <a href=
-     * "https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options">
-     * the OpenTelemetry Protocol Exporter configuration options</a>
-     */
-    public class Constants {
-        public static final String DEFAULT_GRPC_PATH = "v1/traces";
-    }
-
     public class Protocol {
         public static final String GRPC = "grpc";
         public static final String HTTP_PROTOBUF = "http/protobuf";