[feat][client] PIP-446: Support Native OpenTelemetry Tracing in Pulsar Java Client

pulsar-client-api/src/main/java/org/apache/pulsar/client/api/ClientBuilder.java

@@ -615,6 +615,44 @@ ClientBuilder authentication(String authPluginClassName, Map<String, String> aut
      */
     ClientBuilder openTelemetry(io.opentelemetry.api.OpenTelemetry openTelemetry);
 
+    /**
+     * Enable OpenTelemetry distributed tracing.
+     *
+     * <p>When enabled, interceptors are automatically added to all producers and consumers
+     * to create spans for message publishing and consumption, and automatically propagate trace context
+     * via message properties.
+     *
+     * <p>This method is useful when OpenTelemetry is configured globally (e.g., via Java Agent or
+     * {@link io.opentelemetry.api.GlobalOpenTelemetry}) and you just want to enable tracing interceptors
+     * without explicitly setting an OpenTelemetry instance.
+     *
+     * <p>Example with Java Agent:
+     * <pre>{@code
+     * // When using -javaagent:opentelemetry-javaagent.jar
+     * PulsarClient client = PulsarClient.builder()
+     *     .serviceUrl("pulsar://localhost:6650")
+     *     .enableTracing(true)  // Use GlobalOpenTelemetry
+     *     .build();
+     * }</pre>
+     *
+     * <p>Example with GlobalOpenTelemetry:
+     * <pre>{@code
+     * // Configure GlobalOpenTelemetry elsewhere in your application
+     * GlobalOpenTelemetry.set(myOpenTelemetry);
+     *
+     * // Just enable tracing in the client
+     * PulsarClient client = PulsarClient.builder()
+     *     .serviceUrl("pulsar://localhost:6650")
+     *     .enableTracing(true)
+     *     .build();
+     * }</pre>
+     *
+     * @param tracingEnabled whether to enable tracing (default: false)
+     * @return the client builder instance
+     * @since 4.2.0
+     */
+    ClientBuilder enableTracing(boolean tracingEnabled);
+
     /**
      * The clock used by the pulsar client.
      *

pulsar-client-api/src/main/java/org/apache/pulsar/client/api/TraceableMessage.java

@@ -0,0 +1,55 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+package org.apache.pulsar.client.api;
+
+import io.opentelemetry.api.trace.Span;
+
+/**
+ * Extension of {@link Message} interface that supports OpenTelemetry tracing.
+ * <p>
+ * This interface allows attaching OpenTelemetry spans directly to messages,
+ * eliminating the need for external tracking via maps.
+ * <p>
+ * The span lifecycle:
+ * <ul>
+ *   <li>Producer: Span is created before send and attached to the message.
+ *       When the send is acknowledged, the span is retrieved and completed.</li>
+ *   <li>Consumer: Span is created when message is received and attached to the message.
+ *       When the message is acknowledged, the span is retrieved and completed.</li>
+ * </ul>
+ */
+public interface TraceableMessage {
+
+    /**
+     * Set the OpenTelemetry span associated with this message.
+     * <p>
+     * This method is called by tracing interceptors to attach a span to the message
+     * for later retrieval when completing the span.
+     *
+     * @param span the span to associate with this message, or null to clear
+     */
+    void setTracingSpan(Span span);
+
+    /**
+     * Get the OpenTelemetry span associated with this message.
+     *
+     * @return the span associated with this message, or null if no span is set
+     */
+    Span getTracingSpan();
+}

pulsar-client-api/src/main/java/org/apache/pulsar/client/api/TraceableMessageId.java

@@ -0,0 +1,56 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+package org.apache.pulsar.client.api;
+
+import io.opentelemetry.api.trace.Span;
+
+/**
+ * Extension interface that allows {@link MessageId} implementations to support OpenTelemetry tracing.
+ * <p>
+ * This interface enables attaching OpenTelemetry spans directly to message IDs,
+ * allowing span retrieval in acknowledge callbacks which only receive MessageId,
+ * not the full Message object.
+ * <p>
+ * This is particularly useful for consumer-side tracing where:
+ * <ul>
+ *   <li>A span is created when a message is received (in beforeConsume)</li>
+ *   <li>The span is attached to the message's MessageId</li>
+ *   <li>When the message is acknowledged, the span can be retrieved from the MessageId
+ *       and completed, even though the acknowledge callback only provides MessageId</li>
+ * </ul>
+ */
+public interface TraceableMessageId {
+
+    /**
+     * Set the OpenTelemetry span associated with this message ID.
+     * <p>
+     * This method is called by tracing interceptors to attach a span to the message ID
+     * for later retrieval in acknowledge callbacks.
+     *
+     * @param span the span to associate with this message ID, or null to clear
+     */
+    void setTracingSpan(Span span);
+
+    /**
+     * Get the OpenTelemetry span associated with this message ID.
+     *
+     * @return the span associated with this message ID, or null if no span is set
+     */
+    Span getTracingSpan();
+}