autotel 2.23.0 → 2.24.0

package/skills/autotel-frameworks/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: autotel-frameworks
+description: >
+  Hono, Fastify, TanStack Start, Cloudflare Workers. Middleware and init; getRequestLogger() in handlers. Load when adding Autotel to a web framework.
+type: framework
+library: autotel
+library_version: '2.23.0'
+requires:
+  - autotel-instrumentation
+sources:
+  - jagreehal/autotel:packages/autotel-hono/src/index.ts
+  - jagreehal/autotel:docs/AGENT-GUIDE.md
+  - jagreehal/autotel:AGENTS.md
+---
+
+# Autotel — Framework Integration
+
+This skill builds on autotel-instrumentation. Read it first for init() and span creation.
+
+Use framework-specific middleware or wrappers to create a span per request; then call `getRequestLogger()` inside handlers. Each framework package (autotel-hono, autotel-tanstack, autotel-cloudflare) provides the glue.
+
+## Setup
+
+### Hono
+
+```typescript
+import { Hono } from 'hono';
+import { init, getRequestLogger } from 'autotel';
+import { otel } from 'autotel-hono';
+
+init({ service: 'my-api' });
+
+const app = new Hono();
+app.use('*', otel({ serviceName: 'my-api' }));
+
+app.post('/api/checkout', async (c) => {
+  const log = getRequestLogger();
+  log.set({ route: 'checkout' });
+  const body = await c.req.json();
+  log.set({ cart: { items: body.items?.length } });
+  log.emitNow();
+  return c.json({ ok: true });
+});
+```
+
+### Fastify
+
+Use middleware or a wrapper that creates a span per request (see apps/example-fastify). Inside the route, wrap with `trace()` or ensure a span is active, then `getRequestLogger(ctx)` or `getRequestLogger()`.
+
+### TanStack Start
+
+See packages/autotel-tanstack and apps/example-tanstack-start: middleware and env config. Use `getRequestLogger()` inside server handlers when a span is active.
+
+### Cloudflare Workers
+
+See packages/autotel-cloudflare: init at top level, wrap the fetch handler so each request gets a span. Use `getRequestLogger()` or trace context inside the handler.
+
+## Core Patterns
+
+**Register middleware before routes:** Middleware creates the span; getRequestLogger() needs that active span.
+
+**Framework-specific packages:** autotel-hono, autotel-tanstack, autotel-cloudflare. Install the package for your framework and follow its README or CLAUDE.md.
+
+## Common Mistakes
+
+### HIGH Use getRequestLogger() in Hono without registering middleware first
+
+Wrong:
+
+```typescript
+const app = new Hono();
+app.get('/api/x', (c) => {
+  const log = getRequestLogger();
+  return c.json({});
+});
+```
+
+Correct:
+
+```typescript
+const app = new Hono();
+app.use('*', otel());
+app.get('/api/x', (c) => {
+  const log = getRequestLogger();
+  return c.json({});
+});
+```
+
+Middleware creates the span per request. Without it, getRequestLogger() has no active span and will throw.
+
+Source: packages/autotel-hono, docs/AGENT-GUIDE.md
+
+## Version
+
+Targets autotel v2.23.x.
+
+See also: autotel-instrumentation/SKILL.md — init and spans. autotel-request-logging/SKILL.md — request logger usage.

