--- schema_version: "1" id: 98432c383f09907c01350d614e03073ceea2acb439d2ed3772f49289ea457b17 title: Tracing Features in the Mule Java SDK collection: mulesoft version: current locale: en-us portal_url: https://docs.salesforce.com/mulesoft/current/en-us/mule-sdk/latest/tracing.md canonical_url: https://docs.mulesoft.com/mule-sdk/latest/tracing source_site: docs.mulesoft.com content_type: documentation content_hash: 3a2ddbbe7969228c59cd5d43607e6a656030aa7540c14a0795fe2ae4393875a2 description: MuleSoft Documentation Site release: "1.13" latest: true --- --- product: Mule SDK version: 1.13 is-latest-version: true --- # Tracing Features in the Mule Java SDK > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Tracing in the Mule Java SDK enables SDK-developed components to contribute telemetry data to the Mule runtime engine. Sources and operations can customize spans by defining span names, adding attributes, and setting the OpenTelemetry span kind. Tracing also supports trace context propagation, which integrates the Mule Java SDK with distributed tracing systems. ## Implementing Tracing Features For operations, add `DistributedTraceContextManager` as an argument. The SDK [implicitly injects](https://docs.mulesoft.com/mule-sdk/latest/forward-compatibility-implicit-params) this argument during each operation call. For sources, obtain `DistributedTraceContextManager` from `SourceCallbackContext`. `DistributedTraceContextManager` provides access to all the available tracing features for both sources and operations. ## Example: Customize an Operation Span This example shows a module definition: ```java @Extension(name = "Foo") @Operations(FooOperations.class) public class FooModule { @Parameter private String fooModuleParameter; public String getFooModuleParameter() { return fooModuleParameter; } } ``` This operation customizes the span: ```java public class FooOperations { public String foo(@Config FooModule config, DistributedTraceContextManager distributedTraceContextManager) { // Implicit parameters must handle potential null values. if (distributedTraceContextManager != null) { // Override the current span name. distributedTraceContextManager.setCurrentSpanName("fooOperation"); // Add an attribute to the span. distributedTraceContextManager.addCurrentSpanAttribute("attributeKey", "attributeValue"); } return "OK"; } } ``` ## Example: Customize a Source Span Sources [push messages to flows](https://docs.mulesoft.com/mule-sdk/latest/sources-push-message) by using `SourceCallbackContext`. This example is based on the HTTP Listener behavior: ```java public class HttpListener extends Source { @Override public void onStart(SourceCallback sourceCallback) throws MuleException { httpServer = serverProvider.connect(); server.listen(path).onRequest(request -> { SourceCallbackContext context = sourceCallback.createContext(); // Obtain the DistributedTraceContextManager from the SourceCallbackContext. DistributedTraceContextManager distributedTraceContextManager = sourceCallback.getDistributedTraceContextManager(); // Override the current span name. distributedTraceContextManager.setCurrentSpanName("http:special-source"); // Add an attribute to the span. distributedTraceContextManager.addCurrentSpanAttribute("attributeKey", "attributeValue"); Result result = requestToResult(request, context); sourceCallback.handle(result); }); } } ``` ## Trace Context Propagation Sources and connectors play different roles in both Mule and distributed tracing. In Mule, a source triggers a flow and creates the first span in its corresponding trace. Because of this role, the source must handle distributed trace context. If a trace already exists, the source must continue that trace instead of creating a new one. Connectors propagate the current trace context to external systems outside Mule runtime. These systems can include databases, non-Mule APIs, and message queues. The Mule runtime Java SDK supports the W3C trace context propagation standard. This standard defines a [trace context](https://www.w3.org/TR/trace-context/#trace-context-http-headers-format) that consists of a `traceparent` and a `tracestate`: ```text traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01 tracestate: congo=t61rcWkgMzE ``` This representation enables trace context propagation across systems that support the standard. ## Example: Trace Context Propagation in Sources and Connectors This example uses the HTTP Listener and the HTTP Requester to demonstrate trace context propagation. When the HTTP Listener receives W3C trace context headers in a request, use the `DistributedTraceContextManager` to indicate where to retrieve the W3C trace context: ```java public class HttpListener extends Source { @Override public void onStart(SourceCallback sourceCallback) throws MuleException { httpServer = serverProvider.connect(); server.listen(path).onRequest(request -> { SourceCallbackContext context = sourceCallback.createContext(); // Obtain the DistributedTraceContextManager from the SourceCallbackContext. DistributedTraceContextManager distributedTraceContextManager = sourceCallback.getDistributedTraceContextManager(); // This defines the map where the W3C trace context key values are available for retrieval (an HTTP request in this case, so the HTTP headers are used). // The mule runtime will trace the flow execution as child spans of this provided trace context. distributedTraceContextManager.setRemoteTraceContextMap(request.getHeaders()); Result result = requestToResult(request, context); sourceCallback.handle(result); }); } } ``` The HTTP Requester retrieves the current W3C trace context during request operations by using `getRemoteTraceContextMap()`, and then propagates it: ```java public class HttpRequestOperations implements Initialisable, Disposable { public void request(HttpRequesterConfig config, DistributedTraceContextManager distributedTraceContextManager) { HttpRequestBuilder builder = HttpRequestBuilder.createRequestBuilder(config); // Implicit parameters must handle potential null values. if (distributedTraceContextManager != null) { // This obtains the current trace context as a map, propagating it to the connected system (an HTTP endpoint in this case, so HTTP headers are added). distributedTraceContextManager.getRemoteTraceContextMap().forEach(builder::addHeader); } } } ``` ## Distributed Trace Context API This table shows the distributed trace context manager methods:

Method

Parameter

Description

void setRemoteTraceContextMap(Map<String, String> contextMap)

contextMap

A Map<String, String> that contains the key-value pairs that store the information of the remote trace context.

void setCurrentSpanName(String name)

name

Sets the name of the current span.

Map<String, String> getRemoteTraceContextMap()

N/A

Returns the context map for the remote trace context.

void addCurrentSpanAttribute(String key, String value)

  • key

  • value

  • Key of the span attribute.

  • Value of the span attribute. Use span.kind.override as the key to override the span kind.

void addCurrentSpanAttributes(Map<String, String> attributes)

attributes

A Map<String, String> that contains the attributes to add to the current span. Use span.kind.override as the key to override the span kind.

> [!NOTE] `setRemoteTraceContextMap()` is intended for sources only. Mule silently ignores calls > made from connector operations. ## See Also - [OpenTelemetry Support in Mule Runtime](https://docs.mulesoft.com/mule-runtime/latest/otel-support)