Tracing
For usage examples, see Usage - Tracing.
TracingClient
Client for sending traces to the Mentiora platform.
Methods
- TypeScript
- Python
sendTrace(event: TraceEvent): Promise<SendTraceResult>
Send a trace event to the platform (async only).
Parameters:
event: TraceEvent- The trace event to send
Returns: Promise<SendTraceResult>
Example:
const result = await client.tracing.sendTrace({
traceId: '019505a0-b7c2-7000-8000-000000000001', // UUID v7
spanId: '019505a0-b7c2-7000-8000-000000000002', // UUID v7
name: 'llm.call',
type: 'llm',
startTime: new Date(),
endTime: new Date(),
});
flush(): Promise<void>
Currently a no-op reserved for future batching support. Safe to include in shutdown handlers for forward compatibility.
Returns: Promise<void>
Example:
await client.tracing.flush();
send_trace(event: TraceEvent) -> SendTraceResult
Send a trace event to the platform (synchronous).
Parameters:
event: TraceEvent- The trace event to send
Returns: SendTraceResult
Example:
result = client.tracing.send_trace(TraceEvent(
trace_id='019505a0-b7c2-7000-8000-000000000001', # UUID v7
span_id='019505a0-b7c2-7000-8000-000000000002', # UUID v7
name='llm.call',
type='llm',
start_time=datetime.now(),
end_time=datetime.now(),
))
send_trace_async(event: TraceEvent) -> SendTraceResult
Send a trace event to the platform (asynchronous).
Parameters:
event: TraceEvent- The trace event to send
Returns: SendTraceResult
Example:
result = await client.tracing.send_trace_async(TraceEvent(
trace_id='019505a0-b7c2-7000-8000-000000000001', # UUID v7
span_id='019505a0-b7c2-7000-8000-000000000002', # UUID v7
name='llm.call',
type='llm',
start_time=datetime.now(),
end_time=datetime.now(),
))
flush() -> None
Currently a no-op reserved for future batching support. Safe to include in shutdown handlers for forward compatibility.
Returns: None
Example:
client.tracing.flush()
flush_async() -> None
Async version of flush(). Currently a no-op reserved for future batching support.
Returns: None
Example:
await client.tracing.flush_async()
Types
TraceEvent
- TypeScript
- Python
interface UsageInfo {
prompt_tokens?: number;
completion_tokens?: number;
total_tokens?: number;
}
interface TraceEvent {
traceId: string; // Unique trace ID (UUID v7 format)
spanId: string; // Unique span ID (UUID v7 format)
parentSpanId?: string; // Parent span for nesting (UUID v7 format)
threadId?: string; // Optional. If omitted, the SDK sets it to a new UUID v7 before sending.
name: string; // Span name, e.g., 'llm.call', 'tool.execute'
type: 'llm' | 'tool' | 'chat' | 'error' | 'custom';
input?: unknown; // Prompt, tool input, etc.
output?: unknown; // Response, tool result
startTime: Date | string; // ISO 8601 timestamp
endTime?: Date | string;
durationMs?: number;
metadata?: Record<string, unknown>;
tags?: string[];
error?: TraceError; // Error details (when type === 'error')
usage?: UsageInfo; // Token usage (LLM-specific)
model?: string; // Model name (e.g., 'gpt-4', 'claude-3')
provider?: string; // Provider name (e.g., 'openai', 'anthropic')
}
class UsageInfo:
prompt_tokens: int | None
completion_tokens: int | None
total_tokens: int | None
class TraceEvent:
trace_id: str # Unique trace ID (UUID v7 format)
span_id: str # Unique span ID (UUID v7 format)
parent_span_id: str | None # Parent span for nesting (UUID v7 format)
thread_id: str | None # Optional. If omitted, the SDK sets it to a new UUID v7 before sending.
name: str # Span name, e.g., 'llm.call', 'tool.execute'
type: 'llm' | 'tool' | 'chat' | 'error' | 'custom'
input: Any | None # Prompt, tool input, etc.
output: Any | None # Response, tool result
start_time: datetime | str # ISO 8601 timestamp
end_time: datetime | str | None
duration_ms: int | None
metadata: dict[str, Any] | None
tags: list[str] | None
error: TraceError | None
usage: UsageInfo | None # Token usage (LLM-specific)
model: str | None # Model name (e.g., 'gpt-4', 'claude-3')
provider: str | None # Provider name (e.g., 'openai', 'anthropic')
Note: traceId/trace_id and spanId/span_id must be in UUID v7 format. The plugins automatically generate UUID v7 IDs.
Serialization
model_dump_for_api() (Python only)
Serialize the trace event for the Mentiora API. Handles datetime conversion to ISO 8601 strings and uses camelCase field names as expected by the backend.
event = TraceEvent(...)
payload = event.model_dump_for_api()
# Returns dict with camelCase keys: {'traceId': '...', 'spanId': '...', ...}
TraceError
- TypeScript
- Python
interface TraceError {
message: string;
type?: string;
stack?: string;
}
class TraceError:
message: str
type: str | None
stack: str | None
SendTraceResult
- TypeScript
- Python
interface SendTraceResult {
success: boolean;
traceId: string;
spanId: string;
error?: string;
}
class SendTraceResult:
success: bool
trace_id: str
span_id: str
error: str | None
TraceType
- TypeScript
- Python
type TraceType = 'llm' | 'tool' | 'chat' | 'error' | 'custom';
TraceType = Literal['llm', 'tool', 'chat', 'error', 'custom']