package/skills/autotel-instrumentation/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: autotel-instrumentation
+description: >
+  trace(), span(), instrument(), init(). Factory vs direct pattern, name inference. Sync init; use node-require for optional deps. Load when wrapping handlers or functions with spans.
+type: core
+library: autotel
+library_version: '2.23.0'
+sources:
+  - jagreehal/autotel:docs/ARCHITECTURE.md
+  - jagreehal/autotel:packages/autotel/src/functional.ts
+  - jagreehal/autotel:packages/autotel/CLAUDE.md
+---
+
+# Autotel — Instrumentation
+
+Wrap functions and handlers with `trace()`, `span()`, or `instrument()`. Call `init()` once at app startup. Keep init synchronous; use `safeRequire`/`requireModule` for optional dependencies.
+
+## Setup
+
+```typescript
+import { init, trace } from 'autotel';
+
+init({ service: 'my-app' });
+
+const handler = trace(async (req: Request) => {
+  return processRequest(req);
+});
+```
+
+With span context (attributes, request logger):
+
+```typescript
+const handler = trace((ctx) => async (req: Request) => {
+  ctx.setAttribute('http.route', '/api/checkout');
+  const log = getRequestLogger(ctx);
+  log.set({ path: req.url });
+  return processRequest(req);
+});
+```
+
+## Core Patterns
+
+**Explicit span name:**
+
+```typescript
+const checkout = trace('checkout', async (body) => {
+  return processCheckout(body);
+});
+```
+
+**instrument() with key:**
+
+```typescript
+import { instrument } from 'autotel';
+const fn = instrument({
+  key: 'processOrder',
+  fn: async (id) => db.orders.get(id),
+});
+```
+
+**span() for a child span:**
+
+```typescript
+import { span } from 'autotel';
+const result = await span('db.query', async () => db.query(sql));
+```
+
+**Init with optional config:**
+
+```typescript
+init({
+  service: 'my-api',
+  // see docs/CONFIGURATION.md for full options
+});
+```
+
+## Common Mistakes
+
+### HIGH Forget to call init() before using trace/span
+
+Wrong:
+
+```typescript
+import { trace } from 'autotel';
+export const fn = trace(async () => {});
+```
+
+Correct:
+
+```typescript
+import { init, trace } from 'autotel';
+init({ service: 'my-app' });
+export const fn = trace(async () => {});
+```
+
+SDK must be initialized; trace() and span() rely on the global tracer.
+
+Source: packages/autotel/CLAUDE.md
+
+### MEDIUM Wrong export path for submodules
+
+Wrong:
+
+```typescript
+import { Event } from 'autotel'; // Event is on autotel/event
+import { createTraceCollector } from 'autotel'; // testing subpath
+```
+
+Correct:
+
+```typescript
+import { trace, init, getRequestLogger } from 'autotel';
+import { Event } from 'autotel/event';
+import { createTraceCollector } from 'autotel/testing';
+```
+
+Use the exact export paths from package.json (autotel/event, autotel/testing, autotel/attributes, etc.).
+
+Source: packages/autotel/package.json exports
+
+## Version
+
+Targets autotel v2.23.x.
+
+See also: autotel-core/SKILL.md — when to use what. autotel-request-logging/SKILL.md — getRequestLogger requires active span.

package/skills/autotel-request-logging/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: autotel-request-logging
+description: >
+  getRequestLogger(), set(), info/warn/error, emitNow(). One snapshot per request; requires active span. Use when adding request-scoped context or replacing scattered console.log.
+type: core
+library: autotel
+library_version: '2.23.0'
+requires:
+  - autotel-instrumentation
+sources:
+  - jagreehal/autotel:packages/autotel/src/request-logger.ts
+  - jagreehal/autotel:docs/AGENT-GUIDE.md
+---
+
+# Autotel — Request Logging
+
+This skill builds on autotel-instrumentation. Read it first for init and span creation.
+
+Accumulate context with `getRequestLogger(ctx)`, `.set()`, and `.info()`/`.warn()`/`.error()`. Call `.emitNow()` (or rely on middleware) to emit one snapshot per request. Request logger requires an active span — use inside `trace()` or framework middleware.
+
+## Setup
+
+```typescript
+import { init, trace, getRequestLogger } from 'autotel';
+
+init({ service: 'my-app' });
+
+const handler = trace((ctx) => async (req: Request, res: Response) => {
+  const log = getRequestLogger(ctx);
+  log.set({ method: req.method, path: req.url });
+
+  const user = await getAuth(req);
+  log.set({ user: { id: user.id } });
+
+  const result = await doWork(req);
+  log.set({ result: { id: result.id } });
+  log.emitNow();
+  return res.json(result);
+});
+```
+
+When the framework creates the span (e.g. Hono middleware), call `getRequestLogger()` with no args:
+
+```typescript
+app.use(autotelMiddleware());
+app.get('/api/users', (c) => {
+  const log = getRequestLogger();
+  log.set({ route: 'users' });
+  return c.json({ users: [] });
+});
+```
+
+## Core Patterns
+
+**Accumulate then emit:**
+
+```typescript
+const log = getRequestLogger(ctx);
+log.set({ cart: { items: body.items.length } });
+log.set({ payment: { method: body.method } });
+log.error(err, { step: 'payment' });
+log.emitNow();
+```
+
+**RequestLogSnapshot:** `emitNow()` returns `{ timestamp, traceId, spanId, correlationId, context }`. You can pass `onEmit` in options to forward it.
+
+**Options:** `getRequestLogger(ctx?, { onEmit?: (snapshot) => void })` for custom fan-out on emit.
+
+## Common Mistakes
+
+### HIGH Call getRequestLogger() outside a span
+
+Wrong:
+
+```typescript
+function helper() {
+  const log = getRequestLogger();
+  log.set({ step: 'helper' });
+}
+```
+
+Correct:
+
+```typescript
+// Ensure helper runs inside trace() or middleware-created span
+function helper(ctx?: TraceContext) {
+  const log = getRequestLogger(ctx);
+  log.set({ step: 'helper' });
+}
+```
+
+Request logger attaches to the active span. If there is no active span, it throws. Wrap the call path with `trace()` or register middleware that creates a span per request.
+
+Source: packages/autotel/src/request-logger.ts
+
+## Version
+
+Targets autotel v2.23.x.
+
+See also: autotel-instrumentation/SKILL.md — creating the span. autotel-structured-errors/SKILL.md — use .error() to record errors in the snapshot.

