autotel

Files (5)

• SKILL.md
• code-review.md · references/
• request-logger.md · references/
• structured-errors.md · references/
• wide-events.md · references/

SKILL.md (first lines)

# Autotel

Philosophy: "Write once, observe everywhere" - instrument once, stream to any OTLP-compatible backend.

`trace()` wraps functions. `getRequestLogger()` accumulates context. `createStructuredError()` adds why/fix/link to errors. Canonical log lines emit one wide event per request automatically.

## When to Use

- Instrumenting functions with tracing
- Code uses `console.log` / `console.error` for observability
- Error handling lacks structured context (no why, fix, or link)
- Adding tracing to any Node.js or edge runtime handler
- Reviewing code for observability anti-patterns
- Setting up observability in Cloudflare Workers, Hono, or Next.js
- Working in the autotel monorepo

## Quick Reference

| Task                               | Reference                                               |
| ---------------------------------- | ------------------------------------------------------- |
| Convert console.log to wide events | [wide-events.md](references/wide-events.md)             |
| Add structured errors              | [structured-errors.md](references/structured-errors.md) |
| Accumulate request context         | [request-logger.md](references/request-logger.md)       |
| Review code for anti-patterns      | [code-review.md](references/code-review.md)             |
| Add attribute redaction            | (use `init({ attributeRedactor: 'default'               | 'strict' | 'pci-dss' })` or custom config) |
| Lock init from re-initialization   | (use `lockLogger()` in framework plugins)               |          |

## Tracing API

```typescript
import { trace, ctx, span } from 'autotel';

// trace(name, fn) wraps a reusable function under a stable span name
export const createUser = trace('user.create', async (data) => {
  // The ambient ctx reads the active span from anywhere inside a traced body
  ctx.setAttribute('user.id', data.id);
  return await db.users.create(data);
});

// trace(fn) infers the name from the function or const
export const getUser = trace(async (id) => {
  return await db.users.findById(id);
});

// Nested span
span('db.insert', async () => {
  await db.insert(record);
});
```

`ctx` is a live view of the active span, not a value captured at import time.
Read it inside a traced body and it answers from that span. With nothing traced

- an uninstrumented test run, or a plain `node server.js` - `ctx.traceId` reads
  `undefined` and the methods no-op, so instrumentation is never what throws.

Attribute values can be as rich as the data: an object, `Map`, `Set` or `Date`
is flattened to dot-notation keys, so `ctx.setAttribute('user', user)` records
`user.id`, `user.plan`. Never flatten by hand before the call.

`requestCtx` is the same ambient view aimed at the **request** span. Framework
instrumentation opens a span per middleware and per route handler, so context
describing the whole request - the authenticated user, the tenant, the plan -
set from a shared middleware belongs there rather than on a layer span that ends
at `next()`:

```typescript
import { ctx, requestCtx } from 'autotel';

app.use((req, _res, next) => {
  requestCtx.setAttributes({ user: req.user }); // on GET /users/:id
  ctx.setAttribute('auth.cache_hit', cached); // on the middleware's own span
  next();
});
```

`withTracing({ name })((ctx) => fn)` hands the context in as an argument
instead. Both forms are supported: prefer the ambient `ctx` in application
code, and the factory when a wrapper needs an explicit context handle.

### Recording Errors

**Default: throw, don't catch.** `trace()` records status, exception, and structured attributes when the wrapped function rejects.

```typescript
import { trace, createStructuredError } from 'autotel';

export const charge = trace('cart.charge', async (cart) => {
  if (!cart.items.length) {
    throw createStructuredError({
      message: 'Cart is empty',
      why: 'User submitted checkout with no items',
      fix: 'Validate cart on the client before submit',
      link: 'https://docs.example.com/errors/empty-cart',
    });
  }
  return await processCart(cart);
});
```

Fallbacks, in order:

1. **Attach call-site context, then rethrow**: `getRequestLogger(ctx).error(err, { step })`. Use when the rethrown error needs context only known at the catch site.
2. **Writing instrumentation/middleware that wraps user handlers**: `ctx.recordError(err)` from inside a `withTracing({})((ctx) => ...)` callback. Sets ERROR status, structured `error.*` attributes, and (during the back-compat window) records the exception. Accepts `unknown` so no `as Error` cast is needed in catch blocks. For code that doesn't have a `ctx` handle, use the standalone form `recordStructuredError(ctx, err)`.

```typescript
// Instrumentation wrapping a user handler. trace.run() is the immediate form:
// it runs now and hands the callback the span's ctx. trace(name, fn) returns a
// wrapper instead, and passes fn the caller's arguments, never a ctx.
return trace.run(name, async (ctx) => {
  try {
    return await userHandler(args);
  } catch (err) {
    ctx.recordError(err); // ergonomic replacement for ctx.recordException
    throw err;
  }
});
```

From jagreehal/autotel, Apache-2.0.

More from jagreehal/autotel