Quick Start

1. Install

npm install autotel

2. Initialize

Create an instrumentation.ts file (or add to your entry point):

import { init } from 'autotel';

init({
  service: 'my-app',
  endpoint: 'http://localhost:4318',
});

Import it first in your entry point:

import './instrumentation'; // Must be first!

import express from 'express';
// ... rest of your app

3. Trace Functions

import { trace } from 'autotel';

// Factory pattern (receives ctx)
export const createUser = trace((ctx) => async (data: UserData) => {
  ctx.setAttribute('user.email', data.email);
  const user = await db.users.create(data);
  return user;
});

// Direct pattern (no ctx needed)
export const getUser = trace(async (id: string) => {
  return await db.users.findById(id);
});

4. Request-Scoped Logging

import { trace, getRequestLogger } from 'autotel';

export const postCheckout = trace((ctx) => async (req, res) => {
  const log = getRequestLogger(ctx);
  const user = await getAuth(req);
  log.set({ user: { id: user.id } });

  const result = await processCheckout(user.id, req.body);
  log.set({ orderId: result.id });
  log.emitNow();

  return res.json(result);
});

Fork for async background work:

log.fork('send-email', async () => {
  await sendOrderEmail(orderId);
});

5. Structured Errors

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',
    // Backend-only context (never serialized to clients)
    internal: { lookupKey: `users:${userId}`, attempt: 2 },
  });
}

On the client, parse errors with:

import { parseError } from 'autotel';

try {
  await fetch('/api/checkout', { method: 'POST', body: JSON.stringify(data) });
} catch (err) {
  const error = parseError(err);
  toast.error(error.message, {
    description: error.why,
    action: error.fix
      ? { label: 'Fix', onClick: () => showHelp(error.fix) }
      : undefined,
  });
}

6. Product Events

import { track } from 'autotel';

track('user.signup', { userId: '123', plan: 'pro' });

Examples

• example-basic — Core features: trace(), nested spans, metrics, track(), Pino integration, error handling.
• example-http — Express server with manual trace() in route handlers and --import flag.
• example-bun-fullstack — Bun runtime with Bun.serve and trace().

Next Steps

• Configuration — env vars, YAML config, and precedence
• Architecture — patterns and conventions
• Agent Guide — before/after examples for instrumentation