package/skills/autotel-structured-errors/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: autotel-structured-errors
+description: >
+  createStructuredError, parseError, recordStructuredError. API errors with message, why, fix, link; client parsing for UI. Use in API routes and client catch blocks.
+type: core
+library: autotel
+library_version: '2.23.0'
+sources:
+  - jagreehal/autotel:packages/autotel/src/structured-error.ts
+  - jagreehal/autotel:packages/autotel/src/parse-error.ts
+  - jagreehal/autotel:docs/AGENT-GUIDE.md
+---
+
+# Autotel — Structured Errors
+
+Throw errors with `createStructuredError({ message, why?, fix?, link?, status?, cause? })` in API routes and services. On the client, use `parseError(caught)` to get `message`, `status`, `why`, `fix`, `link` for toasts and UI.
+
+## Setup
+
+**Server (API route or service):**
+
+```typescript
+import { createStructuredError } from 'autotel';
+
+if (!user) {
+  throw createStructuredError({
+    message: 'User not found',
+    status: 404,
+    why: `No user with ID "${userId}"`,
+    fix: 'Check the user ID and try again',
+    link: 'https://docs.example.com/errors/user-not-found',
+  });
+}
+```
+
+**Client:**
+
+```typescript
+import { parseError } from 'autotel';
+
+try {
+  await fetch('/api/checkout', { method: 'POST', body: JSON.stringify(data) });
+} catch (err) {
+  const e = parseError(err);
+  toast.error(e.message, { description: e.why });
+  if (e.fix) setHelp(e.fix);
+  if (e.link) setDocLink(e.link);
+}
+```
+
+## Core Patterns
+
+**Wrap a caught error (preserve cause):**
+
+```typescript
+try {
+  await stripe.charges.create(data);
+} catch (err) {
+  throw createStructuredError({
+    message: 'Payment failed',
+    status: 402,
+    why: err instanceof Error ? err.message : 'Unknown error',
+    fix: 'Try a different payment method or contact support',
+    link: 'https://docs.stripe.com/declines',
+    cause: err,
+  });
+}
+```
+
+**Record on current span:** Use `recordStructuredError(ctx, error)` or the request logger's `.error(error, fields)` so the span gets error attributes and status.
+
+**parseError** handles FetchError (ofetch), nested `data.data`, and plain Error. Returns `{ message, status, why?, fix?, link?, raw }`.
+
+## Common Mistakes
+
+### HIGH Throw new Error() in API routes instead of createStructuredError
+
+Wrong:
+
+```typescript
+throw new Error('Payment failed');
+```
+
+Correct:
+
+```typescript
+throw createStructuredError({
+  message: 'Payment failed',
+  status: 402,
+  why: 'Card declined by issuer',
+  fix: 'Try a different payment method',
+  link: 'https://docs.example.com/payments',
+});
+```
+
+Clients and agents need structured fields (why, fix, link) for actionable errors. parseError() reads these from API responses.
+
+Source: docs/AGENT-GUIDE.md, AGENTS.md
+
+### MEDIUM Client only shows error.message and ignores why/fix/link
+
+Wrong:
+
+```typescript
+catch (err) {
+  toast.error(err.message);
+}
+```
+
+Correct:
+
+```typescript
+import { parseError } from 'autotel';
+catch (err) {
+  const e = parseError(err);
+  toast.error(e.message, { description: e.why });
+  if (e.fix) showFix(e.fix);
+  if (e.link) setDocLink(e.link);
+}
+```
+
+parseError() extracts status, why, fix, and link from API error responses and FetchError so the UI can show them.
+
+Source: docs/AGENT-GUIDE.md
+
+## Version
+
+Targets autotel v2.23.x.
+
+See also: autotel-request-logging/SKILL.md — use .error() to record errors in the request snapshot.

