CozeLoopSpan (CozeLoop Java SDK

java.lang.Object
- com.coze.loop.trace.CozeLoopSpan

All Implemented Interfaces:

AutoCloseable
```
public class CozeLoopSpan
extends Object
implements AutoCloseable
```
Wrapper for OpenTelemetry Span that provides CozeLoop-specific methods.
This class wraps OpenTelemetry's Span and provides:
- CozeLoop-specific convenience methods (setInput, setOutput, setModel, etc.)
- Automatic scope management via try-with-resources
- Access to underlying OpenTelemetry Span for advanced usage
The span is automatically made current in the OpenTelemetry context when created, allowing child spans to automatically inherit the parent context.
Example usage:
```
 try (CozeLoopSpan span = client.startSpan("operation", "custom")) {
     span.setInput("input data");
     span.setOutput("output data");
     span.addEvent("important-event");
 }
 
```
For advanced OpenTelemetry features, you can access the underlying Span:
```
 CozeLoopSpan cozeSpan = client.startSpan("operation", "custom");
 Span otelSpan = cozeSpan.getSpan();
 // Use OpenTelemetry APIs directly
 
```

Constructor Summary

Constructors
Constructor and Description
`CozeLoopSpan(io.opentelemetry.api.trace.Span span, io.opentelemetry.context.Scope scope, io.opentelemetry.context.propagation.ContextPropagators propagators, CozeLoopContext context, String scene, FinishEventProcessor finishEventProcessor)` Create a new CozeLoopSpan wrapper.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`close()` End the span and close the scope.
`void`	`finish()` End the span and close the scope.
`Map<String,String>`	`getBaggage()` Get all baggage items.
`CozeLoopContext`	`getContext()` Get the CozeLoop Context associated with this span.
`String`	`getSpanID()` Get the span ID for this span.
`String`	`getTraceID()` Get the trace ID for this span.
`void`	`setBaggage(Map<String,String> values)` Set multiple baggage items.
`void`	`setBaggage(String key, String value)` Set baggage for this span and future child spans.
`void`	`setDeploymentEnv(String env)` Set deployment environment (e.g., "prod", "staging").
`void`	`setError(Throwable error)` Set the error for this span.
`void`	`setInput(Object input)` Set the input for this span.
`void`	`setInputTokens(long tokens)` Set input tokens.
`void`	`setLogID(String logID)` Set log ID for this span.
`void`	`setMessageID(String messageId)` Set message_id for this span.
`void`	`setMessageIDBaggage(String messageId)` Set message_id baggage for this span and future child spans.
`void`	`setModelFrequencyPenalty(Double frequencyPenalty)` Set model frequency_penalty.
`void`	`setModelMaxTokens(Integer maxTokens)` Set model max_tokens.
`void`	`setModelName(String model)` Set model name.
`void`	`setModelPresencePenalty(Double presencePenalty)` Set model presence_penalty.
`void`	`setModelProvider(String provider)` Set model provider (e.g., "openai", "anthropic").
`void`	`setModelStopSequences(List<String> stopSequences)` Set model stop_sequences.
`void`	`setModelTemperature(Double temperature)` Set model temperature.
`void`	`setModelTopK(Integer topK)` Set model top_k.
`void`	`setModelTopP(Double topP)` Set model top_p.
`void`	`setOutput(Object output)` Set the output for this span.
`void`	`setOutputTokens(long tokens)` Set output tokens.
`void`	`setRuntime(Runtime runt)` Set runtime data.
`void`	`setServiceName(String serviceName)` Set service name for this span.
`void`	`setStartTimeFirstResp(long timestampUs)` Set start time (Not duration!)
`void`	`setStatusCode(int statusCode)` Set status code (0=OK, other=ERROR).
`void`	`setTag(String key, boolean value)` Set custom attribute (boolean).
`void`	`setTag(String key, double value)` Set custom attribute (double).
`void`	`setTag(String key, long value)` Set custom attribute (long).
`void`	`setTag(String key, String value)` Set custom attribute (string).
`void`	`setTags(Map<String,String> tags)` Set multiple tags/attributes at once.
`void`	`setThreadID(String threadId)` Set thread_id for this span.
`void`	`setThreadIDBaggage(String threadId)` Set thread_id baggage for this span and future child spans.
`void`	`setUserID(String userId)` Set user_id for this span.
`void`	`setUserIDBaggage(String userId)` Set user_id baggage for this span and future child spans.
`Map<String,String>`	`toHeader()` Get headers for cross-service propagation.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - CozeLoopSpan
```
public CozeLoopSpan(io.opentelemetry.api.trace.Span span,
                    io.opentelemetry.context.Scope scope,
                    io.opentelemetry.context.propagation.ContextPropagators propagators,
                    CozeLoopContext context,
                    String scene,
                    FinishEventProcessor finishEventProcessor)
```
    Create a new CozeLoopSpan wrapper.
    The span is automatically made current in the OpenTelemetry context, which enables automatic context propagation to child spans.
    
    Parameters:
    
    span - the underlying OpenTelemetry Span
    
    scope - the scope that makes this span current in the context
    
    propagators - the context propagators for header injection
    
    context - the context this span was created in
    
    scene - the scene identifier for this span
    
    finishEventProcessor - the processor to handle span finish events
- Method Detail
  - getTraceID
```
public String getTraceID()
```
    Get the trace ID for this span.
    
    Returns:
    
    the trace ID
  - getSpanID
```
public String getSpanID()
```
    Get the span ID for this span.
    
    Returns:
    
    the span ID
  - getBaggage
```
public Map<String,String> getBaggage()
```
    Get all baggage items.
    
    Returns:
    
    map of baggage keys and values
  - setInput
```
public void setInput(Object input)
```
    Set the input for this span. You can find recommended specification in https://github.com/coze-dev/cozeloop-java/tree/main/cozeloop-core/src/main/java/com/coze/loop/spec/tracespec. Or you can use any struct you like.
    
    Parameters:
    
    input - the input object
  - setOutput
```
public void setOutput(Object output)
```
    Set the output for this span. You can find recommended specification in https://github.com/coze-dev/cozeloop-java/tree/main/cozeloop-core/src/main/java/com/coze/loop/spec/tracespec. Or you can use any struct you like.
    
    Parameters:
    
    output - the output object
  - setError
```
public void setError(Throwable error)
```
    Set the error for this span.
    
    Parameters:
    
    error - the error/exception
  - setStatusCode
```
public void setStatusCode(int statusCode)
```
    Set status code (0=OK, other=ERROR).
    
    Parameters:
    
    statusCode - the status code
  - setUserID
```
public void setUserID(String userId)
```
    Set user_id for this span.
    
    Parameters:
    
    userId - the user ID
  - setUserIDBaggage
```
public void setUserIDBaggage(String userId)
```
    Set user_id baggage for this span and future child spans.
    
    Parameters:
    
    userId - the user ID
  - setMessageID
```
public void setMessageID(String messageId)
```
    Set message_id for this span.
    
    Parameters:
    
    messageId - the message ID
  - setMessageIDBaggage
```
public void setMessageIDBaggage(String messageId)
```
    Set message_id baggage for this span and future child spans.
    
    Parameters:
    
    messageId - the message ID
  - setThreadID
```
public void setThreadID(String threadId)
```
    Set thread_id for this span.
    
    Parameters:
    
    threadId - the thread ID
  - setThreadIDBaggage
```
public void setThreadIDBaggage(String threadId)
```
    Set thread_id baggage for this span and future child spans.
    
    Parameters:
    
    threadId - the thread ID
  - setModelProvider
```
public void setModelProvider(String provider)
```
    Set model provider (e.g., "openai", "anthropic").
    
    Parameters:
    
    provider - the model provider
  - setModelName
```
public void setModelName(String model)
```
    Set model name.
    
    Parameters:
    
    model - the model name
  - setModelTemperature
```
public void setModelTemperature(Double temperature)
```
    Set model temperature.
    
    Parameters:
    
    temperature - the temperature
  - setModelTopP
```
public void setModelTopP(Double topP)
```
    Set model top_p.
    
    Parameters:
    
    topP - the top_p
  - setModelTopK
```
public void setModelTopK(Integer topK)
```
    Set model top_k.
    
    Parameters:
    
    topK - the top_k
  - setModelMaxTokens
```
public void setModelMaxTokens(Integer maxTokens)
```
    Set model max_tokens.
    
    Parameters:
    
    maxTokens - the max_tokens
  - setModelFrequencyPenalty
```
public void setModelFrequencyPenalty(Double frequencyPenalty)
```
    Set model frequency_penalty.
    
    Parameters:
    
    frequencyPenalty - the frequency_penalty
  - setModelPresencePenalty
```
public void setModelPresencePenalty(Double presencePenalty)
```
    Set model presence_penalty.
    
    Parameters:
    
    presencePenalty - the presence_penalty
  - setModelStopSequences
```
public void setModelStopSequences(List<String> stopSequences)
```
    Set model stop_sequences.
    
    Parameters:
    
    stopSequences - the stop_sequences
  - setInputTokens
```
public void setInputTokens(long tokens)
```
    Set input tokens.
    
    Parameters:
    
    tokens - the number of input tokens
  - setOutputTokens
```
public void setOutputTokens(long tokens)
```
    Set output tokens.
    
    Parameters:
    
    tokens - the number of output tokens
  - setStartTimeFirstResp
```
public void setStartTimeFirstResp(long timestampUs)
```
    Set start time (Not duration!) of first response for streaming calls.
    
    Parameters:
    
    timestampUs - the timestamp in microseconds
  - setRuntime
```
public void setRuntime(Runtime runt)
```
    Set runtime data. Do not set unless you know what you are doing.
    
    Parameters:
    
    runt - Runtime
  - setServiceName
```
public void setServiceName(String serviceName)
```
    Set service name for this span.
    
    Parameters:
    
    serviceName - the service name
  - setLogID
```
public void setLogID(String logID)
```
    Set log ID for this span.
    
    Parameters:
    
    logID - the log ID
  - setDeploymentEnv
```
public void setDeploymentEnv(String env)
```
    Set deployment environment (e.g., "prod", "staging").
    
    Parameters:
    
    env - the environment
  - setTags
```
public void setTags(Map<String,String> tags)
```
    Set multiple tags/attributes at once.
    
    Parameters:
    
    tags - map of tags
  - setBaggage
```
public void setBaggage(String key,
                       String value)
```
    Set baggage for this span and future child spans. Baggage is automatically propagated across service boundaries.
    
    Parameters:
    
    key - the baggage key
    
    value - the baggage value
  - setBaggage
```
public void setBaggage(Map<String,String> values)
```
    Set multiple baggage items.
    
    Parameters:
    
    values - map of baggage keys and values
  - toHeader
```
public Map<String,String> toHeader()
```
    Get headers for cross-service propagation.
    
    Returns:
    
    headers containing trace context
  - setTag
```
public void setTag(String key,
                   String value)
```
    Set custom attribute (string).
    
    Parameters:
    
    key - the attribute key
    
    value - the attribute value
  - setTag
```
public void setTag(String key,
                   long value)
```
    Set custom attribute (long).
    
    Parameters:
    
    key - the attribute key
    
    value - the attribute value
  - setTag
```
public void setTag(String key,
                   double value)
```
    Set custom attribute (double).
    
    Parameters:
    
    key - the attribute key
    
    value - the attribute value
  - setTag
```
public void setTag(String key,
                   boolean value)
```
    Set custom attribute (boolean).
    
    Parameters:
    
    key - the attribute key
    
    value - the attribute value
  - getContext
```
public CozeLoopContext getContext()
```
    Get the CozeLoop Context associated with this span.
    This context includes the current span, baggage, and other propagation data. It can be used to create child spans or for manual context propagation.
    
    Returns:
    
    the CozeLoop context
  - finish
```
public void finish()
```
    End the span and close the scope.
    This method is automatically called when using try-with-resources. It ends the span (marking it as finished) and closes the scope (removing it from the current context). The span will then be processed by the BatchSpanProcessor and eventually exported to CozeLoop platform.
  - close
```
public void close()
```
    End the span and close the scope.
    This method is automatically called when using try-with-resources. It ends the span (marking it as finished) and closes the scope (removing it from the current context). The span will then be processed by the BatchSpanProcessor and eventually exported to CozeLoop platform.
    
    Specified by:
    
    close in interface AutoCloseable

Class CozeLoopSpan

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CozeLoopSpan

Method Detail

getTraceID

getSpanID

getBaggage

setInput

setOutput

setError

setStatusCode

setUserID

setUserIDBaggage

setMessageID

setMessageIDBaggage

setThreadID

setThreadIDBaggage

setModelProvider

setModelName

setModelTemperature

setModelTopP

setModelTopK

setModelMaxTokens

setModelFrequencyPenalty

setModelPresencePenalty

setModelStopSequences

setInputTokens

setOutputTokens

setStartTimeFirstResp

setRuntime

setServiceName

setLogID

setDeploymentEnv

setTags

setBaggage

setBaggage

toHeader

setTag

setTag

setTag

setTag

getContext

finish

close