---
title: Debugging
description: Debug tool calls, inspect execution logs, and monitor agent performance with CodeSpar's built-in observability.
---
import { Callout } from "fumadocs-ui/components/callout";
import { Step, Steps } from "fumadocs-ui/components/steps";
# Debugging
Every tool call in CodeSpar is logged with input, output, duration, server, and status. Use the dashboard logs and API to debug failed calls, trace execution, and monitor performance.
## Finding your debugging info
Navigate to your project's **Logs** page in the [dashboard](https://codespar.dev/dashboard/logs) to see all tool executions:
| Column | Description |
|--------|-------------|
| **Timestamp** | When the tool call was executed |
| **Status** | `success`, `running`, or `error` |
| **Tool** | Tool name (e.g., `asaas/create_payment`) |
| **Server** | Which MCP server handled the call |
| **Duration** | Execution time (e.g., `340ms`) |
| **User** | Agent or user that initiated the call |
## Tool call anatomy
Every `ToolResult` returned by `session.execute()` contains debugging information:
```typescript
const result = await session.execute("codespar_pay", {
method: "pix",
amount: 15000,
currency: "BRL",
});
console.log(result);
```
```json title="ToolResult"
{
"success": true,
"data": { "payment_id": "pay_xyz789", "status": "pending" },
"error": null,
"duration": 430,
"server": "asaas",
"tool": "codespar_pay",
"tool_call_id": "tc_9f8e7d6c",
"called_at": "2026-04-17T15:30:00Z"
}
```
**Key fields for debugging:**
- `duration` — Latency in milliseconds. High values may indicate provider issues
- `server` — Which MCP server handled the call (useful when meta-tools auto-route)
- `tool_call_id` — Unique identifier for cross-referencing with dashboard logs
- `error` — Error message if `success` is `false`
## Debugging common issues
### Tool call failed
```json
{
"success": false,
"data": null,
"error": "Invalid parameter: amount must be a positive integer",
"duration": 12,
"server": "codespar",
"tool": "codespar_pay"
}
```
**Low duration + error from `codespar` server** = validation error. Check the tool's `input_schema` for required fields and types.
### Provider timeout
```json
{
"success": false,
"data": null,
"error": "Upstream timeout: asaas did not respond within 30000ms",
"duration": 30012,
"server": "asaas",
"tool": "codespar_pay"
}
```
**High duration + timeout error** = the provider's API is slow or down. CodeSpar retries automatically, but if retries also fail, the error is returned.
### Authentication expired
```json
{
"success": false,
"data": null,
"error": "OAuth token expired for server 'mercadopago'. Re-authorize via session.authorize('mercadopago')",
"duration": 45,
"server": "mercadopago",
"tool": "codespar_pay"
}
```
**Auth error** = the OAuth token for a server has expired. Call `session.authorize(serverId)` to trigger re-authentication.
### Rate limited
```json
{
"success": false,
"data": null,
"error": "Rate limited by provider: melhor-envio (180/200 calls). Resets in 14 minutes.",
"duration": 22,
"server": "melhor-envio",
"tool": "codespar_ship"
}
```
**Rate limit error** = the provider's API has rate limits. Wait for the reset window or reduce call frequency.
## API access to logs
Retrieve tool call logs programmatically:
```bash
curl https://api.codespar.dev/v1/sessions/ses_abc123/logs \
-H "Authorization: Bearer csk_live_abc123..."
```
```json title="Response"
{
"data": [
{
"id": "tc_9f8e7d6c",
"tool": "asaas/create_payment",
"server": "asaas",
"status": "success",
"duration_ms": 340,
"input": { "customer": "cus_000007856824", "billingType": "PIX", "value": 150.00, "dueDate": "2026-04-26" },
"output": { "id": "pay_z8rwa1qnr0twili5", "status": "PENDING" },
"called_at": "2026-04-17T15:30:00Z",
"user": "agent-commerce"
}
],
"total": 18,
"session_id": "ses_abc123"
}
```
### Filter logs
| Parameter | Type | Description |
|-----------|------|-------------|
| `status` | `string` | Filter by status: `success`, `error` |
| `server` | `string` | Filter by server ID |
| `tool` | `string` | Filter by tool name |
| `from` | `string` | Start date (ISO 8601) |
| `to` | `string` | End date (ISO 8601) |
| `limit` | `number` | Results per page (default 50, max 100) |
## Reporting a bug
Your debugging info is tied to your project and helps us trace what happened and fix the issue faster. When you file an issue, paste these three fields:
| Field | Where to find it |
|-------|------------------|
| `project_id` | Top of the [dashboard](https://codespar.dev/dashboard) sidebar, or `codespar whoami` |
| `session_id` | Shown on every log row, or returned from `codespar.create()` (`ses_...`) |
| `tool_call_id` | The `tool_call_id` field on any `ToolResult`, or the log detail panel (`tc_...`) |
Paste them into [github.com/codespar/codespar-core/issues/new](https://github.com/codespar/codespar-core/issues/new) along with the expected vs actual behavior.
```text title="Bug report template"
**Project:** proj_abc123
**Session:** ses_xyz789
**Tool call:** tc_9f8e7d6c
**When:** 2026-04-17T15:30:00Z
**Expected:** codespar_pay returns `success: true` with a payment_id
**Actual:** `success: false` with error "Upstream timeout"
Steps to reproduce:
1. ...
```
We retain full input/output logs for **30 days** on paid plans (7 days on free). If you're reporting an older issue, include as much of the ToolResult JSON as you still have on your end.
## Observability dashboard
The [Logs page](https://codespar.dev/dashboard/logs) provides real-time monitoring:
- **Deployments** — Build status, success rate, average build time
- **Error tracking** — Sentry integration with drill-down to issues
- **Smart alerts** — AI-analyzed alerts with severity (P1-P4) and suggested fixes
- **Live logs** — Real-time log streaming via SSE with level and source filtering
## Best practices
1. **Always check `success`** before using `data`. A `false` success means `data` is `null`.
2. **Log `tool_call_id`** in your application for cross-referencing with the dashboard.
3. **Monitor `duration`** to detect provider degradation early. Set alerts for p95 > 5s.
4. **Use `try/finally`** to ensure `session.close()` runs even when tool calls fail.
5. **Check the dashboard** when debugging production issues — it shows the full input/output of every call.
## Next steps