Set Up App Logs

This procedure takes a workspace from no logger to a verified grouped issue. Payload details and limits live in App Logs.

Generate the project key

Open Settings → API Key, select Generate Key, and copy the raw value once.

Framework/package/environment matrix

Tab	Install	Environment	Required file
Next.js	`npm install @aiolaapp/logger`	`NEXT_PUBLIC_AIOLA_KEY=your_api_key`	`app/layout.tsx` plus `app/aiola-client.tsx`
React	`npm install @aiolaapp/logger`	`VITE_AIOLA_KEY=your_api_key`	`src/main.tsx`
Node.js	`npm install @aiolaapp/logger`	`AIOLA_KEY=your_api_key`	`src/index.ts`
Edge Function	No install	`AIOLA_KEY=your_api_key` in edge secrets	`index.ts`
Python	`pip install aiola`	`AIOLA_KEY=your_api_key`	`main.py`

Current initialization snippets

Next.js
React
Node.js
Edge Function
Python

The generator names app/layout.tsx, but that file is a Server Component by default. Put initialization in a Client Component so browser global handlers, navigation breadcrumbs, and client request capture are installed, then render it from the layout.

// app/aiola-client.tsx
'use client'

import { Aiola } from '@aiolaapp/logger'
Aiola.init({ apiKey: process.env.NEXT_PUBLIC_AIOLA_KEY!, environment: 'production' })

export function AiolaClient() { return null }

// app/layout.tsx
import { AiolaClient } from './aiola-client'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return <html><body><AiolaClient />{children}</body></html>
}

import { Aiola } from '@aiolaapp/logger'
Aiola.init({ apiKey: import.meta.env.VITE_AIOLA_KEY, environment: 'production' })

import { Aiola } from '@aiolaapp/logger/node'
Aiola.init({ apiKey: process.env.AIOLA_KEY!, environment: 'production' })

import { Aiola } from 'npm:@aiolaapp/logger'
Aiola.init({ apiKey: Deno.env.get('AIOLA_KEY')!, environment: 'production' })
Deno.serve(Aiola.wrapDenoServe(async (req) => new Response("ok")))

import os
import aiola
aiola.init(api_key=os.environ["AIOLA_KEY"], environment="production")

Automatic versus manual capture

Aiola.captureException(new Error('Something broke'))
Aiola.captureMessage('Payment failed', 'error')

aiola.capture_exception(error)
aiola.capture_message("Payment failed", level="error")

User context

Aiola.setUser({ id: user.id, email: user.email, username: user.name })
Aiola.setUser(null)

aiola.set_user({"id": user.id, "email": user.email, "username": user.name})
aiola.set_user(None)

Runtime wrappers

Next.js provides Aiola.wrapRouteHandler, Node provides Aiola.wrap, Python provides @aiola.wrap, and Edge uses Aiola.wrapDenoServe. Each captures and rethrows/flushes according to its runtime.

Raw HTTP/no-SDK integration

curl -X POST https://aiola.app/api/app-logs-ingest \
  -H "x-aiola-key: $AIOLA_KEY" \
  -H "content-type: application/json" \
  -d '{"message":"Checkout failed","level":"error","exception":{"type":"PaymentError","value":"Card declined","stacktrace":{"frames":[{"filename":"CheckoutView.swift","function":"submitOrder","lineno":128,"in_app":true}]}},"platform":"ios","environment":"production","release":"1.4.2","tags":{"app":"mobile","screen":"checkout"},"user":{"id":"u_123"}}'

Endpoint/auth/payload schema

Use POST https://aiola.app/api/app-logs-ingest; x-aiola-key is preferred and Bearer is accepted. message or exception is required. See the complete payload.

Limits and redaction

Confirm truncation, rate limits, and stripped headers in App Logs. Request text longer than 512,000 characters is rejected with 413.

Environment and release naming

Use stable environment names such as production, staging, and development. Send the exact deployed release identifier consistently in release.

Source-map upload/release matching

Upload maps in Settings → App Logs → Source Maps under the exact event release. Trigger a minified error and confirm its frame shows original source.

Setup Health and SDK upgrades

Run Setup Health. Resolve logger-outdated and logger-legacy-endpoint findings; use Update logger when offered for @aiolaapp/logger.

Verification and troubleshooting

Send a test failure

Capture an exception with environment, release, and user context.

Verify the workspace

Open App Logs, inspect stack, breadcrumbs, request/user contexts, and repeat the event to confirm grouping.

Verify Central

Open Central → App Logs and confirm the issue retains its project name.

Check failures

401 means the key is missing/invalid; 403 means logs are disabled; 400 means invalid JSON or no message/exception; 429 means the project rate limit.

Getting Started

Workspaces & Central

Chat & AI

Project Operations

Monitoring

Connections

Settings

Setup Guides

Reference

Set Up App Logs

Generate the project key

Framework/package/environment matrix

Current initialization snippets

Automatic versus manual capture

User context

Runtime wrappers

Raw HTTP/no-SDK integration

Endpoint/auth/payload schema

Limits and redaction

Environment and release naming

Source-map upload/release matching

Setup Health and SDK upgrades

Verification and troubleshooting

​Generate the project key

​Framework/package/environment matrix

​Current initialization snippets

​Automatic versus manual capture

​User context

​Runtime wrappers

​Raw HTTP/no-SDK integration

​Endpoint/auth/payload schema

​Limits and redaction

​Environment and release naming

​Source-map upload/release matching

​Setup Health and SDK upgrades

​Verification and troubleshooting

Generate the project key

Framework/package/environment matrix

Current initialization snippets

Automatic versus manual capture

User context

Runtime wrappers

Raw HTTP/no-SDK integration

Endpoint/auth/payload schema

Limits and redaction

Environment and release naming

Source-map upload/release matching

Setup Health and SDK upgrades

Verification and troubleshooting