autotel 4.3.0 → 6.0.0

package/skills/autotel-frameworks/SKILL.md

@@ -1,90 +0,0 @@
----
-name: autotel-frameworks
-description: >
-  Hono, Fastify, TanStack Start, Cloudflare Workers. Middleware and init; getRequestLogger() in handlers. Load when adding Autotel to a web framework.
----
-
-# 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.
-
-When adding new request/exception events in framework handlers, prefer correlated logs (`getRequestLogger().info/warn/error`) instead of introducing new `span.addEvent()` usage.
-
-## 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

@@ -1,145 +0,0 @@
----
-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.
----
-
-# 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.
-
-For new event emission, prefer correlated logs (OTel Logs API path) over adding new direct span-event calls.
-
-## 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
-});
-```
-
-**Single backend vs multi-backend OTLP:**
-
-```typescript
-init({
-  service: 'my-api',
-  endpoint: 'https://otlp-gateway-prod.grafana.net/otlp', // single destination
-});
-
-init({
-  service: 'my-api',
-  logs: true,
-  destinations: [
-    {
-      endpoint: 'https://otlp-gateway-prod.grafana.net/otlp',
-      headers: 'Authorization=Basic ...',
-    },
-    {
-      endpoint: 'https://api.honeycomb.io',
-      headers: { 'x-honeycomb-team': process.env.HONEYCOMB_API_KEY! },
-      signals: ['traces'],
-    },
-  ],
-});
-```
-
-## 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

@@ -1,94 +0,0 @@
----
-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.
----
-
-# 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.
-
-Preferred event model: treat request logger emissions as the default way to capture request-correlated events in new code. If a backend still expects span-event rendering, keep compatibility at export/processor level rather than adding new `span.addEvent()` calls in application code.
-
-## 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

@@ -1,125 +0,0 @@
----
-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.
----
-
-# 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.
-
-For new exception event flows, prefer request-logger/log-based correlation and keep span-event compatibility as an implementation detail (processors/export path), not a new app-level dependency.
-
-**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.