migrate-to-autotel

Files (1)

• SKILL.md

SKILL.md (first lines)

# Migrate to autotel

Replacing tracing in a live service is risky. You can lose data, change span shapes, or break dashboards your on-call team relies on. This skill covers the safe paths from each major source, what to change in your code, and how to verify the cutover before turning the old stack off.

## Choose your starting point

| You're using                                | Section                                                        |
| ------------------------------------------- | -------------------------------------------------------------- |
| Raw `@opentelemetry/sdk-node`               | [From raw OTel SDK](#from-raw-opentelemetry-sdk-node)          |
| Sentry `@sentry/node` performance / tracing | [From Sentry](#from-sentry-performance-tracing)                |
| Datadog APM (`dd-trace`)                    | [From Datadog APM](#from-datadog-apm)                          |
| New Relic agent (`newrelic`)                | [From New Relic Node agent](#from-new-relic-node-agent)        |
| Honeycomb Beelines                          | [From Honeycomb Beelines](#from-honeycomb-beelines)            |
| OpenTracing / OpenCensus                    | [From OpenTracing / OpenCensus](#from-opentracing--opencensus) |
| `console.log` everything                    | [From unstructured logging](#from-unstructured-logging)        |

## Universal cutover plan

1. **Pin metrics.** Snapshot p50 / p95 / p99 / error-rate / span-count for the top 5 endpoints. You'll diff post-cutover.
2. **Run both side-by-side for 24–48 h.** Both old and new exporters wired in parallel. Use distinct backends (or distinct datasets) so you can compare like for like.
3. **Cutover dashboards & alerts.** Re-author critical dashboards on the autotel data; keep both alert sets armed.
4. **Disable the old stack.** Remove old SDK imports + processors; redeploy.
5. **Decommission.** Remove old packages from `package.json` and lock files; archive old dashboards.

Don't compress this into a single PR. The riskiest step is "disable old stack". Keep it last.

## From raw `@opentelemetry/sdk-node`

The smoothest migration. autotel layers on top of OTel. Your span attributes, propagators, and exporters can stay.

### Drop-in init

Before:

```typescript
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { resourceFromAttributes } from '@opentelemetry/resources';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';

const sdk = new NodeSDK({
  resource: resourceFromAttributes({ 'service.name': 'my-app' }),
  spanProcessors: [
    new BatchSpanProcessor(
      new OTLPTraceExporter({ url: process.env.OTEL_ENDPOINT }),
    ),
  ],
});
sdk.start();
```

After:

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

init({
  service: 'my-app',
  endpoint: process.env.OTEL_ENDPOINT!, // base URL: autotel appends /v1/traces
  autoInstrumentations: ['http', 'undici'], // what NodeSDK users usually had
});
```

`init()` builds the provider and an OTLP HTTP/JSON exporter, and sets up the W3C trace-context and baggage propagators. It turns on **no** auto-instrumentation by default: list the libraries in `autoInstrumentations` (needs `@opentelemetry/auto-instrumentations-node` installed), or pass your existing `instrumentations: [...]`. If your old `url` ended in `/v1/traces`, drop the suffix. With no `endpoint` (or `OTEL_EXPORTER_OTLP_ENDPOINT`) nothing is exported.

### What you gain immediately

- `getRequestLogger().set({ … })` flattens onto the active span: no more `span.setAttribute('user.id', id)` boilerplate.
- PII redaction (`attributeRedactor: 'default'`) switches on by itself when `environment` (default `NODE_ENV`) is `production`.
- `destinations: [...]` for straightforward OTLP multi-backend fan-out.
- The same API on Cloudflare Workers and edge runtimes via `autotel-cloudflare` / `autotel-edge`.

### What stays the same

- Your propagator (W3C trace context + baggage are the default).
- Your exporters: pass them via `spanExporters` (autotel batches them) or `spanProcessors` (full control).
- Your resource attributes (`resourceAttributes` or `resource`).

## From Sentry performance tracing

Sentry's tracing is OTel-compatible since v7+, but their span shapes have non-standard names (`http.server`, `db.query`).

### Step 1: Use `autotel-sentry` to keep sending to Sentry

If you want the dashboards to stay in Sentry, autotel can export OTLP to Sentry's OTLP intake:

```typescript
import * as Sentry from '@sentry/node';
import { init } from 'autotel';
import { sentryOtlpConfig } from 'autotel-sentry';

const sentry = sentryOtlpConfig(process.env.SENTRY_DSN!);

// Keep Sentry for errors, but let autotel own OpenTelemetry
Sentry.init({ dsn: sentry.dsn, skipOpenTelemetrySetup: true });
// Sentry reads trace ids from the active OpenTelemetry span
Sentry.setOpenTelemetryContextAsyncContextStrategy();

init({ service: 'my-app', endpoint: sentry.endpoint, headers: sentry.headers });
```

### Step 2: Replace Sentry-specific helpers

| Sentry                                                     | autotel                                                              |
| ---------------------------------------------------------- | -------------------------------------------------------------------- |
| `Sentry.startSpan({ op: 'fn', name: 'process' }, () => …)` | `trace.run('process', (ctx) => …)`                                   |
| `Sentry.captureException(err)`                             | `getRequestLogger().error(err)` or `recordStructuredError(ctx, err)` |
| `Sentry.setUser({ id })`                                   | `getRequestLogger().set({ user: { id } })`                           |
| `Sentry.setContext('cart', { … })`                         | `getRequestLogger().set({ cart: { … } })`                            |
| reusable named transaction function                        | `trace(name, fn)` or `instrument({ key: name, fn })`                 |

### Step 3: Decide on errors-only vs full tracing

Sentry shines at errors; for tracing you may want to fan out to Honeycomb or Grafana Tempo. If both targets are plain OTLP backends, prefer `destinations`:

```typescript
init({
  service: 'my-app',
  destinations: [

From jagreehal/autotel, Apache-2.0.

More from jagreehal/autotel