Save this content to: .cursor/rules/public_api.mdc

# Public API

## Facade (browser parity)

```php
Talaria::init([...]);
Talaria::logger('name' | ['name' => …, 'tags' => [...], 'minLevel' => 'info']);
Talaria::withTags([...]);
Talaria::debug/info/warning/warn/error/fatal($message, $context);
Talaria::log($level, $message, $context);
Talaria::captureException($e, $context);
Talaria::captureMessage($message, $level, $context);
Talaria::addBreadcrumb([...]);
Talaria::startTransaction($name, $kind?, $attributes?);
Talaria::startSpan($name, $kind?, $attributes?);
Talaria::setRecordQuerySpans($record);
Talaria::withoutQuerySpans($callback);
Talaria::getTraceparent();
Talaria::analytics();
Talaria::resetRequestState();
Talaria::getMinLevel(); Talaria::setMinLevel($level); Talaria::isLevelEnabled($level);
Talaria::isEnforceDefaultLevel(); Talaria::setEnforceDefaultLevel($bool);
Talaria::flush();
Talaria::close();
```

Also expose `Talaria\TalariaClient` for DI and `Talaria\Logger` (PSR-3 + scoped helpers).
`Talaria\Client` remains a deprecated class alias of `TalariaClient`.

`Talaria\Logger::log()` must keep **untyped** `$level` / `$message` parameters so the class
implements psr/log 1.x, 2.x, and 3.x. Do not add `\Stringable|string` on `$message` —
that fatals against older `LoggerInterface::log($level, $message, …)`. Document PSR-3 in
PHPDoc; cast with `(string) $message` at runtime.

## Init options

- `apiKey` (`tal_sk_` on servers). Optional `url` overrides the key-derived ingest host. The API key decides the environment; do not pass or send `environment`. A missing or bad key, or a bad option, never throws: the client is disabled (`isEnabled()` false) and logs one warning (`onWarning` callable, else `error_log`).
- Optional: `release`, `sampleRate`, `enableTracing` (default `false`), `tracesSampleRate` (default `0.1` when tracing is on), `enableAnalytics` (default `true` on core; Silverstripe YAML defaults off), `minLevel` (default `debug` — default/root level), `enforceDefaultLevel` (default `false`), `loggers` (named presets), `beforeSend`, `maxBatchSize`, `flushIntervalMs`, `defaultIntegrations`, `userId`, `anonymousId`, `sessionId`, `tags`, `httpTimeoutSeconds`
- `TalariaClient::addProcessor()` for per-request tag/extra enrichment (prefer over `setTags` on long-lived singletons)
- Tag merge order (later wins): automatic `RuntimeContext` tags → init/global → processors → logger scope → per-call context

## Capture rules

- Exceptions default `level: error`; messages default `info`
- Derive `eventType` from level
- Context bag: `tags`, `extra`, `userId`, `title`, optional `mechanism` (`type` / `handled` / `synthetic`)
- `captureException` builds first-class `exception.values[]` (frames oldest→newest, `functionName`); `extra` is app metadata only
- Gates: effective level → `sampleRate` → `beforeSend`; filtered captures are quiet no-ops
- Scoped loggers inherit client `minLevel` as default; assigned `minLevel` may raise or lower unless `enforceDefaultLevel` is true
- Direct client captures always respect client `minLevel`; logger path applies client floor only when enforcing
- Capture enqueues only — network I/O happens on queue drain
- See `packages/talaria/docs/logging-levels.md` for hierarchy, enforcement, and migration