package/src/enrichers.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, it } from 'vitest';
+import { userAgent, geo, requestSize } from './enrichers';
+
+describe('enrichers', () => {
+  describe('userAgent', () => {
+    it('parses Chrome on macOS', () => {
+      const result = userAgent({
+        'user-agent':
+          'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+      });
+
+      expect(result).toMatchObject({
+        'user_agent.browser': 'Chrome 120.0.0.0',
+        'user_agent.os': 'macOS 10.15.7',
+        'user_agent.device': 'desktop',
+      });
+      expect(result?.['user_agent.raw']).toBeDefined();
+    });
+
+    it('parses Firefox on Windows', () => {
+      const result = userAgent({
+        'user-agent':
+          'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0',
+      });
+
+      expect(result).toMatchObject({
+        'user_agent.browser': 'Firefox 121.0',
+        'user_agent.os': 'Windows 10.0',
+        'user_agent.device': 'desktop',
+      });
+    });
+
+    it('detects mobile device', () => {
+      const result = userAgent({
+        'user-agent':
+          'Mozilla/5.0 (iPhone; CPU iPhone OS 17_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Mobile/15E148 Safari/604.1',
+      });
+
+      expect(result?.['user_agent.device']).toBe('mobile');
+      expect(result?.['user_agent.os']).toBe('iOS 17.2');
+    });
+
+    it('detects bot', () => {
+      const result = userAgent({
+        'user-agent': 'Googlebot/2.1 (+http://www.google.com/bot.html)',
+      });
+
+      expect(result?.['user_agent.device']).toBe('bot');
+    });
+
+    it('returns undefined when no user-agent header', () => {
+      expect(userAgent({})).toBeUndefined();
+    });
+
+    it('accepts mixed-case User-Agent header names', () => {
+      const result = userAgent({
+        'User-Agent':
+          'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0',
+      });
+
+      expect(result).toMatchObject({
+        'user_agent.browser': 'Firefox 121.0',
+        'user_agent.os': 'Windows 10.0',
+      });
+    });
+  });
+
+  describe('geo', () => {
+    it('extracts Vercel geo headers', () => {
+      const result = geo({
+        'x-vercel-ip-country': 'US',
+        'x-vercel-ip-country-region': 'CA',
+        'x-vercel-ip-city': 'San%20Francisco',
+        'x-vercel-ip-latitude': '37.7749',
+        'x-vercel-ip-longitude': '-122.4194',
+      });
+
+      expect(result).toEqual({
+        'geo.country': 'US',
+        'geo.region': 'CA',
+        'geo.city': 'San Francisco',
+        'geo.latitude': '37.7749',
+        'geo.longitude': '-122.4194',
+      });
+    });
+
+    it('extracts Cloudflare country header', () => {
+      const result = geo({ 'cf-ipcountry': 'GB' });
+
+      expect(result).toEqual({ 'geo.country': 'GB' });
+    });
+
+    it('does not throw on malformed encoded city values', () => {
+      expect(() =>
+        geo({
+          'x-vercel-ip-country': 'US',
+          'x-vercel-ip-city': '%E0%A4%A',
+        }),
+      ).not.toThrow();
+    });
+
+    it('returns undefined when no geo headers', () => {
+      expect(geo({})).toBeUndefined();
+    });
+
+    it('returns longitude when it is the only geo signal', () => {
+      const result = geo({ 'x-vercel-ip-longitude': '-0.1276' });
+
+      expect(result).toEqual({ 'geo.longitude': '-0.1276' });
+    });
+  });
+
+  describe('requestSize', () => {
+    it('extracts request and response sizes', () => {
+      const result = requestSize(
+        { 'content-length': '1024' },
+        { 'content-length': '2048' },
+      );
+
+      expect(result).toEqual({
+        'http.request.body.size': 1024,
+        'http.response.body.size': 2048,
+      });
+    });
+
+    it('handles request-only size', () => {
+      const result = requestSize({ 'content-length': '512' });
+
+      expect(result).toEqual({ 'http.request.body.size': 512 });
+    });
+
+    it('returns undefined when no content-length headers', () => {
+      expect(requestSize({}, {})).toBeUndefined();
+    });
+
+    it('ignores non-numeric content-length', () => {
+      expect(requestSize({ 'content-length': 'abc' })).toBeUndefined();
+    });
+
+    it('ignores invalid numeric content-length values', () => {
+      expect(requestSize({ 'content-length': '-1' })).toBeUndefined();
+      expect(requestSize({ 'content-length': '12.5' })).toBeUndefined();
+    });
+
+    it('ignores non-digit numeric formats for content-length', () => {
+      expect(requestSize({ 'content-length': '1e3' })).toBeUndefined();
+      expect(requestSize({ 'content-length': '+10' })).toBeUndefined();
+    });
+  });
+});