// Module included in the following assemblies:
//
// assembly-kafka-bridge-config.adoc

[id='proc-configuring-kafka-bridge-tracing-{context}']
= Configuring distributed tracing

[role="_abstract"]
Enable distributed tracing to trace messages consumed and produced by the Kafka Bridge, and HTTP requests from client applications.

Properties to enable tracing are present in the `application.properties` file.
To enable distributed tracing, do the following:

* Set the `bridge.tracing` property value to enable the tracing you want to use. The only possible value is `opentelemetry`.
* Set environment variables for tracing.

With the default configuration, OpenTelemetry tracing uses OTLP as the exporter protocol.
By configuring the OTLP endpoint, you can still use a Jaeger backend instance to get traces.

NOTE: Jaeger has supported the OTLP protocol since version 1.35. Older Jaeger versions cannot get traces using the OTLP protocol.

OpenTelemetry defines an API specification for collecting tracing data as _spans_ of metrics data.
Spans represent a specific operation.
A trace is a collection of one or more spans.

Traces are generated when the Kafka Bridge does the following:

* Sends messages from Kafka to consumer HTTP clients 
* Receives messages from producer HTTP clients to send to Kafka

Jaeger implements the required APIs and presents visualizations of the trace data in its user interface for analysis. 

To have end-to-end tracing, you must configure tracing in your HTTP clients.

CAUTION: Strimzi no longer supports OpenTracing.
If you were previously using OpenTracing with the `bridge.tracing=jaeger` option, we encourage you to transition to using OpenTelemetry instead.

.Prerequisites

* xref:proc-downloading-kafka-bridge-{context}[The Kafka Bridge installation archive is downloaded].

.Procedure

. Edit the `application.properties` file provided with the Kafka Bridge installation archive.
+
Use the `bridge.tracing` property to enable the tracing you want to use. 
+
.Example configuration to enable OpenTelemetry
[source,properties]
----
bridge.tracing=opentelemetry # <1>
----
<1> The property for enabling OpenTelemetry is uncommented by removing the `#` at the beginning of the line.
+
With tracing enabled, you initialize tracing when you run the Kafka Bridge script.

. Save the configuration file.
. Set the environment variables for tracing.
+
.Environment variables for OpenTelemetry 
[source,env]
----
OTEL_SERVICE_NAME=my-tracing-service # <1>
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 # <2>
----
<1> The name of the OpenTelemetry tracer service.
<2> The gRPC-based OTLP endpoint that listens for spans on port 4317.

. Run the Kafka Bridge script with the property enabled for tracing.
+
.Running the Kafka Bridge with OpenTelemetry enabled
[source,shell,subs="+quotes,attributes"]
----
./bin/kafka_bridge_run.sh --config-file=_<path>_/application.properties
----
+
The internal consumers and producers of the Kafka Bridge are now enabled for tracing.

== Specifying tracing systems with OpenTelemetry

Instead of the default OTLP tracing system, you can specify other tracing systems that are supported by OpenTelemetry.

If you want to use another tracing system with OpenTelemetry, do the following: 

. Add the library of the tracing system to the Kafka classpath.
. Add the name of the tracing system as an additional exporter environment variable.
+
.Additional environment variable when not using OTLP
[source,env]
----
OTEL_SERVICE_NAME=my-tracing-service
OTEL_TRACES_EXPORTER=zipkin # <1>
OTEL_EXPORTER_ZIPKIN_ENDPOINT=http://localhost:9411/api/v2/spans <2>
----
<1> The name of the tracing system. In this example, Zipkin is specified.
<2> The endpoint of the specific selected exporter that listens for spans. In this example, a Zipkin endpoint is specified.

== Supported Span attributes

The Kafka Bridge adds, in addition to the standard OpenTelemetry attributes, the following attributes from the https://opentelemetry.io/docs/specs/semconv/http/http-spans/#http-server-semantic-conventions[OpenTelemetry standard conventions for HTTP] to its spans.
[cols="1,1"]
|===
| Attribute key | Attribute value
| `peer.service` | Hardcoded to `kafka`
| `http.request.method` | The http method used to make the request
| `url.scheme` | The https://www.rfc-editor.org/rfc/rfc3986#section-3.1[URI scheme] component
| `url.path` | The https://www.rfc-editor.org/rfc/rfc3986#section-3.3[URI path] component
| `url.query` | The https://www.rfc-editor.org/rfc/rfc3986#section-3.4[URI query] component
| `messaging.destination.name` | The name of the Kafka topic being produced to or read from
| `messaging.system` | Hardcoded to `kafka`
| `http.response.status_code` | `ok` for http responses between 200 and 300. `error` for all other status codes
|===

[role="_additional-resources"]
.Additional resources

* {otel-exporters}
