autotel
Version:
Write Once, Observe Anywhere
146 lines (106 loc) • 3.28 kB
Markdown
---
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.
---
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);
});
```
**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'],
},
],
});
```
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
Targets autotel v2.23.x.
See also: autotel-core/SKILL.md — when to use what. autotel-request-logging/SKILL.md — getRequestLogger requires active span.