> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Debug production with an AI agent: logs, traces and errors

> Let an AI agent find why production fails: read errors, logs and traces with forge obs, follow one request to the failing line, and verify the fix.

An AI agent can find out why production is failing without you pasting logs into the chat. It asks the running system, follows one failing request from the error to the line of code, and hands you a fix to review. This guide ran that loop against a real bug in a hosted Forge app, from a Reliant agent chat.

It works because every `forge obs` verb is a read-only query that returns a JSON document with an exit code and complete next commands, and every log line carries its trace ID. [Why this helps an agent](https://docs.reliantlabs.io/hosting/observability/agents.md) explains the design.

## Before you begin

* A Forge API deployed to a hosted environment: [Deploy a Go API with managed Postgres](https://docs.reliantlabs.io/guides/hosting/deploy-go-api-managed-postgres.md).
* Forge v1.6.1 or later in the project (`reliant forge --version`).
* `obs:read` on the organization. Under Reliant, the credential helper grants it from your own account. A CI or automation token needs `obs:read`, minted at [forge.reliantlabs.io/settings/tokens](https://forge.reliantlabs.io/settings/tokens).

The bug used here: `ListProducts` counts in-stock products with a typo, `in_stok`, in its SQL.

**1. Give the agent the tools**

In a Reliant chat there is nothing to set up: the agent's shell already has `reliant forge`, signed in. Ask it to start with `reliant forge agent skill load debug`, which sets the read-only order this guide follows.

In Claude Code or Cursor, add two MCP servers. The local one carries the repo tools (skills, `shapes`, `lint`); the hosted Reliant Forge connector carries the telemetry tools (`obs_status`, `obs_issues`, `obs_issue`, `obs_logs`, `obs_traces`, `obs_check`) after you sign in:

```bash terminal theme={null}
claude mcp add forge -- npx -y @reliantlabs/forge agent mcp
claude mcp add --transport http reliant-forge https://api.reliantapi.com/forge/mcp
```

```json .cursor/mcp.json theme={null}
{
  "mcpServers": {
    "forge": {"command": "npx", "args": ["-y", "@reliantlabs/forge", "mcp"]},
    "reliant-forge": {"url": "https://api.reliantapi.com/forge/mcp"}
  }
}
```

Signing in asks which organization, projects and tools the connector may use; revoke it under Settings → Access tokens.

**2. Ask what is wrong now**

```bash terminal theme={null}
reliant forge obs status prod --since 15m
```

```text Output (trimmed) theme={null}
prod (cloud backend), 2026-11-20T09:09:10Z .. 2026-11-20T09:24:10Z
release v4.4.0, promoted 7m ago
telemetry: last log 1m ago, last span 1m ago

SERVICE     RATE    ERRORS  P95  ERROR LOGS
api         0.03/s  100.0%  6ms  62

ISSUE                                 STATUS  SERVICE  EVENTS  LAST SEEN  TITLE
aeb59d1e-69cb-4503-aa4c-56210ad60bd6  new     api      31      1m         *pgconn.PgError: rpc failed
```

One document says which release is live, that telemetry is arriving, and that every `api` request fails. With `--json`, its `suggested[]` names the next commands.

**3. Read the error logs**

The caller sees only `{"code":"internal","message":"internal server error"}`. The cause is in the logs:

```bash terminal theme={null}
reliant forge obs logs prod --severity error --since 15m --limit 2
```

```text Output (trimmed) theme={null}
TIME          SEVERITY  SERVICE  BODY
09:23:04.462  ERROR     api      rpc failed  error="internal: internal server error" cause="ERROR: column \"in_stok\" does not exist (SQLSTATE 42703)" …
09:23:04.461  ERROR     api      audit.event  error="internal: internal server error" code=internal
```

**4. Follow one failing request**

List failing traces, then print one as a tree:

```bash terminal theme={null}
reliant forge obs traces prod --errors --since 15m --limit 2
reliant forge obs trace 0424f332f688c04084efb392c124aeac prod
```

```text Output (trimmed) theme={null}
trace 0424f332f688c04084efb392c124aeac  2.5ms  2 spans
* api services.catalog.v1.CatalogService/ListProducts  2.5ms  rpc=INTERNAL  ERROR internal server error
  ↳ log ERROR rpc failed: … cause="ERROR: column \"in_stok\" does not exist (SQLSTATE 42703)" …
*└─  api SELECT products  1.4ms  ERROR *pgconn.PrepareError: ERROR: column "in_stok" does not exist (SQLSTATE 42703)
```

The database span names the failing statement. With `--json` the document also carries the release live when the trace started (`v4.4.0`).

**5. Pull the issue as JSON**

`--fields` keeps only what the agent needs:

```bash terminal theme={null}
reliant forge obs issue aeb59d1e-69cb-4503-aa4c-56210ad60bd6 prod --json \
  --fields issue.culprit,latest_event.trace_id,first_release,suspect_commits
```

```json Output (trimmed) theme={null}
"issue": {"culprit": "internal/handlers/catalog/handlers_crud.go in …catalog.(*Service).ListProducts"},
"latest_event": {"trace_id": "0424f332f688c04084efb392c124aeac"},
"first_release": {"version": "v4.4.0", "git_commit": "5da1e047f41c…"},
"suspect_commits": [{"sha": "5da1e047f41c…", "subject": "catalog: products with an in-stock count",
  "files": ["internal/handlers/catalog/handlers_crud.go"]}]
```

From here the agent read `handlers_crud.go`, found the call into `CountInStockProducts`, and proposed a one-line fix: `in_stok` to `in_stock`. [Find the release that caused an error](https://docs.reliantlabs.io/guides/observability/find-release-that-caused-error.md) covers issues and releases in depth.

**6. Reproduce it on your machine**

The same verbs read `dev`, your local stack. Start it with `reliant forge env up dev`, call the RPC, and every log is a file:

```bash terminal theme={null}
grep -l in_stok .forge/logs/dev/*.log
reliant forge obs endpoints dev
```

```text Output theme={null}
.forge/logs/dev/api.log
SERVICE  ENDPOINT                                         REQUESTS  ERRORS  RATE    P50    P95   P99
api      services.catalog.v1.CatalogService/ListProducts  5         100.0%  0.01/s  0.6ms  56ms  56ms
```

Each JSON line in `api.log` carries `trace_id`, `code.file.path` and `code.line.number`, so `reliant forge obs trace <id>` prints the same tree locally. Browser errors land beside them: `grep '\[browser:error\]' .forge/logs/dev/*.log`. Stop the stack with `reliant forge env down dev`.

**7. Ship the fix and verify it**

Review the diff, then cut and deploy a release as usual (`reliant forge env build prod --release v4.4.1`, then `reliant forge env deploy prod v4.4.1 --yes`). Send traffic and check:

```bash terminal theme={null}
reliant forge obs endpoints prod --since 3m
```

```text Output theme={null}
SERVICE  ENDPOINT                                         REQUESTS  ERRORS  RATE    P50    P95    P99
api      services.catalog.v1.CatalogService/ListProducts  32        0.0%    0.18/s  5.0ms  5.5ms  5.5ms
```

The error rate is 0%. The issue's alert keeps firing until someone resolves the issue, which is triage, not a read. To judge the whole release, run `reliant forge obs check prod --wait --json`.

## What this does not do

* The agent only reads. `obs` reads change nothing; resolving, assigning or commenting on an issue needs `obs:triage`, and the agent does not deploy or roll back here. You review the fix and ship it.
* There is no automatic rollback. You recover by deploying an earlier or fixed release.
* An alert does not fix itself. Turning alerts into investigated issues and pull requests is two steps with a person between them: [Turn production alerts into GitHub issues](https://docs.reliantlabs.io/guides/workflows/production-alerts-to-github-issues.md).
* Reads are rate limited per credential: today, 60 telemetry reads a minute per organization, on a query lane separate from the console, so a looping agent cannot blank your dashboards. Release-health reads (`obs check`) get 6 a minute with a burst of 40. A refused read exits 2.
* Monitoring needs sign-in; there is no anonymous path. Database rows are a separate grant: [Let AI agents query production data](https://docs.reliantlabs.io/guides/forge/let-agents-query-production-data.md).

## Troubleshooting

> [accordion] exit 2 from an obs read
>
> Forge could not look: a missing `obs:read` scope (`does not carry the obs:read scope`), a rate limit or quota, or telemetry that is off. It does not mean "no errors". Read the document's `error`, fix that, and run the read again. See [the exit codes](https://docs.reliantlabs.io/hosting/observability/forge-obs.md#the-exit-codes).

> [accordion] /bin/sh: 1: forge: not found
>
> `env up dev` has only `reliant forge` to call. The fix is in [Build a Go and React app](https://docs.reliantlabs.io/guides/forge/build-go-react-app-connect-rpc.md#troubleshooting).

## Next steps

> [card] [Find the release that caused an error](https://docs.reliantlabs.io/guides/observability/find-release-that-caused-error.md)
>
> Go from an issue to the release and commits that introduced it, then resolve it.

> [card] [Let agents query production data](https://docs.reliantlabs.io/guides/forge/let-agents-query-production-data.md)
>
> Give an agent read-only, audited SQL against production.

> [card] [Why this helps an agent](https://docs.reliantlabs.io/hosting/observability/agents.md)
>
> Exit codes, skills, `shapes` and the forge MCP server.

> [card] [Querying with forge obs](https://docs.reliantlabs.io/hosting/observability/forge-obs.md)
>
> Every verb, the JSON contract and the exit codes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.