com.coze.loop.trace

Class CozeLoopTracerProvider

java.lang.Object

com.coze.loop.trace.CozeLoopTracerProvider

public class CozeLoopTracerProvider
extends Object

CozeLoop TracerProvider that wraps OpenTelemetry TracerProvider.

This class provides a bridge between CozeLoop SDK and OpenTelemetry, managing the complete trace lifecycle from span creation to export. It configures and initializes the OpenTelemetry SDK with OTLP/HTTP exporter and BatchSpanProcessor.

Architecture Overview:

• Resource: Defines service metadata (service name, workspace ID)
• SdkTracerProvider: Manages Tracer instances and SpanProcessors
• BatchSpanProcessor: Handles batching (configurable batch size)
• CozeLoopSpanExporter: Custom OTLP/HTTP exporter with X-TT-LogID support

Context Propagation: The TracerProvider automatically handles OpenTelemetry context propagation, ensuring that trace context (trace ID, span ID, baggage) is automatically propagated to child spans within the same thread and across async boundaries.

Example Usage:

 TraceConfig config = TraceConfig.builder()
     .maxQueueSize(2048)
     .batchSize(512)
     .scheduleDelayMillis(5000)
     .exportTimeoutMillis(30000)
     .build();

 CozeLoopTracerProvider provider = CozeLoopTracerProvider.create(
     spanEndpoint, workspaceId, serviceName, config);

 Tracer tracer = provider.getTracer("my-instrumentation");
 

Shutdown: Always call shutdown() when the application is shutting down to ensure all pending spans are flushed and exported:

 provider.shutdown(); // Flushes and exports all pending spans
 

See Also:

OpenTelemetry Java Documentation, BatchSpanProcessor, CozeLoopSpanExporter

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CozeLoopTracerProvider.TraceConfig Trace configuration for OpenTelemetry BatchSpanProcessor.

Method Summary

Modifier and Type	Method and Description
static CozeLoopTracerProvider	create(Auth auth, String spanEndpoint, String workspaceId, String serviceName, CozeLoopTracerProvider.TraceConfig config) Create a new CozeLoopTracerProvider.
void	flush() Force flush all pending spans.
FinishEventProcessor	getFinishEventProcessor()
io.opentelemetry.context.propagation.ContextPropagators	getPropagators() Get the ContextPropagators configured for this SDK.
io.opentelemetry.api.trace.Tracer	getTracer(String instrumentationName, String instrumentationVersion) Get a Tracer for creating spans.
io.opentelemetry.api.trace.TracerProvider	getTracerProvider() Get the underlying OpenTelemetry TracerProvider.
void	shutdown() Shutdown the tracer provider and flush all pending spans.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getFinishEventProcessor

public FinishEventProcessor getFinishEventProcessor()

create

public static CozeLoopTracerProvider create(Auth auth,
                                            String spanEndpoint,
                                            String workspaceId,
                                            String serviceName,
                                            CozeLoopTracerProvider.TraceConfig config)

Create a new CozeLoopTracerProvider.

Parameters:

auth - the authentication provider

spanEndpoint - the span upload endpoint

workspaceId - the workspace ID

serviceName - the service name

config - the trace configuration (includes optional FinishEventProcessor)

Returns:

CozeLoopTracerProvider instance

getPropagators

public io.opentelemetry.context.propagation.ContextPropagators getPropagators()

Get the ContextPropagators configured for this SDK.

Returns:

the context propagators

getTracer

public io.opentelemetry.api.trace.Tracer getTracer(String instrumentationName,
                                                   String instrumentationVersion)

Get a Tracer for creating spans.

The instrumentation name identifies the library or framework that is creating spans. This helps organize spans in the CozeLoop platform.

Example:

 Tracer tracer = provider.getTracer("my-application", "1.0.0");
 Span span = tracer.spanBuilder("operation").startSpan();
 

Parameters:

instrumentationName - the name of the instrumentation library (e.g., "cozeloop-java-sdk", "my-application")

Returns:

Tracer instance for creating spans

getTracerProvider

public io.opentelemetry.api.trace.TracerProvider getTracerProvider()

Get the underlying OpenTelemetry TracerProvider.

This provides direct access to the OpenTelemetry TracerProvider for advanced use cases that require OpenTelemetry-specific APIs.

Example:

 TracerProvider provider = tracerProvider.getTracerProvider();
 // Use OpenTelemetry APIs directly
 

Returns:

the underlying OpenTelemetry TracerProvider

flush

public void flush()

Force flush all pending spans. This method waits up to 10 seconds for the flush to complete.

shutdown

public void shutdown()

Shutdown the tracer provider and flush all pending spans.

This method should be called when the application is shutting down to ensure:

• All pending spans are flushed from the queue
• All spans are exported to CozeLoop platform
• Resources are properly released

Important: After shutdown, the TracerProvider cannot be used again. You must create a new instance if needed.

The shutdown process:

1. Force flush all pending spans (waits up to 10 seconds)
2. Shutdown the TracerProvider (waits up to 10 seconds)
3. Shutdown the SpanExporter

Example:

 Runtime.getRuntime().addShutdownHook(new Thread(() -> {
     tracerProvider.shutdown();
 }));