Tracing Classes API Reference

TraceSpan Model

The TraceSpan model represents an individual span within an agent execution trace.

namespace Vizra\VizraADK\Models;

class TraceSpan extends Model
{
    use HasUlids;
}

Properties

Relationships

// Get the parent span
$parentSpan = $span->parent();

// Get child spans
$childSpans = $span->children();

// Get all spans in the same trace
$traceSpans = $span->traceSpans();

Query Scopes

// Filter by trace ID
$spans = TraceSpan::forTrace($traceId)->get();

// Filter by session ID
$spans = TraceSpan::forSession($sessionId)->get();

// Filter by type
$llmCalls = TraceSpan::ofType('llm_call')->get();

// Filter by status
$errors = TraceSpan::withStatus('error')->get();

// Get root spans only
$rootSpans = TraceSpan::rootSpans()->get();

// Order chronologically
$orderedSpans = TraceSpan::chronological()->get();

Helper Methods

// Check if span is completed
if ($span->isCompleted()) {
    echo "Span finished in " . $span->duration_ms . "ms";
}

// Check if span has error
if ($span->hasError()) {
    echo "Error: " . $span->error_message;
}

// Check if root span
if ($span->isRoot()) {
    echo "This is the root span";
}

// Get formatted duration
echo $span->getFormattedDuration(); // "125ms" or "1.5s"

// Get status icon
echo $span->getStatusIcon(); // ✅, ❌, or ⏳

// Get type icon
echo $span->getTypeIcon(); // 🤖, 🧠, 🛠️, or 👥

// Get summary
echo $span->getSummary(); // "🧠 llm_call: gpt-4 - 1.2s ✅"

Tracer Service

The Tracer service manages span creation and lifecycle.

namespace Vizra\VizraADK\Services;

class Tracer
{
    // Service is typically injected via dependency injection
}

Creating Spans

// Start a new span
$spanId = $tracer->startSpan(
    type: 'tool_call',
    name: 'database_query',
    input: ['query' => 'SELECT * FROM users'],
    metadata: ['database' => 'mysql']
);

// End the span successfully
$tracer->endSpan($spanId, [
    'rows_returned' => 42,
    'cache_hit' => false
]);

// Mark span as failed
$tracer->failSpan($spanId, $exception);

Span Types

Trace Management

// Create a new trace
$traceId = $tracer->createTrace(
    sessionId: $context->getSessionId(),
    agentName: 'customer_support'
);

// Set current trace context
$tracer->setCurrentTrace($traceId);

// Get current trace ID
$currentTraceId = $tracer->getCurrentTraceId();

Cleanup Operations

// Get count of old traces
$count = $tracer->getOldTracesCount(30); // 30 days

// Clean up old traces with progress callback
$deleted = $tracer->cleanupOldTraces(30, function($batchCount) {
    echo "Deleted {$batchCount} traces...\n";
});

Usage Examples

Analyzing Trace Performance

use Vizra\VizraADK\Models\TraceSpan;

// Find slowest operations in a trace
$slowestSpans = TraceSpan::forTrace($traceId)
    ->where('duration_ms', '>', 1000)
    ->orderBy('duration_ms', 'desc')
    ->get();

foreach ($slowestSpans as $span) {
    echo $span->getSummary() . "\n";
}

Error Analysis

// Get all errors for a session
$errors = TraceSpan::forSession($sessionId)
    ->withStatus('error')
    ->with('parent')
    ->get();

foreach ($errors as $error) {
    echo "Error in {$error->name}: {$error->error_message}\n";

    // Show parent context
    if ($error->parent) {
        echo "  Parent: {$error->parent->name}\n";
    }
}

Building Trace Trees

// Build hierarchical trace tree
function buildTraceTree(string $traceId): array
{
    $spans = TraceSpan::forTrace($traceId)
        ->with('children')
        ->chronological()
        ->get();

    $tree = [];
    $spanMap = [];

    // First pass: create span map
    foreach ($spans as $span) {
        $spanMap[$span->span_id] = $span;
    }

    // Second pass: build tree
    foreach ($spans as $span) {
        if ($span->isRoot()) {
            $tree[] = $span;
        }
    }

    return $tree;
}