@owlmetry/cli 0.1.0

package/dist/skills/owlmetry-cli/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: owlmetry-cli
+version: 0.1.0
+description: >-
+  Install the OwlMetry CLI, sign up, and manage projects, apps, metrics,
+  funnels, and events. Use when adding OwlMetry to a project, querying
+  analytics, or when another OwlMetry skill needs CLI setup as a prerequisite.
+allowed-tools: Bash
+---
+
+## What is OwlMetry?
+
+OwlMetry is a self-hosted analytics platform for mobile and backend apps. It captures events, structured metrics, and funnel conversions from client SDKs (Swift, Node.js), stores them in a partitioned PostgreSQL database, and exposes query and management APIs.
+
+The **CLI** is the management and query tool — it does not ingest events. You use it to create projects and apps, define metrics and funnels, query event data, and view analytics. SDKs handle event ingestion using client keys (`owl_client_...`). The CLI uses agent keys (`owl_agent_...`) for reading data and managing resources.
+
+## Version Check
+
+Run these checks silently. Only inform the user if updates are available.
+
+1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-cli/SKILL.md | head -5` — compare the `version:` field to `0.1.0`. If newer, ask the user if they want to update the local skill file.
+2. **CLI version** (if installed): compare `owlmetry --version` to `npm view @owlmetry/cli version 2>/dev/null`. If a newer version exists, offer `npm install -g @owlmetry/cli@latest`.
+
+If everything is current or the remote is unreachable, continue silently.
+
+## Setup
+
+**Prerequisites:** Node.js 20+
+
+**Install:**
+```bash
+npm install -g @owlmetry/cli
+```
+
+**Sign up / log in:**
+```bash
+owlmetry auth send-code --email <user-email>
+```
+Ask the user for the 6-digit verification code that arrives by email, then:
+```bash
+owlmetry auth verify --email <user-email> --code <code> --format json
+```
+
+- New users are auto-provisioned with a team, project, and backend app.
+- The response includes an agent API key (`owl_agent_...`), team ID, project ID, and app details.
+- Config is saved to `~/.owlmetry/config.json`.
+- Default endpoint: `https://api.owlmetry.com`
+
+If the user already has a config file (`~/.owlmetry/config.json`), they're already set up — skip auth.
+
+**Manual setup** (if the user already has an API key):
+```bash
+owlmetry setup --endpoint <url> --api-key <key>
+```
+
+## Resource Hierarchy
+
+OwlMetry organises resources in a `Team → Project → Apps` hierarchy:
+
+- **Team** — the top-level account. Users belong to one or more teams. All resources (projects, apps, keys) are team-scoped.
+- **Project** — groups related apps under one product (e.g., "MyApp" project). Metrics and funnels are defined at the project level so they span all apps in the project.
+- **App** — represents a single deployable artifact. Each app has a `platform` (`apple`, `android`, `web`, `backend`) and, for non-backend platforms, a `bundle_id`. Creating an app auto-generates a `client_key` for SDK use.
+
+Projects group apps cross-platform: an iOS app and its backend API can share the same project, enabling unified funnel and metric analysis across both.
+
+## Resource Management
+
+### Projects
+
+Projects group apps by product and scope metrics and funnels. Create one project per product (e.g., "Acme" with iOS + backend apps under it).
+
+```bash
+owlmetry projects --format json                                        # List all
+owlmetry projects view <id> --format json                              # View details + apps
+owlmetry projects create --team-id <id> --name <name> --slug <slug> --format json
+owlmetry projects update <id> --name <new-name> --format json
+```
+
+### Apps
+
+An app represents a single deployable target. The `client_key` returned on creation is what SDKs use for event ingestion. The `bundle_id` is **immutable after creation** — to change it, delete and recreate the app. Backend apps have no bundle_id.
+
+```bash
+owlmetry apps --format json                                            # List all
+owlmetry apps --project <id> --format json                             # List by project
+owlmetry apps view <id> --format json                                  # View details
+owlmetry apps create --project-id <id> --name <name> --platform <platform> [--bundle-id <id>] --format json
+owlmetry apps update <id> --name <new-name> --format json
+```
+
+- **Platforms:** `apple`, `android`, `web`, `backend`
+- `--bundle-id` is required for apple/android/web, omitted for backend
+- The create response includes `client_key` — this is the SDK API key
+
+### Metric Definitions
+
+Metrics are project-scoped definitions that tell OwlMetry what structured data to expect from SDKs. There are two kinds:
+
+- **Lifecycle metrics** (`--lifecycle`): track operations with a start → complete/fail/cancel flow. Use for things with duration — API calls, uploads, database queries. The SDK auto-tracks `duration_ms`.
+- **Single-shot metrics** (no `--lifecycle`): record a point-in-time measurement. Use for snapshots — cache hit rates, queue depth, cold start time.
+
+The metric definition must exist on the server **before** the SDK emits events for that slug, otherwise the server will reject the events.
+
+```bash
+owlmetry metrics --project <id> --format json                          # List all
+owlmetry metrics view <slug> --project <id> --format json              # View details
+owlmetry metrics create --project <id> --name <name> --slug <slug> [--lifecycle] [--description <desc>] --format json
+owlmetry metrics update <slug> --project <id> [--name <name>] [--status active|paused] --format json
+owlmetry metrics delete <slug> --project <id>
+```
+
+Slugs: lowercase letters, numbers, hyphens only (`/^[a-z0-9-]+$/`).
+
+### Funnel Definitions
+
+Funnels measure how users progress through a multi-step flow and where they drop off. Each funnel has an ordered list of steps, and each step has an `event_filter` that matches incoming events (by `message` and/or `screen_name`).
+
+SDKs emit funnel events via `track("step-name")`, which generates events with message `"track:step-name"`. The `event_filter` in each step must match these messages exactly.
+
+Funnels support two analysis modes:
+- **Closed mode** (default): sequential — a user must complete steps in order (step 2 only counts if step 1 was completed first). Use for linear flows like onboarding or checkout.
+- **Open mode** (`--open` on query): independent — each step is evaluated separately. Use when steps can happen in any order.
+
+Maximum 20 steps per funnel.
+
+```bash
+owlmetry funnels --project <id> --format json                          # List all
+owlmetry funnels view <slug> --project <id> --format json              # View details
+owlmetry funnels create --project <id> --name <name> --slug <slug> --steps '<json>' [--description <desc>] --format json
+owlmetry funnels update <slug> --project <id> [--name <name>] [--steps '<json>'] --format json
+owlmetry funnels delete <slug> --project <id>
+```
+
+Steps JSON format: `[{"name":"Step Name","event_filter":{"message":"track:step-name"}}]`
+
+## Querying
+
+### Events
+
+Events are the raw log records emitted by SDKs — every `Owl.info()`, `Owl.error()`, `Owl.track()`, etc. Query events when debugging specific issues, investigating user behavior, or reviewing what happened in a time window.
+
+```bash
+owlmetry events [--project <id>] [--app <id>] [--since <time>] [--until <time>] [--level info|debug|warn|error] [--user <id>] [--session <id>] [--screen <name>] [--limit <n>] [--cursor <cursor>] [--data-mode production|development|all] --format json
+owlmetry events view <id> --format json
+```
+
+Defaults to last 24 hours if no `--since`/`--until` specified.
+
+### Investigate (contextual events)
+
+Investigate works like a flight recorder — given a single event ID, it returns the surrounding events from the same app within a time window. Use this when you have a specific error or anomaly and want to see what happened immediately before and after it.
+
+```bash
+owlmetry investigate <eventId> [--window <minutes>] --format json
+```
+
+Shows events surrounding a target event. Default window: 5 minutes.
+
+### Users
+
+```bash
+owlmetry users <app-id> [--anonymous] [--real] [--search <query>] [--limit <n>] --format json
+```
+
+`--anonymous` and `--real` are mutually exclusive.
+
+### Metric Events & Aggregation
+
+There are two ways to look at metric data:
+
+- **`metrics events`** — raw metric event records, useful for debugging individual operations (e.g., "why did this specific upload fail?"). Shows each start/complete/fail/cancel/record event individually.
+- **`metrics query`** — aggregated statistics (count, avg/p50/p95/p99 duration, error rate), useful for spotting trends and regressions. Supports grouping by app, version, environment, device, or time bucket.
+
+```bash
+owlmetry metrics events <slug> --project <id> [--phase start|complete|fail|cancel|record] [--tracking-id <id>] [--user <id>] [--since <time>] [--until <time>] [--environment <env>] [--data-mode <mode>] --format json
+owlmetry metrics query <slug> --project <id> [--since <date>] [--until <date>] [--app <id>] [--app-version <v>] [--environment <env>] [--user <id>] [--group-by app_id|app_version|device_model|os_version|environment|time:hour|time:day|time:week] [--data-mode <mode>] --format json
+```
+
+### Funnel Analytics
+
+Funnel queries return conversion rates and drop-off between steps. The output shows how many users entered each step and what percentage continued to the next. Use `--group-by` to segment results and compare conversion across environments, app versions, or A/B experiment variants.
+
+```bash
+owlmetry funnels query <slug> --project <id> [--since <date>] [--until <date>] [--open] [--app-version <v>] [--environment <env>] [--experiment <name:variant>] [--group-by environment|app_version|experiment:<name>] [--data-mode <mode>] --format json
+```
+
+`--open` = open funnel mode (steps evaluated independently, not sequentially).
+
+### Audit Logs
+
+Audit logs record who performed what action on which resource — creating an app, revoking an API key, changing a team member's role, etc. Query them when investigating configuration changes or tracking administrative activity. Requires `audit_logs:read` permission on the agent key (included in default agent key permissions).
+
+```bash
+owlmetry audit-log list --team <id> [--resource-type <type>] [--resource-id <id>] [--actor <id>] [--action create|update|delete] [--since <time>] [--until <time>] [--limit <n>] --format json
+```
+
+## Key Notes
+
+- Always use `--format json` when parsing output programmatically.
+- **Global flags** available on all commands: `--endpoint <url>`, `--api-key <key>`, `--format <format>`
+- **Agent keys** (`owl_agent_...`) are for CLI queries. **Client keys** (`owl_client_...`) are for SDK event ingestion.
+- **Time format:** relative (`1h`, `30m`, `7d`) or ISO 8601 (`2026-03-20T00:00:00Z`). Relative times go backwards from now — `1h` means "the last hour", `7d` means "the last 7 days".
+- **Data mode:** `production` (default), `debug`, or `all` — filters events by their debug flag. SDKs auto-detect debug mode (DEBUG builds on iOS, `NODE_ENV !== "production"` on Node). Use `debug` mode during development to see test events; use `production` (the default) for real analytics.
+- Ask the user for their email address; the verification code arrives by email.
+
+## Typical Workflow
+
+A typical end-to-end flow for adding OwlMetry to a new project:
+
+1. **Sign up**: `owlmetry auth send-code` → verify code → auto-provisioned with team, project, and backend app
+2. **Create apps**: `owlmetry apps create --platform apple --bundle-id com.example.myapp` (and/or android, web, backend)
+3. **Note the client key**: from the app creation response — pass this to the SDK
+4. **Instrument the app**: Add the Swift or Node SDK, configure with the endpoint and client key, add logging calls
+5. **Define metrics**: `owlmetry metrics create --slug photo-upload --lifecycle` for operations you want to track with duration
+6. **Define funnels**: `owlmetry funnels create --slug onboarding --steps '[...]'` for multi-step flows you want to measure conversion on
+7. **Query data**: Use `owlmetry events`, `owlmetry metrics query`, and `owlmetry funnels query` to analyze behavior

