Logging & Usage
Inspect Matrix OS kernel logs, token usage, the usage API, file audit trails, and log rotation while keeping operational details out of client errors.
Maintained by the Matrix OS team. Product instructions are updated with the supported workflow.
Matrix OS provides structured logging for every kernel operation: dispatches, tool calls, agent spawns, file mutations, and costs. This data powers debugging, billing, security auditing, and usage dashboards.
Interaction Logs
Every kernel dispatch is logged as a JSONL entry in ~/system/logs/. Daily rotation is built in (one file per day).
Log Entry Fields
| Field | Type | Description |
|---|---|---|
timestamp | string | ISO 8601 timestamp |
senderId | string | User or channel that triggered the dispatch |
conversationId | string | Session ID for conversation threading |
model | string | Claude model used (e.g., claude-opus-4-6) |
agentName | string | Which agent handled the request |
tokensIn | number | Input tokens consumed |
tokensOut | number | Output tokens generated |
cost | number | Dollar cost of the dispatch |
durationMs | number | Wall-clock time |
tools | array | Tool executions (see below) |
status | string | success or error |
error | object | Error details if failed (name, message, truncated stack) |
batch | boolean | Whether this was a batch dispatch entry |
batchId | string | Correlation ID for batch entries |
Tool Execution Logging
Each tool call within a dispatch is recorded:
{
"tools": [
{
"name": "Write",
"durationMs": 45,
"inputPreview": "Write to ~/apps/chess/index.html (2.3KB)",
"status": "success"
},
{
"name": "Bash",
"durationMs": 3200,
"inputPreview": "cd ~/apps/chess && pnpm install",
"status": "success"
}
]
}Tool outputs are not logged (too large). Only errors are captured from tool results.
Structured Errors
On dispatch failure, the error is captured with full context:
{
"error": {
"name": "ToolExecutionError",
"message": "pnpm install failed with exit code 1",
"stack": "Error: pnpm install failed...\n at runBuild (/packages/...)",
"tool": "Bash",
"turn": 3
}
}Usage Tracking
The usage tracker aggregates costs and token consumption per user:
How It Works
On each dispatch completion, cost and token data is recorded per senderId. Data is aggregated by user, model, and day, and persisted to ~/system/logs/usage.jsonl.
Usage API
GET /api/usage?userId=hamed&startDate=2026-03-01&endDate=2026-03-31&groupBy=dayResponse:
{
"totalCost": 12.45,
"totalTokensIn": 1250000,
"totalTokensOut": 320000,
"entries": [
{
"date": "2026-03-01",
"cost": 0.85,
"tokensIn": 95000,
"tokensOut": 24000,
"dispatches": 12
}
]
}Authentication
The usage endpoint requires a valid session or admin token.
Cost Limits
Per-user cost limits are configurable in ~/system/config.json:
{
"costLimits": {
"daily": 10.00,
"monthly": 100.00
}
}When a user exceeds their limit, the dispatcher rejects new dispatches with HTTP 429 and a message: "Daily cost limit reached." Set a limit to 0 for unlimited.
File Audit Trail
A lightweight audit log tracks all file mutations performed by the kernel. Written to ~/system/logs/audit.jsonl.
Audit Entry Format
{
"timestamp": "2026-03-04T10:30:00Z",
"op": "write",
"path": "apps/chess/index.html",
"sizeBytes": 2340,
"actor": "builder",
"agentName": "builder"
}| Field | Description |
|---|---|
op | Operation: write, delete, mkdir |
path | Relative path within ~/matrixos/ |
sizeBytes | Size of the written file |
actor | Agent or system component that performed the operation |
agentName | Name of the kernel agent |
Instrumentation
File mutations are detected via PreToolUse and PostToolUse hooks on the Write, Edit, and Bash tools. Read operations are not audited (too noisy).
The audit logger (packages/kernel/src/audit.ts) uses async buffered writes to avoid blocking kernel operations.
Log Rotation
| Log File | Rotation | Retention |
|---|---|---|
activity.log | Daily (rename to activity-{YYYY-MM-DD}.log) | 30 days |
audit.jsonl | Daily (rename to audit-{YYYY-MM-DD}.jsonl) | 30 days |
| Interaction logs | Already daily by filename | 30 days |
Rotation runs in the heartbeat service (daily check). Files older than 30 days are deleted automatically.
Log Files Summary
| File | Location | Format | Contents |
|---|---|---|---|
| Interaction logs | ~/system/logs/interactions-{date}.jsonl | JSONL | Dispatch events with tokens, cost, tools |
| Activity log | ~/system/logs/activity.log | Text | General system activity |
| Audit log | ~/system/logs/audit.jsonl | JSONL | File mutation events |
| Usage log | ~/system/logs/usage.jsonl | JSONL | Per-user cost aggregation |
| Storage log | ~/system/logs/storage.jsonl | JSONL | Daily storage measurements |
| Backup log | ~/system/logs/backup.jsonl | JSONL | Postgres backup status |
How is this guide?
Skills System
Skill validation, runtime synchronization, the Matrix app-building and collaboration skill pack, and public skills.sh distribution.
Testing
Follow test-driven development in Matrix OS. Learn how to run tests, organize unit and integration suites, and check coverage before reviewing a change.

