Skip to main content

intentusnet inspect

Inspect execution records for debugging, auditing, and analysis.

Synopsis​

intentusnet inspect [execution_id] [options]

Options​

OptionDescription
--listList all executions
--status STATUSFilter by status: success, error, incomplete
--intent NAMEFilter by intent name
--agent NAMEFilter by agent name
--since DATETIMEFilter executions since datetime
--until DATETIMEFilter executions until datetime
--limit NLimit results (default: 100)
--eventsInclude full event trace
--envelopeInclude original envelope
--error-code CODEFilter by error code

Examples​

Inspect Single Execution​

intentusnet inspect exec-a1b2c3d4

Output:

{
  "execution_id": "exec-a1b2c3d4",
  "created_at": "2024-01-15T10:30:00.123456Z",
  "intent": "ProcessIntent",
  "intent_version": "1.0",
  "status": "completed",
  "agent": "processor-a",
  "latency_ms": 127,
  "envelope_hash": "sha256:e3b0c44298fc1c149afbf4c8996fb924...",
  "replayable": true,
  "event_count": 5,
  "routing": {
    "strategy": "DIRECT",
    "decision": "deterministic_match"
  }
}

With Full Events​

intentusnet inspect exec-a1b2c3d4 --events
{
  "execution_id": "exec-a1b2c3d4",
  ...
  "events": [
    {
      "seq": 1,
      "type": "INTENT_RECEIVED",
      "timestamp": "2024-01-15T10:30:00.100Z",
      "payload": {"intent": "ProcessIntent"}
    },
    {
      "seq": 2,
      "type": "AGENT_ATTEMPT_START",
      "timestamp": "2024-01-15T10:30:00.105Z",
      "payload": {"agent": "processor-a", "attempt": 1}
    },
    {
      "seq": 3,
      "type": "AGENT_ATTEMPT_END",
      "timestamp": "2024-01-15T10:30:00.220Z",
      "payload": {"agent": "processor-a", "status": "success", "latency_ms": 115}
    },
    {
      "seq": 4,
      "type": "ROUTER_DECISION",
      "timestamp": "2024-01-15T10:30:00.225Z",
      "payload": {"agent": "processor-a", "reason": "deterministic_match"}
    },
    {
      "seq": 5,
      "type": "FINAL_RESPONSE",
      "timestamp": "2024-01-15T10:30:00.227Z",
      "payload": {"status": "success"}
    }
  ]
}

With Original Envelope​

intentusnet inspect exec-a1b2c3d4 --envelope
{
  "execution_id": "exec-a1b2c3d4",
  ...
  "envelope": {
    "version": "1.0",
    "intent": {"name": "ProcessIntent", "version": "1.0"},
    "payload": {"data": "original input"},
    "context": {...},
    "metadata": {...},
    "routing": {...}
  }
}

List All Executions​

intentusnet inspect --list
[
  {
    "execution_id": "exec-a1b2c3d4",
    "created_at": "2024-01-15T10:30:00Z",
    "intent": "ProcessIntent",
    "status": "completed",
    "agent": "processor-a"
  },
  {
    "execution_id": "exec-e5f6g7h8",
    "created_at": "2024-01-15T10:31:00Z",
    "intent": "ProcessIntent",
    "status": "error",
    "agent": "processor-a"
  }
]

Text Format List​

intentusnet inspect --list --format text
EXECUTION_ID      CREATED_AT           INTENT           STATUS     AGENT
exec-a1b2c3d4     2024-01-15T10:30:00  ProcessIntent    completed  processor-a
exec-e5f6g7h8     2024-01-15T10:31:00  ProcessIntent    error      processor-a
exec-i9j0k1l2     2024-01-15T10:32:00  SearchIntent     completed  searcher-b

Filter by Status​

intentusnet inspect --list --status error

Filter by Intent​

intentusnet inspect --list --intent ProcessIntent

Filter by Agent​

intentusnet inspect --list --agent processor-a

Filter by Time Range​

# Since a specific time
intentusnet inspect --list --since "2024-01-15T10:00:00Z"

# Until a specific time
intentusnet inspect --list --until "2024-01-15T12:00:00Z"

# Time range
intentusnet inspect --list \
    --since "2024-01-15T10:00:00Z" \
    --until "2024-01-15T12:00:00Z"

Filter by Error Code​

intentusnet inspect --list --error-code AGENT_TIMEOUT

Limit Results​

intentusnet inspect --list --limit 10

Inspect Incomplete Executions​

intentusnet inspect --list --status incomplete

Output:

[
  {
    "execution_id": "exec-m3n4o5p6",
    "created_at": "2024-01-15T10:35:00Z",
    "intent": "ProcessIntent",
    "status": "incomplete",
    "last_event": {
      "seq": 2,
      "type": "AGENT_ATTEMPT_START"
    },
    "replayable": false,
    "replayable_reason": "execution_incomplete"
  }
]

Advanced Usage​

Analyze Fallback Patterns​

intentusnet inspect --list --format json | jq '
  [.[] | select(.routing.strategy == "FALLBACK")] |
  group_by(.routing.attempts | length) |
  map({attempts: .[0].routing.attempts | length, count: length})
'

Find Slow Executions​

intentusnet inspect --list --format json | jq '
  [.[] | select(.latency_ms > 1000)] |
  sort_by(.latency_ms) |
  reverse
'

Error Code Distribution​

intentusnet inspect --list --status error --format json | jq '
  group_by(.error.code) |
  map({code: .[0].error.code, count: length}) |
  sort_by(.count) |
  reverse
'

Export for Analysis​

intentusnet inspect --list --format json > executions.json

Exit Codes​

CodeMeaning
0Success
1General error
10Record not found
12Invalid filter

See Also​