autotel-api-surface

Files (1)

• SKILL.md

SKILL.md (first lines)

# Autotel API Surface

Complete API reference for autotel's functional instrumentation library.

## Purpose

Canonical reference for all public autotel APIs, their signatures, import paths, and usage patterns. Use this when writing or reviewing code that uses autotel.

## When to Use

- Writing new instrumented code
- Choosing between trace/span/instrument
- Looking up function signatures or import paths
- Understanding configuration options

## Core API

All from `import { ... } from 'autotel'` unless noted.

### trace(fn) / trace(name, fn) / trace.run(name, operation)

**`trace` wraps, `trace.run` runs.** Every `trace(...)` form returns a wrapper
and executes nothing, so a `trace()` call can never run user code at module
load. `trace.run(...)` runs the operation now and injects its `TraceContext`.
Two names, so no call shape is ambiguous and nothing inspects a callback's
parameter name.

**Direct pattern** (no span context needed):

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

export const getUser = trace(async (id: string) => {
  return await db.users.findById(id);
});
```

**Immediate named operation** (access span context to set attributes):

```typescript
const result = await trace.run('checkout', async (ctx) => {
  ctx.setAttribute('user.id', req.userId);
  return await processCheckout(req.body);
});
```

**Reusable explicit name:**

```typescript
export const handler = trace('checkout', async (req: Request) =>
  processCheckout(req.body),
);
```

Reach the span from inside any traced body with the ambient `ctx` import,
which resolves at any depth:

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

export const handler = trace('checkout', async (req: Request) => {
  ctx.setAttribute('user.id', req.userId);
  return processCheckout(req.body);
});
```

The options form of the same wrapper, for when you need its extra fields:

```typescript
export const handler = instrument({
  key: 'checkout',
  fn: async (req: Request) => processCheckout(req.body),
});
```

For a reusable function that needs injected context, use
`withTracing({ name: 'checkout' })((ctx) => async (req) => ...)`.

**Name inference rules** (highest to lowest priority):

1. Explicit name passed to `trace('name', fn)`, `instrument({ key: 'name', fn })`, or `withTracing({ name })`
2. Named function: `trace(async function getUser() { ... })` → `getUser`
3. Const/let/var assignment: `const getUser = trace(async () => { ... })` → `getUser`
4. Fallback: `unknown`

### span(name, fn)

Like `trace()` but always requires an explicit name. Useful for inline spans.

```typescript
import { span } from 'autotel';

const result = await span('validate-cart', async () => {
  return validateCartItems(cart);
});
```

### instrument({ key, fn })

Like `trace()` with an explicit key for naming. Useful when you want the span name decoupled from the variable name.

```typescript
import { instrument } from 'autotel';

export const handler = instrument({
  key: 'checkout.process',
  fn: async (data: CheckoutData) => {
    return await processCheckout(data);
  },
});
```

### getRequestLogger(ctx?)

Returns a request-scoped logger that accumulates attributes and events on the active span. Emits one coherent snapshot per request.

**Requires an active span.** Call inside a `trace()` wrapper or after framework middleware creates a span.

```typescript

From jagreehal/autotel, Apache-2.0.

More from jagreehal/autotel