App Logs groups repeated failures and retains stack, breadcrumbs, request, and release context. Open that project's workspace before you start the thread. Set Claude Code as the default provider, then start Chat or Fix it. Read any diff, and check new events after you deploy.
Capture the failure in the project workspace
A workspace is the boundary around one local folder. Open the repository you want the agent to read. Create the shared Feedback and App Logs key under Settings, then API Key. Select Generate Key, and copy the raw value once. Later reads show only the hint.
Install @aiolaapp/logger for Next.js, React, or Node.js. An Edge Function imports npm:@aiolaapp/logger instead. The Python package is aiola. SDK initialization enables automatic capture for its runtime. SDKs capture uncaught exceptions, unhandled promise rejections, console errors and warnings, failed HTTP requests, and resource-load failures. Manual calls are Aiola.captureException, Aiola.captureMessage, aiola.capture_exception, and aiola.capture_message. Samples are in the setup guide.
Swift, Kotlin, Go, React Native, shell, and other HTTP runtimes can post the contract. Send POST to https://aiola.app/api/app-logs-ingest. Prefer the x-aiola-key header. Bearer is also accepted. The body needs a message or an exception. Fields are in the App Logs reference.
| Status | Meaning |
|---|---|
| 401 | The key is missing or invalid |
| 402 | The owner has neither Pro nor an active trial |
| 403 | Logs are disabled for this project |
| 400 | Invalid JSON, or no message and no exception |
| 429 | The project rate limit was exceeded |
A missing or zero limit falls back to 60 events a minute. Capture a test exception with environment, release, and user context. Confirm the stack, breadcrumbs, and request in App Logs. Repeat it and confirm the events share one group.
Match each source map to its release
Use stable names such as production, staging, and development. Send the deployed release on every event. A top-level release wins when both release fields are present. Otherwise the release tag can supply it.
Upload source maps under that exact release. Open Settings, then App Logs, then Source Maps. Ingest looks up maps by project key and release before it stores resolved frames. Trigger a minified error and confirm the frame shows original source. Check environment and release on the event before you edit.
Read the group before you hand it off
Repeated failures become one issue. The group hash combines project name, exception type, and normalized message. Normalization replaces query and hash values, hexadecimal values, and UUIDs. It also replaces numbers of four or more digits. Quoted strings longer than 20 characters are replaced. IPv4 addresses are replaced too.
| Stored field | What is kept |
|---|---|
| Stack frames | Up to the first 200 |
| Breadcrumbs | Up to the newest 100, in order |
| Request body | 4,096 characters, then a truncation marker |
| Message and exception value | 8,192 characters, then a truncation marker |
| Tags | Up to the first 50 |
Ingest removes authorization, cookie, set-cookie, x-aiola-key, x-api-key, x-auth-token, and proxy-authorization. The dashboard understands fatal, error, warning, info, and debug. Ingest stores any supplied level, and an empty level becomes error.
Filters cover status, time, environment, browser, OS, device, country, and HTTP status. Read one event before you start a thread. Use the stack for the failing frame and breadcrumbs for the earlier trail. Compare environment and release with the open checkout. Do not treat a missing request body as known.
Start Chat or Fix it with Claude Code
Install Claude Code, then run claude login in a terminal. The Providers page does not accept an API key. Enable the CLI only after login succeeds. Set Default Provider to Claude Code under Workspace, then General. A new thread preselects that provider and the Default Model. You bring your own Claude subscription, and Aiola adds no token markup.
Chat on an error or warning uses the App Logs Analysis prompt. Fix it on an error uses the App Logs Fix prompt. The App Logs page also calls these actions Analyze and Fix It. Edit both prompts under Workspace, then Instructions. GUI Lifetime omits those hosted rows.
Turn on Run app log actions in worktree for a fresh worktree. Find it under Workspace, then Git. That toggle is not the Tasks run mode named Worktree.
Central App Logs merges groups and keeps each project name. The action still runs in the owning workspace. The composer can show Provider and model. Context choices can lock after the thread starts. Set the default before you choose Chat or Fix it.
Review the diff in the same workspace
The dashboard panel includes Review, browser tabs, Files, and Terminal. If the thread edits files, open Review with Ctrl+Shift+G and read the git diff. Use the Terminal panel for commands you choose to run.
Commit and push with Commit & Push. Create the pull request with Create PR. In the shortcut list, Command means Command on macOS and Ctrl on Windows. Workspace GitHub shows changed files and diff statistics. Merge applies only to an eligible pull request.
Check the next events in that release
Open App Logs in the same workspace after the deploy. Filter by the environment you shipped, and read the release on each new event. Compare that event with the stack you already read.
Statuses are open, in_progress, human_review, closed, and ignored. Set one to record triage. Changing it does not deploy code. Closed and ignored groups are deleted 30 days after their last event. The other three statuses are not removed by that cleanup.
Repair collection when events never arrive
Missing events can mean the install is wrong. Setup Health points to the affected file and line. It flags an outdated @aiolaapp/logger package and a legacy hardcoded ingest URL. Those App Logs checks run only when a project key exists and logs are not disabled.
Choose the button that updates the logger to the latest version. The setup guide calls that action Update logger. It runs in a workspace directory whose package file lists the logger. The npm command uses install. The pnpm, yarn, and bun commands use add. The action then rescans.
For a legacy endpoint, choose Fix with agent. It asks for https://aiola.app/api/app-logs-ingest, or for the endpoint option to be removed. Removal lets the SDK default apply. Then choose Check again.
A finding stays until a fresh scan no longer detects it. There is no dismiss action. SSH workspaces are skipped. Central pages do not run or show the scan. GUI Lifetime alone does not meet this plan gate. The scan reads local files, so confirm a deployed event in App Logs afterward.
Try it in Aiola: Download Aiola free for macOS 12+ or Windows 10+. There is no Linux build. Bring your own Claude Code subscription, with no token markup. Hosted App Logs and Setup Health require Pro or the seven-day trial. The trial is the 100,000-event Pro Monthly plan for a first-time customer. A card is required.
