diff --git a/docs/src/main/asciidoc/includes/tracing/tracer-otel.adoc b/docs/src/main/asciidoc/includes/tracing/tracer-otel.adoc new file mode 100644 index 00000000000..2a95fe10da5 --- /dev/null +++ b/docs/src/main/asciidoc/includes/tracing/tracer-otel.adoc @@ -0,0 +1,105 @@ +/////////////////////////////////////////////////////////////////////////////// + + Copyright (c) 2025 Oracle and/or its affiliates. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +/////////////////////////////////////////////////////////////////////////////// + +// tag::setup[] +ifndef::rootdir[:rootdir: {docdir}/../..] +ifndef::flavor-lc[:flavor-lc: se] +:feature-name: OpenTelemetry Tracing +// end::setup[] + +Helidon is integrated with OpenTelemetry and OpenTelemetry tracing. + +include::{rootdir}/includes/dependencies.adoc[] + +// tag::otel-dependency[] + + +[source,xml] +.Dependency for OpenTelemetry support +---- + +io.helidon.tracing.providers +helidon-tracing-providers-opentelemetry +runtime + +---- +To control OpenTelemetry tracing using Helidon configuration, also add the following dependency. +[source,xml] +.Dependency for configuring OpenTelemetry using Helidon config +---- + + io.helidon.telemetry + helidon-telemetry-opentelemetry-config + runtime + +---- +You must also add at least one dependency on an OpenTelemetry exporter so your service sends its span data to a back-end system such as Jaeger or Grafana. + +The following example dependency uses the OpenTelemetry `otlp` exporter. + +[source,xml] +.Example dependency for an OpenTelemetry exporter +---- + + io.opentelemetry + opentelemetry-exporter-otlp + runtime + +---- + +// end::otel-dependency[] + +// tag::otel-configuration[] + +== Configuring OpenTelemetry Tracing +Because OpenTelemetry comprises several signals, of which tracing is only one, you configure OpenTelemetry tracing differently from other implementations of tracing. + +For complete information on configuring OpenTelemetry using Helidon {flavor-uc}, see xref:{rootdir}/{flavor-lc}/open-telemetry.adoc[the Helidon {flavor-uc} OpenTelemetry documentation] which describes all the available configuration settings. The following example shows only some of those settings. + +ifdef::se-flavor[] +[source,yaml] +.Example Helidon configuration for OpenTelemetry tracing +---- +telemetry: + service: helidon-otel-tracing-example # <1> + signals: + tracing: + processors: + - type: simple # <2> + exporters: + - type: otlp # <3> +---- +endif::se-flavor[] +ifdef::mp-flavor[] +[source.properties] +.Example Helidon configuration for OpenTelemetry tracing +---- +telemetry.service=helidon-otel-tracing-example # <1> +telemetry.signals.tracing.processors.0.type=simple <2> +telemetry.signals.tracing.exporters.0.type=otlp <3> +---- +endif::mp-flavor[] +<1> Specifies the OpenTelemetry service name. +<2> Selects the `simple` span processor. +<3> Selects which span exporter to use. + +The `simple` processor type sends each span to the backend as soon as it ends, rather than grouping multiple spans into batches, and so is appropriate for testing and demos but not for production deployments. + +The `otlp` exporter type matches the exporter dependency example shown above. If you try to configure a particular exporter type without adding the corresponding dependency to your project, the server fails during startup. + +// end::otel-configuration[] diff --git a/docs/src/main/asciidoc/se/tracing.adoc b/docs/src/main/asciidoc/se/tracing.adoc index f24155eab9e..e8fd275ff25 100644 --- a/docs/src/main/asciidoc/se/tracing.adoc +++ b/docs/src/main/asciidoc/se/tracing.adoc @@ -33,6 +33,7 @@ include::{rootdir}/includes/se.adoc[] - <> ** <> ** <> +** <> - <> == Overview @@ -41,9 +42,11 @@ Distributed tracing is a critical feature of microservice based applications, si within a service and across multiple services. This provides insight to sequence and timing data for specific blocks of work, which helps you identify performance and operational issues. Helidon includes support for distributed tracing through its own API, backed by either -through the https://opentelemetry.io/docs/instrumentation/js/api/tracing/[OpenTelemetry API], or by + the https://opentelemetry.io/docs/instrumentation/js/api/tracing/[OpenTelemetry API], or by https://opentracing.io[OpenTracing API]. Tracing is integrated with WebServer and Security. +NOTE: As OpenTelemetry has subsumed OpenTracing, Helidon support for OpenTracing is deprecated and will likely be removed in a future release. + include::{rootdir}/includes/dependencies.adoc[] // tag::tracing-dependency[] @@ -63,7 +66,7 @@ include::{rootdir}/includes/dependencies.adoc[] <1> Helidon tracing dependency. <2> Observability dependencies for tracing. -For further processing of the tracing data, different providers are used. +To transmit tracing data from your service to a backend, you need to add a tracing provider to your project. For Jaeger: [source,xml] @@ -71,6 +74,7 @@ For Jaeger: io.helidon.tracing.providers helidon-tracing-providers-jaeger + runtime ---- @@ -80,6 +84,7 @@ For Zipkin: io.helidon.tracing.providers helidon-tracing-providers-zipkin + runtime ---- @@ -88,9 +93,17 @@ For OpenTelemetry: ---- io.helidon.tracing.providers - helidon-tracing-providers-opentelemetry + helidon-tracing-providers-opentelemetry + runtime + + + io.helidon.telemetry + helidon-telemetry-opentelemetry-config + runtime ---- +<1> Allows your service to send tracing information using OpenTelemetry exporters. +<2> Allows you to configure the behavior of OpenTelemetry as a whole and OpenTelemetry tracing in the `telemetry` config section. For OpenTracing: [source,xml] @@ -352,9 +365,13 @@ As the <> section describes, you can use Jaeger include::{rootdir}/includes/tracing/tracer-zipkin.adoc[tag=zipkin-dependency] include::{rootdir}/includes/tracing/tracer-zipkin.adoc[tag=zipkin-configuration] +=== OpenTelemetry Tracing [[opentelemetry-tracing]] + +include::{rootdir}/includes/tracing/tracer-otel.adoc[tags=setup;otel-dependency] +include::{rootdir}/includes/tracing/tracer-otel.adoc[tag=otel-configuration] == Reference -* link:https://opentracing.io/[Opentracing Project] -* link:https://opentelemetry.io/docs/instrumentation/js/api/tracing/[OpenTelemetry API] * link:https://opentelemetry.io/docs/instrumentation/js/api/tracing/[OpenTelemetry API] +* link:https://opentracing.io/[Opentracing Project (now part of OpenTelemetry)] +