Telemetry

Telemetry Data Flow
    ├── Orbit Level
    │   ├── Total execution time
    │   ├── Aggregated token usage
    │   ├── Total API calls
    │   └── All tasks metrics
    │       │
    │       ├── Task Level
    │       │   ├── Task execution time
    │       │   ├── Task token usage
    │       │   ├── Task API calls
    │       │   ├── Validation results
    │       │   └── Tools used
    │       │       │
    │       │       └── Tool Level
    │       │           ├── Tool name
    │       │           ├── Execution time
    │       │           ├── Success status
    │       │           ├── Input size
    │       │           └── Output size
    │       │
    │       └── Agent Level
    │           ├── Execution count
    │           ├── Average execution time
    │           └── Cumulative metrics
    │
    └── External Integration
        ├── TelemetryManager
        ├── Custom Analytics
        ├── Monitoring Dashboards
        └── Alerting Systems

public struct UsageMetrics: Codable, Sendable {
    public let promptTokens: Int          // Tokens in prompts
    public let completionTokens: Int      // Tokens in responses
    public let totalTokens: Int           // Total token usage
    public let successfulRequests: Int    // Successful API calls
    public let totalRequests: Int         // Total API calls made
}

import Foundation

// Start orbit asynchronously
Task {
    try await orbit.run()
}

// Monitor while running
while await orbit.isRunning() {
    let status = await orbit.getExecutionStatus()

    print("\r⏳ Progress: \(status.completionPercentage)% ", terminator: "")
    print("| Active: \(status.activeTasks) ", terminator: "")
    print("| Completed: \(status.completedTasks)/\(status.totalTasks) ", terminator: "")
    print("| Failed: \(status.failedTasks)", terminator: "")

    try await Task.sleep(for: .seconds(1))
}

print("\n✅ Complete!")

public struct ToolUsage: Codable, Sendable {
    public let toolName: String           // Name of the tool used
    public let executionTime: TimeInterval // Tool execution duration
    public let success: Bool              // Execution success status
    public let inputSize: Int             // Size of tool input
    public let outputSize: Int            // Size of tool output
}

// Which tasks use which tools?
for (index, taskOutput) in result.taskOutputs.enumerated() {
    guard let task = orbit.tasks[safe: index] else { continue }

    if !taskOutput.toolsUsed.isEmpty {
        print("\nTask \(index + 1): \(task.description)")
        print("  Tools: \(taskOutput.toolsUsed.map { $0.toolName }.joined(separator: ", "))")

        // Tool execution sequence
        print("  Execution order:")
        for (i, toolUsage) in taskOutput.toolsUsed.enumerated() {
            let status = toolUsage.success ? "✓" : "✗"
            print("    \(i + 1). \(toolUsage.toolName) (\(String(format: "%.2f", toolUsage.executionTime))s) \(status)")
        }
    }
}

// Tool correlation analysis
print("\n🔗 Tool Correlation:")
print("  (Which tools are often used together?)")

var toolPairs: [String: Int] = [:]
for taskOutput in result.taskOutputs {
    let tools = taskOutput.toolsUsed.map { $0.toolName }
    for i in 0..<tools.count {
        for j in (i+1)..<tools.count {
            let pair = "\(tools[i]) + \(tools[j])"
            toolPairs[pair, default: 0] += 1
        }
    }
}

for (pair, count) in toolPairs.sorted(by: { $0.value > $1.value }).prefix(5) {
    print("  \(pair): \(count) times")
}

final class BudgetTracker {
    let dailyLimit: Double
    let monthlyLimit: Double

    private var dailyCost: Double = 0
    private var monthlyCost: Double = 0
    private var lastResetDate: Date = Date()

    init(dailyLimit: Double, monthlyLimit: Double) {
        self.dailyLimit = dailyLimit
        self.monthlyLimit = monthlyLimit
    }

    func trackExecution(metrics: UsageMetrics, model: String) throws {
        resetIfNeeded()

        let cost = calculateOpenAICost(metrics: metrics, model: model)

        // Check limits
        if dailyCost + cost > dailyLimit {
            throw BudgetError.dailyLimitExceeded(
                current: dailyCost,
                limit: dailyLimit,
                attempted: cost
            )
        }

        if monthlyCost + cost > monthlyLimit {
            throw BudgetError.monthlyLimitExceeded(
                current: monthlyCost,
                limit: monthlyLimit,
                attempted: cost
            )
        }

        // Update tracking
        dailyCost += cost
        monthlyCost += cost

        print("💰 Budget Status:")
        print("  Daily: $\(String(format: "%.2f", dailyCost))/$\(String(format: "%.2f", dailyLimit))")
        print("  Monthly: $\(String(format: "%.2f", monthlyCost))/$\(String(format: "%.2f", monthlyLimit))")
    }

    private func resetIfNeeded() {
        let calendar = Calendar.current
        let now = Date()

        // Reset daily if new day
        if !calendar.isDate(lastResetDate, inSameDayAs: now) {
            dailyCost = 0
        }

        // Reset monthly if new month
        if !calendar.isDate(lastResetDate, equalTo: now, toGranularity: .month) {
            monthlyCost = 0
        }

        lastResetDate = now
    }

    enum BudgetError: Error {
        case dailyLimitExceeded(current: Double, limit: Double, attempted: Double)
        case monthlyLimitExceeded(current: Double, limit: Double, attempted: Double)
    }
}

// Usage
let budgetTracker = BudgetTracker(
    dailyLimit: 10.00,    // $10/day
    monthlyLimit: 200.00  // $200/month
)

do {
    let result = try await orbit.run()
    try budgetTracker.trackExecution(
        metrics: result.usageMetrics,
        model: "gpt-4o"
    )
} catch BudgetTracker.BudgetError.dailyLimitExceeded(let current, let limit, let attempted) {
    print("⚠️ Daily budget exceeded!")
    print("  Current: $\(current)")
    print("  Limit: $\(limit)")
    print("  Attempted: $\(attempted)")
}

public protocol TelemetryManager {
    // Lifecycle events
    func orbitStarted(orbitId: String, name: String)
    func orbitCompleted(orbitId: String, output: OrbitOutput)
    func orbitFailed(orbitId: String, error: Error)

    // Task events
    func taskStarted(taskId: String, description: String)
    func taskCompleted(taskId: String, output: TaskOutput)
    func taskFailed(taskId: String, error: Error)

    // Agent events
    func agentExecuted(agentId: String, role: String, metrics: UsageMetrics)

    // Tool events
    func toolInvoked(toolName: String, parameters: [String: Any])
    func toolCompleted(toolName: String, usage: ToolUsage)

    // Custom events
    func logEvent(name: String, properties: [String: Any])
    func logMetric(name: String, value: Double, tags: [String: String])
}

let orbit = try await Orbit.create(
    name: "Monitored Workflow",
    agents: agents,
    tasks: tasks,
    stepCallback: "onStepComplete"
)

// Define callback
func onStepComplete(step: ExecutionStep) {
    print("📍 Step completed:")
    print("  Orbit: \(step.orbitId)")
    print("  Task: \(step.taskDescription)")
    print("  Agent: \(step.agentRole)")
    print("  Duration: \(String(format: "%.2f", step.duration))s")
    print("  Progress: \(step.progressPercentage)%")

    // Custom telemetry
    telemetryManager.logEvent(
        name: "step_completed",
        properties: [
            "orbit_id": step.orbitId,
            "task_id": step.taskId,
            "agent_id": step.agentId,
            "duration": step.duration,
            "progress": step.progressPercentage
        ]
    )

    // Update UI/dashboard
    updateDashboard(step: step)
}