---
name: ivy
description: "Debug production AWS Lambda issues with Ivy: errors, 500s, timeouts, slow invocations, cold starts, failing AWS SDK calls, and checking whether a fix worked after deploy. Use when the user reports a production problem in a Lambda function traced by Ivy (ivytrace.dev), or asks to verify a deploy."
---

# Debugging production with Ivy

Ivy records every invocation of the user's traced Lambda functions: the event, the response, errors and stack
traces, cold starts, and every AWS SDK and HTTP call with its payload and timing. Use it to find out what actually
happened in production before changing code.

## Access

Use whichever of these is available, in this order:

1. **Ivy's MCP server** (`https://ivytrace.dev/mcp`). If its tools are connected, use them: `list_workspaces`,
   `find_failing_invocations`, `search_invocations`, `list_error_groups`, `get_trace_summary`, `compare_invocations`,
   `render_waterfall`, `render_graph`. Every tool except `list_workspaces` takes optional `workspace` and `project`
   (slug or ID); pass the ones from "Repo context" below. Results are labelled `[workspace]`.
2. **The HTTP API** at `https://ivytrace.dev/api`, with `Authorization: Bearer <access token>` from the sign-in in
   https://ivytrace.dev/llms.txt (OAuth device flow). Refresh the token as described there when it expires.
   Reference: `https://ivytrace.dev/api/openapi.json` and `https://ivytrace.dev/api/docs`. Data routes are scoped to a
   workspace and project, `P=/api/w/<workspace>/p/<project>`:
   - `GET $P/invocations?function=<name>&status=error&since=1h`: failing invocations.
   - `GET $P/errors?since=24h`: error groups (`/api/w/<workspace>/errors` covers every project).
   - `GET $P/traces/<trace_id>?format=text`: one trace as a compact text tree. Prefer it over the JSON form.
   - `GET $P/functions?since=24h`: per-function counts, error rates and latency percentiles.

Never print, log or commit tokens. Keep them in memory or in the agent's own credential store, never in this repo.

If neither is available, tell the user and point them to https://ivytrace.dev/llms.txt to set Ivy up.

## Choosing scope

The user can have several workspaces, each with several projects (environments are separate projects, for
example `checkout-prod` and `checkout-staging`). Before querying:

1. Use the workspace and project from "Repo context" below when they are filled in.
2. Otherwise list them (`list_workspaces`, or `GET /api/workspaces` and `GET /api/w/<workspace>/projects`) and pick
   the one that matches this repo by project or function name.
3. If more than one could match, ask the user. Don't guess. Production problems are usually in the `-prod` project.

## The debugging loop

1. **Find the failures.** For the function in question, get the failing invocations or error groups over a window that
   covers the report (for example `since: 2h`). Note how many, since when, and whether one error group dominates.
2. **Read one failing trace.** Get it as text (`get_trace_summary`, or `?format=text`). Use `render_waterfall` or
   `render_graph` when a picture helps the user. Find the first span that failed and its error message. Link the user to
   `https://ivytrace.dev/w/<workspace>/<project>/traces/<trace_id>`.
3. **Compare with a success.** Take a recent successful invocation of the same function (`compare_invocations`, or
   fetch both). Look at what differs: inputs, a missing field, a slower dependency, a different code path.
4. **Map it to the code.** Use the failing span (service, operation, resource) and the stack trace to find the code
   in this repo. Explain the cause in one or two sentences, then fix it. Add or adjust a test when the repo has tests.
5. **Verify after deploy.** Once the fix is deployed, check new invocations of the function. The error group should
   stop growing, and fresh traces of the same path should succeed. Report what you checked.

For slow invocations and timeouts, read the waterfall: find the longest span, check whether it is a cold start, a
slow AWS call or external HTTP request, or calls made one after another that could run in parallel.

## Care with data

Traces contain real request and response payloads, which can include personal data.

- Quote only the fields you need to explain the problem.
- Never copy payloads into code, tests, fixtures, commits or issue trackers. Write synthetic test data instead.
- Respect redaction. Fields shown as redacted stay redacted; don't try to recover them.
- Don't invoke functions, replay events or change infrastructure without asking the user first.

## Repo context

<!-- Filled in by the installing agent. Keep it short. -->

- Ivy workspace: <!-- workspace slug -->
- Ivy project: <!-- project slug -->
- Main functions: <!-- function names, one per line or comma-separated -->