autotel-anti-patterns

Files (1)

• SKILL.md

SKILL.md (first lines)

# Autotel Anti-Patterns

Common mistakes when using autotel, why they're wrong, and how to fix them.

## Purpose

Quick reference for catching and fixing incorrect autotel usage. Each anti-pattern includes the bad code, why it's wrong, the correct code, and a one-line rationale.

## When to Use

- Reviewing code that uses autotel
- Debugging instrumentation issues
- Teaching correct autotel patterns
- Auditing an existing codebase

## Anti-Patterns

### 1. Async Init / await import()

**Bad:**

```typescript
async function setup() {
  const { init } = await import('autotel');
  init({ service: 'my-api' });
}
await setup();
```

**Good:**

```typescript
import { init } from 'autotel';
init({ service: 'my-api' });
```

**Why:** `init()` must be synchronous. `await import()` delays SDK registration, causing spans to be lost before init completes. Use static imports or `safeRequire`/`requireModule` for optional dependencies.

---

### 2. Manual Span Lifecycle

**Bad:**

```typescript
import { trace } from '@opentelemetry/api';

const tracer = trace.getTracer('my-service');

export async function getUser(id: string) {
  return tracer.startActiveSpan('getUser', async (span) => {
    try {
      span.setAttribute('user.id', id);
      const user = await db.users.findById(id);
      span.setStatus({ code: SpanStatusCode.OK });
      return user;
    } catch (error) {
      span.recordException(error);
      span.setStatus({ code: SpanStatusCode.ERROR });
      throw error;
    } finally {
      span.end();
    }
  });
}
```

**Good:**

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

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

**Why:** `trace()` handles the entire span lifecycle automatically. Start, end, error recording, and status. Manual lifecycle is verbose and error-prone (forgetting `span.end()`, incorrect error handling). Use `trace()`, `span()`, or `instrument()` instead.

---

### 3. Scattered console.log

**Bad:**

```typescript
export async function handleCheckout(req, res) {
  console.log('Checkout started');
  const user = await getAuth(req);
  console.log('User:', user.id);
  const cart = await getCart(user.id);
  console.log('Cart items:', cart.items.length);
  const result = await processCheckout(cart);
  console.log('Order:', result.id);
  return res.json(result);
}
```

**Good:**

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

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

  const cart = await getCart(user.id);
  log.set({ cart: { items: cart.items.length } });

  const result = await processCheckout(cart);
  log.set({ order: { id: result.id } });
  log.emitNow();
  return res.json(result);
});
```

From jagreehal/autotel, Apache-2.0.

More from jagreehal/autotel