package/dist/skills/owlmetry-node/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: owlmetry-node
+version: 0.1.0
+description: >-
+  Integrate the OwlMetry Node.js SDK into a backend service for server-side
+  analytics, event tracking, metrics, funnels, and A/B experiments. Use when
+  instrumenting a Node.js, Express, Fastify, or serverless project with OwlMetry.
+allowed-tools: Read, Bash, Grep, Glob
+---
+
+## What is OwlMetry?
+
+OwlMetry is a self-hosted analytics platform. The Node.js SDK captures events from backend services — API servers, job workers, serverless functions — and delivers them to the OwlMetry server. It buffers events in memory and flushes them in batches to avoid blocking your application's request path.
+
+The SDK has zero runtime dependencies. All calls are non-blocking — events are buffered internally and sent in the background. A single `Owl.configure()` call initialises everything including a background flush timer.
+
+## Version Check
+
+Run these checks silently. Only inform the user if updates are available.
+
+1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-node/SKILL.md | head -5` — compare the `version:` field to `0.1.0`. If newer, ask the user if they want to update.
+2. **SDK version**: `npm ls @owlmetry/node --json 2>/dev/null` for current version, `npm view @owlmetry/node version 2>/dev/null` for latest. If newer, offer `npm install @owlmetry/node@latest`.
+
+## Prerequisite
+
+You need an OwlMetry endpoint URL and a `client_key` (starts with `owl_client_...`) for an app with `platform: backend`.
+
+If the user doesn't have these yet, invoke `/owlmetry-cli` first to:
+1. Sign up or log in
+2. Create a project (if needed)
+3. Create an app with `--platform backend` (no `--bundle-id` needed)
+4. Note the `client_key` from the app creation response
+
+## Install
+
+```bash
+npm install @owlmetry/node
+```
+
+Zero runtime dependencies. Node.js 20+. ESM only.
+
+## Configure
+
+```typescript
+import { Owl } from '@owlmetry/node';
+
+Owl.configure({
+  endpoint: 'https://ingest.owlmetry.com',
+  apiKey: 'owl_client_...',
+  serviceName: 'my-api',          // optional, default: "unknown"
+  appVersion: '1.2.0',            // optional
+  isDev: false,                   // optional, default: process.env.NODE_ENV !== "production"
+  flushIntervalMs: 5000,          // optional, default: 5000
+  flushThreshold: 20,             // optional, default: 20
+  maxBufferSize: 10000,           // optional, default: 10000
+});
+```
+
+- `apiKey` must start with `owl_client_`
+- `isDev` defaults to `true` when `NODE_ENV !== "production"`
+- Generates a fresh `sessionId` (UUID) on each `configure()` call
+- Registers a `beforeExit` handler to auto-flush on graceful shutdown
+
+## Buffering and Delivery
+
+The SDK buffers events in memory and sends them to the server in batches. Understanding how buffering works helps you avoid lost events:
+
+- **Buffer size** (`maxBufferSize: 10000`): maximum events held in memory. If the buffer fills up, new events are dropped. Increase this if your service produces bursts of events.
+- **Flush interval** (`flushIntervalMs: 5000`): a background timer fires every 5 seconds and sends all buffered events. The timer uses `.unref()` so it won't keep the process alive.
+- **Flush threshold** (`flushThreshold: 20`): if the buffer reaches this many events before the timer fires, an immediate flush is triggered.
+- **HTTP timeout**: each flush request has a 10-second timeout to prevent hanging on slow or unreachable servers. Failed flushes are silently dropped (events are not retried).
+- **Graceful exit**: a `beforeExit` handler auto-flushes remaining events on normal process termination. For SIGTERM/SIGINT, you must call `Owl.shutdown()` explicitly (see Graceful Shutdown).
+
+The key implication: if your process crashes or is force-killed, any events still in the buffer are lost. For critical routes, use `wrapHandler()` to flush after each request.
+
+## Log Events
+
+Events are the core data unit. Use the four log levels to capture different kinds of backend activity:
+
+- **`info`** — normal operations: server started, request handled, job completed, user action processed.
+- **`debug`** — verbose detail for development: cache lookups, query plans, config loading, intermediate state.
+- **`warn`** — recoverable problems: slow queries, rate limits approaching, fallback paths, deprecated API usage.
+- **`error`** — failures: database connection errors, external API failures, unhandled rejections, missing resources.
+
+Choose **message strings** that are specific and searchable. Prefer `"Payment processing failed"` over `"error occurred"`. Use attributes for structured data you'll filter on later.
+
+```typescript
+Owl.info('Server started', { port: 4000 });
+Owl.debug('Cache miss', { key: 'user:123' });
+Owl.warn('Slow query', { duration_ms: 2500, table: 'events' });
+Owl.error('Database connection failed', { host: 'db.example.com' });
+```
+
+All methods: `Owl.info/debug/warn/error(message: string, attrs?: Record<string, unknown>)`.
+
+Source module (file:line) is auto-captured from the call stack.
+
+**Backend-specific examples:**
+```typescript
+Owl.info('Request handled', { method: 'POST', path: '/api/orders', status: 201 });
+Owl.info('Background job completed', { job: 'send-emails', processed: 150 });
+Owl.warn('Rate limit approaching', { current: 95, limit: 100, client_id: 'abc' });
+Owl.error('External API timeout', { service: 'stripe', endpoint: '/charges', timeout_ms: 10000 });
+```
+
+## Per-Request User Scoping
+
+In a multi-user backend, many requests are processed concurrently. Without scoping, you'd need to pass a user ID to every log call. `Owl.withUser()` creates a scoped instance that automatically tags all events with the user ID — create one per request in your auth middleware.
+
+Use scoped instances whenever you know who the user is. Use the global `Owl` for system-level events (startup, shutdown, background jobs without a user context).
+
+```typescript
+const owl = Owl.withUser('user_42');
+owl.info('User logged in');
+owl.warn('Rate limit approaching', { requests: 95 });
+owl.error('Payment failed', { reason: 'insufficient_funds' });
+```
+
+`ScopedOwl` has the same logging methods as `Owl` (`info`, `debug`, `warn`, `error`, `track`, `startOperation`, `recordMetric`).
+
+## Funnel Tracking
+
+Backend funnels track server-side conversion flows — signup pipelines, payment processing, onboarding sequences, data processing stages. Unlike client-side funnels where users interact with UI, backend funnels typically track state transitions in response to API calls or background jobs.
+
+**User ID is critical for backend funnels.** Funnel analytics group by user to calculate conversion — without a user ID, events can't be attributed. Always use a scoped instance (`Owl.withUser()`) or ensure user identity is set.
+
+```typescript
+Owl.track('signup-started');
+Owl.track('email-verified', { method: 'link' });
+Owl.track('profile-completed');
+
+// With user scoping:
+const owl = Owl.withUser(userId);
+owl.track('checkout-completed', { item_count: '3' });
+```
+
+Each `track()` call emits an info-level event with message `"track:<stepName>"`. Define matching funnels via `/owlmetry-cli`.
+
+**Note:** `track()` attributes must be `Record<string, string>` (string values only).
+
+## Structured Metrics
+
+Use structured metrics when you want aggregated performance data (averages, percentiles, error rates) rather than individual event logs. Metrics give you trend data and alerting signals; events give you individual records for debugging.
+
+**Decision: lifecycle vs single-shot:**
+- **Lifecycle** — when measuring something with a duration (start → end). Backend examples: HTTP request handling, database queries, external API calls, file processing, queue job execution.
+- **Single-shot** — when recording a point-in-time measurement. Backend examples: queue depth, cache hit rate, active connections, deployment markers.
+
+The metric definition must exist on the server **before** the SDK emits events for that slug. Create it via CLI first.
+
+### Lifecycle operations (start -> complete/fail/cancel)
+
+```typescript
+const op = Owl.startOperation('database-query', { table: 'users' });
+try {
+  const result = await db.query('SELECT * FROM users');
+  op.complete({ rows: result.length });
+} catch (err) {
+  op.fail(String(err), { table: 'users' });
+}
+
+// Or cancel:
+op.cancel({ reason: 'timeout' });
+```
+
+`duration_ms` and `tracking_id` (UUID) are auto-added. Create the metric definition first:
+```bash
+owlmetry metrics create --project <id> --name "Database Query" --slug database-query --lifecycle --format json
+```
+
+### Single-shot measurements
+
+```typescript
+Owl.recordMetric('cache-hit-rate', { rate: '0.95', cache: 'redis' });
+```
+
+Works with scoped instances too: `owl.startOperation(...)`, `owl.recordMetric(...)`.
+
+**Slug rules:** lowercase letters, numbers, hyphens only. Invalid slugs are auto-corrected with a warning.
+
+## A/B Experiments
+
+Backend experiments let you vary server-side behavior (algorithm versions, feature flags, response formats) and measure the impact through metrics and funnels.
+
+How it works end-to-end:
+1. **Assign a variant**: `getVariant("pricing-algo", ["control", "v2"])` randomly picks on first call.
+2. **Branch your logic**: use the returned variant string to execute different code paths.
+3. **Events are auto-tagged**: all subsequent events include the experiment assignment.
+4. **Analyse**: query metrics or funnels segmented by variant to compare outcomes.
+
+Assignments persist to `~/.owlmetry/experiments.json` on disk, so they survive restarts. **Serverless caveat**: in serverless environments (Lambda, Cloud Functions), each cold start reads from the file — but if the filesystem is ephemeral, assignments won't persist across invocations. Use `setExperiment()` with a server-side assignment for stable bucketing in serverless.
+
+```typescript
+// Random assignment on first call, persisted to ~/.owlmetry/experiments.json
+const variant = Owl.getVariant('checkout-redesign', ['control', 'variant-a', 'variant-b']);
+
+// Force-set (e.g., from server config)
+Owl.setExperiment('checkout-redesign', 'variant-a');
+
+// Clear all
+Owl.clearExperiments();
+```
+
+All events automatically include an `experiments` field with current assignments.
+
+## Serverless Support
+
+Serverless environments (AWS Lambda, Vercel Functions, Cloud Functions) freeze the runtime after each invocation. Events still in the buffer are lost when the runtime freezes — the flush timer and `beforeExit` handler may never fire.
+
+`wrapHandler()` solves this by calling `Owl.flush()` in a `finally` block after every invocation, guaranteeing delivery before the runtime freezes.
+
+**When to use `wrapHandler()`:**
+- **Serverless functions**: always wrap — this is the only reliable way to flush.
+- **Long-running servers, critical routes**: wrap routes where losing events is unacceptable (payment processing, user signup). The 5-second flush timer handles the rest.
+- **Long-running servers, general routes**: not needed — the background timer and shutdown handler cover normal operation.
+
+```typescript
+// AWS Lambda
+export const handler = Owl.wrapHandler(async (event, context) => {
+  Owl.info('Lambda invoked', { functionName: context.functionName });
+  // ... handle request ...
+  return { statusCode: 200, body: JSON.stringify({ ok: true }) };
+});
+
+// Express route
+app.post('/api/checkout', Owl.wrapHandler(async (req, res) => {
+  const owl = Owl.withUser(req.user?.id);
+  const op = owl.startOperation('checkout');
+  // ... process ...
+  op.complete();
+  res.json({ ok: true });
+}));
+```
+
+`wrapHandler` calls `Owl.flush()` in a `finally` block, ensuring events are sent even if the handler throws.
+
+## Graceful Shutdown
+
+Without explicit shutdown, events buffered since the last flush (up to 5 seconds worth) are lost when the process exits via SIGTERM or SIGINT. The `beforeExit` handler only covers graceful exits (no pending work, no signal termination).
+
+Always add a shutdown handler for production services:
+
+```typescript
+process.on('SIGTERM', async () => {
+  await Owl.shutdown();
+  process.exit(0);
+});
+```
+
+- `shutdown()` stops the flush timer, flushes remaining events, and clears state.
+- The `beforeExit` handler auto-flushes on graceful process exit even without explicit shutdown.
+
+## Integration Patterns
+
+These patterns show how to wire OwlMetry into common Node.js frameworks. The key ideas:
+- **Create a scoped logger in auth middleware** so all route handlers get user-attributed events automatically.
+- **Use `wrapHandler()` on critical routes** where losing events is unacceptable.
+- **Call `shutdown()` in the framework's close hook** to flush on process termination.
+
+### Express middleware
+
+```typescript
+import express from 'express';
+import { Owl } from '@owlmetry/node';
+
+const app = express();
+
+// Scoped logging middleware
+app.use((req, res, next) => {
+  req.owl = req.user?.id ? Owl.withUser(req.user.id) : Owl;
+  next();
+});
+
+app.post('/api/order', Owl.wrapHandler(async (req, res) => {
+  const op = req.owl.startOperation('create-order', { items: req.body.items?.length });
+  try {
+    const order = await createOrder(req.body);
+    op.complete({ order_id: order.id });
+    res.json(order);
+  } catch (err) {
+    op.fail(String(err));
+    res.status(500).json({ error: 'Order failed' });
+  }
+}));
+
+process.on('SIGTERM', async () => {
+  await Owl.shutdown();
+  process.exit(0);
+});
+```
+
+### Fastify hooks
+
+```typescript
+import Fastify from 'fastify';
+import { Owl } from '@owlmetry/node';
+
+const fastify = Fastify();
+
+fastify.addHook('onRequest', (request, reply, done) => {
+  request.owl = request.user?.id ? Owl.withUser(request.user.id) : Owl;
+  done();
+});
+
+fastify.addHook('onClose', async () => {
+  await Owl.shutdown();
+});
+
+fastify.post('/api/process', async (request, reply) => {
+  request.owl.info('Processing request', { path: request.url });
+  // ... handle request ...
+  await Owl.flush();
+  return { ok: true };
+});
+```