Struct TraceSpan 

pub struct TraceSpan {

    pub trace_id: Uuid,
    pub span_id: Uuid,
    pub parent_span_id: Option<Uuid>,
    pub tenant_id: TenantId,
    pub operation_name: String,
    pub start_time: DateTime<Utc>,
    pub end_time: Option<DateTime<Utc>>,
    pub provider: LLMProvider,
    pub model_name: String,
    pub prompt: String,
    pub response: Option<String>,
    pub prompt_tokens: Option<u32>,
    pub completion_tokens: Option<u32>,
    pub total_tokens: Option<u32>,
    pub time_to_first_token_ms: Option<u64>,
    pub duration_ms: Option<u64>,
    pub status_code: Option<u16>,
    pub error_message: Option<String>,
    pub estimated_cost_usd: Option<f64>,
    pub security_score: Option<u8>,
    pub security_findings: Vec<SecurityFinding>,
    pub tags: HashMap<String, String>,
    pub events: Vec<SpanEvent>,
    pub agent_actions: Vec<AgentAction>,
}

A single span within a trace representing a portion of an LLM interaction.

Fields

trace_id: Uuid

Unique identifier for the trace this span belongs to.

span_id: Uuid

Unique identifier for this span.

parent_span_id: Option<Uuid>

Parent span ID if this is a child span.

tenant_id: TenantId

Tenant this span belongs to.

operation_name: String

Name of the operation (e.g., “chat_completion”, “embedding”, “prompt_analysis”).

start_time: DateTime<Utc>

When the span started.

end_time: Option<DateTime<Utc>>

When the span ended (None if still in progress).

provider: LLMProvider

LLM provider used for this span.

model_name: String

Model name/identifier.

prompt: String

The input prompt or messages.

response: Option<String>

The response from the LLM (None if not yet completed).

prompt_tokens: Option<u32>

Number of tokens in the prompt.

completion_tokens: Option<u32>

Number of tokens in the completion/response.

total_tokens: Option<u32>

Total token count (prompt + completion).

time_to_first_token_ms: Option<u64>

Time to first token (TTFT) in milliseconds.

duration_ms: Option<u64>

Processing duration in milliseconds.

status_code: Option<u16>

HTTP status code of the response.

error_message: Option<String>

Error message if the request failed.

estimated_cost_usd: Option<f64>

Estimated cost of this request in USD.

security_score: Option<u8>

Overall security score (0-100, higher = more suspicious).

security_findings: Vec<SecurityFinding>

Security findings detected for this span.

tags: HashMap<String, String>

Custom tags and metadata.

events: Vec<SpanEvent>

Events that occurred during this span (e.g., streaming chunks, analysis results).

agent_actions: Vec<AgentAction>

Agent actions captured during this span (tool calls, commands, web access, etc.).

Implementations

impl TraceSpan

pub fn new( trace_id: Uuid, tenant_id: TenantId, operation_name: String, provider: LLMProvider, model_name: String, prompt: String, ) -> Self

Create a new trace span.

pub fn finish_with_response(self, response: String) -> Self

Finish the span with a response.

pub fn finish_with_error(self, error: String, status_code: Option<u16>) -> Self

Mark the span as failed with an error.

pub fn add_security_finding(&mut self, finding: SecurityFinding)

Add a security finding to this span.

pub fn add_event(&mut self, event: SpanEvent)

Add an event to this span.

pub fn add_agent_action(&mut self, action: AgentAction)

Add an agent action to this span.

pub fn tool_calls(&self) -> Vec<&AgentAction>

Return all tool call actions in this span.

pub fn web_accesses(&self) -> Vec<&AgentAction>

Return all web access actions in this span.

pub fn commands(&self) -> Vec<&AgentAction>

Return all command execution actions in this span.

pub fn has_tool_calls(&self) -> bool

Check if this span has any tool call actions.

pub fn has_web_access(&self) -> bool

Check if this span has any web access actions.

pub fn has_commands(&self) -> bool

Check if this span has any command execution actions.

pub fn duration(&self) -> Option<Duration>

Get the duration of this span.

pub fn is_complete(&self) -> bool

Check if the span is complete.

pub fn is_failed(&self) -> bool

Check if the span failed.

Trait Implementations

impl Clone for TraceSpan

fn clone(&self) -> TraceSpan

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ComposeSchema for TraceSpan

fn compose(generics: Vec<RefOr<Schema>>) -> RefOr<Schema>

impl Debug for TraceSpan

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for TraceSpan

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for TraceSpan

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl ToSchema for TraceSpan

fn name() -> Cow<'static, str>

Return name of the schema.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

Implement reference utoipa::openapi::schema::Schemas for this type.