# Logs

What happened, told to whoever runs the app: audit, security, incident, job and debug intents, recorded with log().

## Why

A `console.error` says nothing about who needs to know. Is it an incident someone should look at, a security signal, a record of who did what, or leftover debugging? Without that, everything is printed at the same volume, alerts are either missing or noisy, and secrets end up in logs. Logs apply everywhere: servers, browser code, background jobs and scripts, so this profile stands on its own.

Before

```tsx
} catch (error) {
  console.error('[ArticlePage] Failed to load related articles:', error);
}
```

After

```tsx
} catch (error) {
  log('incident.degraded', 'Article rendered without related articles', { slug, cause: error });
}
```

## Set it up

```bash
npx prongs add logs
```

Adds the logs profile and its starter intents, and copies `log()` (this page) into `components/prongs/log.ts`. Point its `write` function at your logger or error tracker; it receives the intent, the level and whether to alert.

## The types of log

Pick the type by who needs to know, then the event within it. Each domain has its own page.

| Intent | Use it for | Resolves to |
|---|---|---|
| [`audit.created`](https://www.prongs.dev/docs/intents/audit/created.md) | Someone created something that matters later: an account, a page, an API key | `info level` |
| [`audit.changed`](https://www.prongs.dev/docs/intents/audit/changed.md) | Someone changed something that matters: settings, a role, a published page | `info level` |
| [`audit.deleted`](https://www.prongs.dev/docs/intents/audit/deleted.md) | Someone deleted something: a page, an account, content | `info level` |
| [`audit.signedin`](https://www.prongs.dev/docs/intents/audit/signedin.md) | Someone signed in, the ordinary way | `info level` |
| [`audit.signedout`](https://www.prongs.dev/docs/intents/audit/signedout.md) | Someone signed out | `info level` |

| Intent | Use it for | Resolves to |
|---|---|---|
| [`security.signin`](https://www.prongs.dev/docs/intents/security/signin.md) | A sign-in failed, or succeeded from somewhere unusual | `warn level` |
| [`security.token`](https://www.prongs.dev/docs/intents/security/token.md) | A bad or expired token, secret or signature was presented | `warn level` |
| [`security.limited`](https://www.prongs.dev/docs/intents/security/limited.md) | A caller hit a rate limit | `warn level` |

| Intent | Use it for | Resolves to |
|---|---|---|
| [`incident.failed`](https://www.prongs.dev/docs/intents/incident/failed.md) | Something broke and someone should look: a request, a job, a dependency | `error level · alerts` |
| [`incident.degraded`](https://www.prongs.dev/docs/intents/incident/degraded.md) | It worked, but worse than it should: a fallback, a retry, a slow dependency | `warn level` |

| Intent | Use it for | Resolves to |
|---|---|---|
| [`job.started`](https://www.prongs.dev/docs/intents/job/started.md) | A background job or script began: a sync, a backup, a migration | `info level` |
| [`job.finished`](https://www.prongs.dev/docs/intents/job/finished.md) | A job ended, with what it did: counts, duration | `info level` |

| Intent | Use it for | Resolves to |
|---|---|---|
| [`debug.trace`](https://www.prongs.dev/docs/intents/debug/trace.md) | Detail for working on the code | `debug level · not in production` |

## Using log()

```ts
import { log } from '@/components/prongs/log';

log('audit.deleted', 'Page deleted', { pageId, by: user.id });
log('security.token', 'Preview secret did not match', { ip });
log('incident.degraded', 'Search fell back to the cached index', { tookMs });
log('job.finished', 'Redirects synced', { count: entries.length });
```

`log(intent, message, data?)` writes one structured entry. Levels live in ref-only [`level.*`](https://www.prongs.dev/docs/intents/logs.md#level) intents; [`level.debug`](https://www.prongs.dev/docs/intents/logs.md#level-debug) is dropped in production. Errors in `data` become their name, message and stack, and anything under a key that looks like a secret is replaced.