Observing

Every Perstack execution produces a complete audit trail. Use events and checkpoints to monitor, debug, and verify Expert behavior.

Event stream

perstack run outputs JSON events to stdout:


npx perstack run my-expert "query" | tee execution.jsonl

Each line is a JSON object:


{"type":"startRun","timestamp":1234567890,"runId":"abc123",...}
{"type":"startGeneration","timestamp":1234567891,...}
{"type":"finishGeneration","timestamp":1234567892,...}
{"type":"finishStep","timestamp":1234567893,...}
{"type":"finishRun","timestamp":1234567894,...}

Event types

Event	When	Key fields
`startRun`	Run begins	`runId`, `expertKey`, `query`
`startGeneration`	LLM call starts	`step`
`finishGeneration`	LLM call ends	`step`, `usage`, `toolCalls`
`finishStep`	Step completes	`step`, `checkpoint`
`finishRun`	Run ends	`stopReason`, `totalUsage`
`errorRun`	Error occurs	`error`, `message`

Filtering events

Use jq to extract specific information:


# Errors only
npx perstack run my-expert "query" | jq 'select(.type == "errorRun")'
 
# Token usage per step
npx perstack run my-expert "query" | jq 'select(.type == "finishGeneration") | {step, usage}'
 
# Final result
npx perstack run my-expert "query" | jq 'select(.type == "finishRun")'

Checkpoints

Checkpoints are saved to perstack/runs/{runId}/ in the workspace:


perstack/runs/abc123/
├── run-setting.json
├── checkpoint-1234567893-1-xyz.json
├── checkpoint-1234567895-2-xyz.json
└── event-1234567890-0-startRun.json

Each checkpoint contains complete state — message history, usage, Expert info — enabling replay and forensic analysis.

Integrating with monitoring

CloudWatch (AWS)


npx perstack run my-expert "query" 2>&1 | \
  while read line; do
    echo "$line" | aws logs put-log-events ...
  done

Or use ECS/Fargate log drivers to capture stdout automatically.

Custom integration


import { run } from "@perstack/runtime"
 
await run(params, {
  eventListener: (event) => {
    // Send to your monitoring system
    metrics.increment(`perstack.${event.type}`)
    if (event.type === "errorRun") {
      alerting.notify(event)
    }
    if (event.type === "finishRun") {
      metrics.gauge("perstack.tokens", event.totalUsage.totalTokens)
    }
  }
})

Auditing checklist

For compliance and security audits:

All runs produce event logs
Checkpoints retained for required period
Token usage tracked per Expert/run
Errors monitored and alerted
Event logs correlated with platform audit logs

What’s next

Runtime — how events and checkpoints work
Error Handling — handling failures
Isolation by Design — security configuration