Tracing

# View traces for a session
php artisan vizra:trace {session_id}

# Example: View all traces for session abc123
php artisan vizra:trace abc123

# View trace with additional options
php artisan vizra:trace abc123 --format=tree --show-input --show-output

# View a specific trace ID instead of all session traces
php artisan vizra:trace any-session --trace-id=specific-trace-id

# Clean up old traces
php artisan vizra:trace:cleanup --days=30

Agent Execution (root span)
├── Session Initialization
├── Memory Retrieval
│   ├── Vector Search
│   └── Context Building
├── LLM Request
│   ├── Prompt Construction
│   ├── API Call
│   └── Response Processing
├── Tool Execution
│   ├── Tool: order_lookup
│   └── Tool: send_email
└── Memory Storage

use Vizra\ADK\Tracing\TraceManager;

// Get trace for a session
$trace = TraceManager::forSession($sessionId);

// Loop through all spans
foreach ($trace->spans as $span) {
    echo $span->name . ': ' . $span->duration . "ms\n";
}

// Get performance metrics
$metrics = $trace->getMetrics();
echo "Total Duration: " . $metrics['total_duration'] . "ms\n";
echo "Token Usage: " . $metrics['total_tokens'] . "\n";

use Vizra\ADK\Tracing\Tracer;

class CustomTool extends BaseTool
{
    public function execute(array $parameters): ToolResult
    {
        return Tracer::span('custom_operation', function() use ($parameters) {
            // Add span attributes
            Tracer::addAttribute('operation.type', 'database');
            Tracer::addAttribute('query.complexity', 'high');

            // Your operation
            $result = $this->performOperation($parameters);

            // Add result to span
            Tracer::addEvent('operation_completed', [
                'records_processed' => count($result),
            ]);

            return ToolResult::success($result);
        });
    }
}

// Find slow operations
$slowSpans = $trace->getSlowSpans(1000); // Spans over 1 second

foreach ($slowSpans as $span) {
    echo "Slow operation: {$span->name} took {$span->duration}ms\n";
}

// Analyze token usage
$tokenAnalysis = $trace->analyzeTokenUsage();
echo "Most expensive span: " . $tokenAnalysis['most_expensive']->name;
echo " used " . $tokenAnalysis['most_expensive']->tokens . " tokens\n";

// Find failed spans
$errors = $trace->getErrors();

foreach ($errors as $error) {
    echo "Error in {$error->span->name}: {$error->message}\n";
    echo "Stack trace:\n{$error->stackTrace}\n";
}

'tracing' => [
    'enabled' => env('VIZRA_ADK_TRACING_ENABLED', true),
    'table' => 'agent_trace_spans',
    'cleanup_days' => env('VIZRA_ADK_TRACING_CLEANUP_DAYS', 30),
];

# Enable/disable tracing
VIZRA_ADK_TRACING_ENABLED=true

# Days to keep trace data before cleanup
VIZRA_ADK_TRACING_CLEANUP_DAYS=30

# Clean up old traces (uses config value, default 30 days)
php artisan vizra:trace:cleanup

# Keep last 30 days of traces (delete anything older)
php artisan vizra:trace:cleanup --days=30

# Keep last week of traces (delete anything older)
php artisan vizra:trace:cleanup --days=7

# Keep only today's traces (delete anything from yesterday or earlier)
php artisan vizra:trace:cleanup --days=1

# Delete ALL traces (use with caution!)
php artisan vizra:trace:cleanup --days=0

# Dry run to see what would be deleted
php artisan vizra:trace:cleanup --days=7 --dry-run

# Skip confirmation prompt
php artisan vizra:trace:cleanup --days=7 --force

use Vizra\VizraADK\Services\Tracer;

class CustomOperation
{
    public function process(Tracer $tracer)
    {
        // Start a custom span
        $spanId = $tracer->startSpan(
            type: 'custom_operation',
            name: 'Process Data',
            input: ['records' => 100],
            metadata: ['batch_id' => 'abc123']
        );

        try {
            // Your operation
            $result = $this->doWork();

            // End span with success
            $tracer->endSpan($spanId, ['processed' => 100]);

        } catch (\Throwable $e) {
            // Mark span as failed
            $tracer->failSpan($spanId, $e);
            throw $e;
        }
    }
}