autotel 4.3.0 → 5.0.0

package/skills/migrate-to-autotel/SKILL.md

@@ -12,7 +12,7 @@ license: MIT
 
 # 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.
+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
 
@@ -34,11 +34,11 @@ Replacing tracing in a live service is risky — you can lose data, change span
 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.
+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.
+The smoothest migration. autotel layers on top of OTel. Your span attributes, propagators, and exporters can stay.
 
 ### Drop-in init
 
@@ -76,15 +76,15 @@ init({
 
 ### What you gain immediately
 
-- `useLogger().set({ … })` flattens onto the active span — no more `span.setAttribute('user.id', id)` boilerplate.
-- `attributeRedactor: 'default'` — PII masking for free in production.
+- `useLogger().set({ … })` flattens onto the active span: no more `span.setAttribute('user.id', id)` boilerplate.
+- `attributeRedactor: 'default'`: PII masking for free in production.
 - `destinations: [...]` for straightforward OTLP multi-backend fan-out.
 - Cloudflare Workers + Edge support out of the box (`defineWorkerFetch`).
 
 ### What stays the same
 
 - Your propagator (`W3CTraceContextPropagator` is the default).
-- Your exporters — pass them via `spanProcessors` if you want to keep custom ones.
+- Your exporters: pass them via `spanProcessors` if you want to keep custom ones.
 - Your resource attributes.
 
 ## From Sentry performance tracing
@@ -148,7 +148,7 @@ Datadog APM uses its own format and proprietary tracer. The migration path is OT
 
 ### Step 1: Stop importing `dd-trace`
 
-`dd-trace` patches every supported library on import — keeping it in the bundle while autotel runs causes double-instrumentation. Remove `import 'dd-trace'` (or the `--require dd-trace/init` arg).
+`dd-trace` patches every supported library on import. Keeping it in the bundle while autotel runs causes double-instrumentation. Remove `import 'dd-trace'` (or the `--require dd-trace/init` arg).
 
 ### Step 2: Point autotel at Datadog OTLP intake
 
@@ -166,7 +166,7 @@ For the EU site use `datadoghq.eu`; for US3 / US5 see Datadog's region matrix.
 
 ### Step 3: Map Datadog span tags
 
-Datadog uses `service`, `resource`, `operation` — OTel uses `service.name`, `http.route`, span name. autotel handles the conversion automatically when exporting via `dd-api-key`. If you have custom Datadog tags in dashboards, rename them in code:
+Datadog uses `service`, `resource`, `operation`. OTel uses `service.name`, `http.route`, span name. autotel handles the conversion automatically when exporting via `dd-api-key`. If you have custom Datadog tags in dashboards, rename them in code:
 
 | Datadog tag | OTel attribute              |
 | ----------- | --------------------------- |
@@ -185,7 +185,7 @@ Datadog uses `service`, `resource`, `operation` — OTel uses `service.name`, `h
 
 ## From New Relic Node agent
 
-New Relic's agent is invasive — it patches Node internals. Plan a maintenance window for the cutover.
+New Relic's agent is invasive. It patches Node internals. Plan a maintenance window for the cutover.
 
 ### Step 1: Remove `--require newrelic`
 
@@ -214,7 +214,7 @@ For EU: `https://otlp.eu01.nr-data.net/v1/traces`.
 
 ## From Honeycomb Beelines
 
-Beelines for Node was Honeycomb's pre-OTel SDK. Migration is straightforward — Honeycomb supports OTLP natively.
+Beelines for Node was Honeycomb's pre-OTel SDK. Migration is straightforward. Honeycomb supports OTLP natively.
 
 ```typescript
 init({
@@ -234,7 +234,7 @@ init({
 
 Both are deprecated; the migration is "rewrite the tracer setup, leave call sites alone." OpenTracing's `Tracer.startSpan` and OpenCensus's `tracer.startRootSpan` shapes are similar enough that a script can replace them with `trace()` calls in most files.
 
-For libraries you don't control that still use OpenTracing, the OTel project ships a [shim](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-shim-opentracing) — wire it once, then migrate at your own pace.
+For libraries you don't control that still use OpenTracing, the OTel project ships a [shim](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-shim-opentracing). Wire it once, then migrate at your own pace.
 
 ## From unstructured logging
 
@@ -249,21 +249,21 @@ See [`review-otel-patterns`](../review-otel-patterns/SKILL.md) for the framework
 
 ## Verifying the cutover
 
-| Check                       | How                                                                                           |
-| --------------------------- | --------------------------------------------------------------------------------------------- |
-| **Span volume matches**     | Compare `count(spans)` per route over 24h; should be within ±5 %                              |
-| **p99 latency unchanged**   | Histograms on both backends                                                                   |
-| **Error rate unchanged**    | `count(spans where status=error)`                                                             |
-| **Trace correlation works** | Pick 10 random `traceId`s; confirm cross-service spans resolve                                |
-| **Bundle size acceptable**  | `pnpm bundle-size` — moving from heavy agents (New Relic, Datadog) often _shrinks_ the bundle |
+| Check                       | How                                                                                          |
+| --------------------------- | -------------------------------------------------------------------------------------------- |
+| **Span volume matches**     | Compare `count(spans)` per route over 24h; should be within ±5 %                             |
+| **p99 latency unchanged**   | Histograms on both backends                                                                  |
+| **Error rate unchanged**    | `count(spans where status=error)`                                                            |
+| **Trace correlation works** | Pick 10 random `traceId`s; confirm cross-service spans resolve                               |
+| **Bundle size acceptable**  | `pnpm bundle-size`: moving from heavy agents (New Relic, Datadog) often _shrinks_ the bundle |
 
 ## Anti-patterns
 
 | Anti-pattern                                              | Fix                                                                                                                           |
 | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| Both old SDK and autotel running on the same library      | Pick one — double-instrumentation duplicates spans                                                                            |
+| Both old SDK and autotel running on the same library      | Pick one: double-instrumentation duplicates spans                                                                             |
 | Removing the old SDK in the same PR as adding autotel     | Run both side-by-side for 24–48 h first                                                                                       |
 | Changing span names during migration                      | Preserve names; rename in a separate PR after dashboards re-pointed                                                           |
 | No metric snapshot before cutover                         | Take p50/p95/p99 + error-rate baselines first                                                                                 |
-| Migrating prod before staging                             | Always staging first — at least 24 h                                                                                          |
+| Migrating prod before staging                             | Always staging first: at least 24 h                                                                                           |
 | Trusting the old vendor agent's auto-instrumentation list | autotel's targeted instrumentations (`autotel-drizzle`, `autotel-mongoose`, …) are faster and tighter; expect to add a couple |

package/skills/review-otel-patterns/SKILL.md

@@ -17,7 +17,7 @@ license: MIT
 
 # Review OpenTelemetry patterns
 
-Review and improve OpenTelemetry instrumentation in TypeScript/JavaScript codebases using autotel. Replace ad-hoc tracing with idiomatic OTel-native spans, metrics and structured logs that work across every major framework and edge runtime — without vendor lock-in.
+Review and improve OpenTelemetry instrumentation in TypeScript/JavaScript codebases using autotel. Replace ad-hoc tracing with idiomatic OTel-native spans, metrics and structured logs that work across every major framework and edge runtime. Without vendor lock-in.
 
 ## When to use
 
@@ -64,7 +64,7 @@ npm install autotel-sentry        # Sentry exporter via OTLP
 
 ### Next.js (App Router)
 
-Step 1 — Initialise once in `instrumentation.ts`:
+Step 1: Initialise once in `instrumentation.ts`:
 
 ```typescript
 // instrumentation.ts
@@ -82,7 +82,7 @@ export function register() {
 }
 ```
 
-Step 2 — Wrap route handlers:
+Step 2: Wrap route handlers:
 
 ```typescript
 // app/api/checkout/route.ts
@@ -96,9 +96,9 @@ export const POST = withAutotel(async (request: Request) => {
 });
 ```
 
-Step 3 — Tag Server Actions the same way (`withAutotel`).
+Step 3: Tag Server Actions the same way (`withAutotel`).
 
-Step 4 — Browser → server trace propagation: drop in `<TraceProvider />` from `autotel-web` so the W3C `traceparent` header is forwarded automatically.
+Step 4: Browser to server trace propagation: drop in `<TraceProvider />` from `autotel-web` so the W3C `traceparent` header is forwarded automatically.
 
 ### Nuxt + Nitro v3
 
@@ -149,14 +149,13 @@ export const Route = createRootRoute({
 
 ```typescript
 import { Hono } from 'hono';
-import { honoToolkit } from 'autotel-adapters';
+import { autotelMiddleware, useLogger } from 'autotel-adapters/hono';
 
-const { useLogger, withAutotel } = honoToolkit;
 const app = new Hono();
-app.use('*', withAutotel({ service: 'my-api' }));
+app.use('*', autotelMiddleware());
 
 app.get('/api/users', (c) => {
-  const log = useLogger(c);
+  const log = useLogger();
   log.set({ users: { count: 42 } });
   return c.json({ users: [] });
 });
@@ -168,7 +167,7 @@ The `autotel-adapters` toolkit ships a uniform shape for these: `withAutotel` mi
 
 ### Cloudflare Workers (with auto `waitUntil`)
 
-`defineWorkerFetch` instruments the handler **and** wires `ctx.waitUntil` for span exports — without it, async exports silently drop:
+`defineWorkerFetch` instruments the handler **and** wires `ctx.waitUntil` for span exports. Without it, async exports silently drop:
 
 ```typescript
 import { defineWorkerFetch } from 'autotel-cloudflare';
@@ -182,7 +181,7 @@ export default defineWorkerFetch(
 );
 ```
 
-For broader use cases (`scheduled`, `queue`, `email` handlers, Durable Objects, Workflows), use `wrapModule` / `wrapDurableObject` / `instrumentWorkflow` — same auto-`waitUntil` semantics.
+For broader use cases (`scheduled`, `queue`, `email` handlers, Durable Objects, Workflows), use `wrapModule` / `wrapDurableObject` / `instrumentWorkflow`. Same auto-`waitUntil` semantics.
 
 ### AWS Lambda
 
@@ -245,16 +244,19 @@ Enrichers turn raw request data into standard, low-cardinality span attributes.
 | `requestSize(reqHeaders, resHeaders?)` | `http.request.body.size`, `http.response.body.size`                          | `content-length` headers        |
 
 ```typescript
+import { withTracing } from 'autotel';
 import { userAgent, geo, requestSize } from 'autotel/enrichers';
 
-export const handler = trace((ctx) => async (request: Request) => {
-  ctx.setAttributes({
-    ...userAgent(request.headers),
-    ...geo(request.headers),
-    ...requestSize(request.headers),
-  });
-  // ... handle request
-});
+export const handler = withTracing({ name: 'http.request' })(
+  (ctx) => async (request: Request) => {
+    ctx.setAttributes({
+      ...userAgent(request.headers),
+      ...geo(request.headers),
+      ...requestSize(request.headers),
+    });
+    // ... handle request
+  },
+);
 ```
 
 For your own derived fields on a request's wide event, build a reusable enricher with `defineEnricher` (from `autotel`) instead of scattering ad-hoc field writes. `compute` returns an object that is merged into the named `field`; return `undefined` to skip. Keep the output low-cardinality (bucket or hash high-cardinality values):
@@ -279,7 +281,7 @@ const enrichTier = defineEnricher<
 
 ## Backends (multi-vendor OTLP)
 
-Switch backends with **no code changes** — autotel speaks OTLP HTTP/JSON and HTTP/protobuf out of the box.
+Switch backends with **no code changes**. Autotel speaks OTLP HTTP/JSON and HTTP/protobuf out of the box.
 
 | Backend                          | Endpoint                                                   | Headers                               |
 | -------------------------------- | ---------------------------------------------------------- | ------------------------------------- |
@@ -334,7 +336,7 @@ const config: AttributeRedactorConfig = {
 init({ attributeRedactor: config });
 ```
 
-For free-text fields outside the span pipeline (logs, error messages, frontend payloads), use `createStringRedactor('default')` — same masks, returns a `(s: string) => string`.
+For free-text fields outside the span pipeline (logs, error messages, frontend payloads), use `createStringRedactor('default')`. Same masks, returns a `(s: string) => string`.
 
 ---
 
@@ -365,7 +367,7 @@ export const otelConfig = defineConfig({
 });
 ```
 
-Errors are isolated per item — one bad processor cannot break the others. See [references/processor-pipeline.md](references/processor-pipeline.md) for the full pipeline cookbook.
+Errors are isolated per item. One bad processor cannot break the others. See [references/processor-pipeline.md](references/processor-pipeline.md) for the full pipeline cookbook.
 
 ---
 
@@ -380,15 +382,15 @@ Errors are isolated per item — one bad processor cannot break the others. See
 | `BaggageSpanProcessor`         | Lift baggage entries onto every span                        |
 | `PrettyConsoleExporter`        | Hierarchical colourised output for local dev                |
 
-Compose them at build time with `composeSpanProcessors([...])` — no boilerplate.
+Compose them at build time with `composeSpanProcessors([...])`. No boilerplate.
 
 ---
 
 ## AI SDK integration (gen-ai semantic conventions)
 
-autotel implements the **OTel gen-ai semantic conventions** out of the box. Token usage, tool calls, model info, latency, cost — captured as standard attributes (`gen_ai.usage.input_tokens`, `gen_ai.tool.name`, `gen_ai.response.finish_reasons`, …) so any backend that understands OTel can render LLM telemetry without custom mapping.
+autotel implements the **OTel gen-ai semantic conventions** out of the box. Token usage, tool calls, model info, latency, cost. Captured as standard attributes (`gen_ai.usage.input_tokens`, `gen_ai.tool.name`, `gen_ai.response.finish_reasons`, …) so any backend that understands OTel can render LLM telemetry without custom mapping.
 
-> Node.js apps get the same canonical `gen_ai.*` conventions (plus cost, metric views, and agent governance) from the `autotel-genai` package — `traceGenAI` / `recordGenAiUsage` from `autotel-genai/trace` and `genAiMetricViews` from `autotel-genai/metrics`. `withAiTelemetry` below is the edge-runtime entry point.
+> Node.js apps get the same canonical `gen_ai.*` conventions (plus cost, metric views, and agent governance) from the `autotel-genai` package. `traceGenAI` / `recordGenAiUsage` from `autotel-genai/trace` and `genAiMetricViews` from `autotel-genai/metrics`. `withAiTelemetry` below is the edge-runtime entry point.
 
 ```typescript
 import { trace } from 'autotel';
@@ -423,7 +425,7 @@ Anti-patterns to detect:
 
 ## Structured errors
 
-Throw rich errors that carry status, audience, and remediation hints — and consume them at HTTP boundaries:
+Throw rich errors that carry status, audience, and remediation hints. And consume them at HTTP boundaries:
 
 ```typescript
 import { createStructuredError, parseError } from 'autotel';
@@ -492,21 +494,21 @@ pnpm --filter autotel run test:e2e
 
 ## Anti-patterns to detect
 
-| Anti-pattern                                        | Fix                                                                 |
-| --------------------------------------------------- | ------------------------------------------------------------------- |
-| `console.log` in handlers                           | Use `useLogger()` — fields land on the active span                  |
-| Manual `tracer.startSpan` boilerplate               | `trace(fn)` — auto-named, auto-ended, auto-status                   |
-| `try { … } catch (e) { console.error(e); throw e }` | Replace with `createStructuredError({ … })`                         |
-| `throw new Error('something went wrong')`           | `createStructuredError({ message, status, why, fix })`              |
-| Ad-hoc `span.setAttribute('user_id', id)`           | Use `useLogger().set({ user: { id } })` — flattens with stable keys |
-| Multiple exporters wired in parallel by hand        | `composeSpanProcessors([…])`                                        |
-| PII in attributes                                   | `attributeRedactor: 'default'` (on in prod by default)              |
-| Cloudflare Workers without `waitUntil`              | Use `defineWorkerFetch` / `wrapModule`                              |
-| High-cardinality span names (`/users/123`)          | `SpanNameNormalizingProcessor`                                      |
-| AI SDK token logs                                   | `withAiTelemetry()` + gen-ai semantic conventions                   |
-| Health checks blowing up trace volume               | `FilteringSpanProcessor`                                            |
-| No tests for instrumentation                        | `InMemorySpanExporter` + `autotel-vitest` matchers                  |
-| Manual context propagation in fetch                 | `instrumentation.instrumentGlobalFetch: true` (default)             |
+| Anti-pattern                                        | Fix                                                                |
+| --------------------------------------------------- | ------------------------------------------------------------------ |
+| `console.log` in handlers                           | Use `useLogger()`: fields land on the active span                  |
+| Manual `tracer.startSpan` boilerplate               | `trace(fn)`: auto-named, auto-ended, auto-status                   |
+| `try { … } catch (e) { console.error(e); throw e }` | Replace with `createStructuredError({ … })`                        |
+| `throw new Error('something went wrong')`           | `createStructuredError({ message, status, why, fix })`             |
+| Ad-hoc `span.setAttribute('user_id', id)`           | Use `useLogger().set({ user: { id } })`: flattens with stable keys |
+| Multiple exporters wired in parallel by hand        | `composeSpanProcessors([…])`                                       |
+| PII in attributes                                   | `attributeRedactor: 'default'` (on in prod by default)             |
+| Cloudflare Workers without `waitUntil`              | Use `defineWorkerFetch` / `wrapModule`                             |
+| High-cardinality span names (`/users/123`)          | `SpanNameNormalizingProcessor`                                     |
+| AI SDK token logs                                   | `withAiTelemetry()` + gen-ai semantic conventions                  |
+| Health checks blowing up trace volume               | `FilteringSpanProcessor`                                           |
+| No tests for instrumentation                        | `InMemorySpanExporter` + `autotel-vitest` matchers                 |
+| Manual context propagation in fetch                 | `instrumentation.instrumentGlobalFetch: true` (default)            |
 
 See [references/code-review.md](references/code-review.md) for the full checklist.
 
@@ -530,7 +532,7 @@ See [references/code-review.md](references/code-review.md) for the full checklis
 
 ## Loading reference files
 
-Load based on what you're working on — **do not load all at once**:
+Load based on what you're working on. **do not load all at once**:
 
 - Designing spans → [references/wide-spans.md](references/wide-spans.md)
 - Improving errors → [references/structured-errors.md](references/structured-errors.md)

package/skills/review-otel-patterns/references/code-review.md

@@ -7,7 +7,7 @@ Run through this list when adding observability to a new service or auditing an
 - [ ] **Service name set.** `service.name` resource attribute is unique per deployable unit (not just `"app"`).
 - [ ] **OTLP endpoint configured** via `OTLP_ENDPOINT` env var. Don't hard-code per-vendor URLs.
 - [ ] **No global SDK init in handlers.** Init runs once at module load (Next.js `instrumentation.ts`, Workers top of module, Node `--require`).
-- [ ] **Production redaction on.** `attributeRedactor: 'default'` (or `'strict'` / `'pci-dss'`) — autotel turns it on automatically when `NODE_ENV === 'production'`.
+- [ ] **Production redaction on.** `attributeRedactor: 'default'` (or `'strict'` / `'pci-dss'`): autotel turns it on automatically when `NODE_ENV === 'production'`.
 - [ ] **Sampling configured.** Don't ship 100% in production unless volume is genuinely tiny. `sampling.rates: { server: 25 }` is a reasonable starting point.
 
 ## Spans
@@ -31,8 +31,8 @@ Run through this list when adding observability to a new service or auditing an
 - [ ] **`useLogger().set({ … })` instead of `console.log`.** Logger fields land on the active span automatically.
 - [ ] **No PII in attributes** (or rely on redactor). Don't log raw email / cards / phones / JWTs.
 - [ ] **Group fields with objects.** `{ user: { id, plan } }`, not flat `userId` / `userPlan`.
-- [ ] **Decisions captured.** Which branch, which fallback, which feature flag — not just inputs.
-- [ ] **Background work uses `log.fork()`** — gets its own span and `_parentCorrelationId` for correlation.
+- [ ] **Decisions captured.** Which branch, which fallback, which feature flag: not just inputs.
+- [ ] **Background work uses `log.fork()`**: gets its own span and `_parentCorrelationId` for correlation.
 
 ## Errors
 
@@ -44,7 +44,7 @@ Run through this list when adding observability to a new service or auditing an
 ## Metrics
 
 - [ ] **Use OTel meter API**, not service-specific clients.
-- [ ] **Counters for events, histograms for durations, gauges for snapshots** — match the right type.
+- [ ] **Counters for events, histograms for durations, gauges for snapshots**: match the right type.
 - [ ] **Bounded label cardinality.** Don't put `userId` on a metric label.
 
 ## AI / LLM

package/skills/review-otel-patterns/references/processor-pipeline.md

@@ -89,7 +89,7 @@ const normalise = new SpanNameNormalizingProcessor({
 });
 ```
 
-Now `GET /users/123e4567-e89b-12d3-a456-426614174000/orders` becomes `GET /users/:id/orders` in your traces — fewer unique span names, dramatically faster queries.
+Now `GET /users/123e4567-e89b-12d3-a456-426614174000/orders` becomes `GET /users/:id/orders` in your traces. Fewer unique span names, dramatically faster queries.
 
 ## Lift baggage onto every span
 
@@ -103,7 +103,7 @@ spanProcessors: composeSpanProcessors([baggage, new BatchSpanProcessor(otlp)]);
 
 ## Subscribers for in-process side effects
 
-Subscribers run synchronously in the parent context — ideal for metrics, audit, and cost calculation that you want recorded **before** the span goes to the batcher.
+Subscribers run synchronously in the parent context. Ideal for metrics, audit, and cost calculation that you want recorded **before** the span goes to the batcher.
 
 ```typescript
 import type { EdgeSubscriber } from 'autotel-edge';
@@ -192,7 +192,7 @@ export const otelConfig = defineConfig({
 
 ## Error isolation
 
-Every compose helper catches errors per item and logs to `console.error` with the helper name. A single bad processor cannot break the others — important when one of your subscribers is a third-party integration (Datadog, PagerDuty, …) that can rate-limit or 502.
+Every compose helper catches errors per item and logs to `console.error` with the helper name. A single bad processor cannot break the others. Important when one of your subscribers is a third-party integration (Datadog, PagerDuty, …) that can rate-limit or 502.
 
 ## Choosing between subscribers and post-processors
 

package/skills/review-otel-patterns/references/structured-errors.md

@@ -98,5 +98,5 @@ app.onError((error, c) => {
 | `throw new Error('something went wrong')`                    | `createStructuredError({ message, status, why, fix })`                                 |
 | Putting support IDs in `message` (`"Failed for user 42"`)    | Use `internal: { userId: 42 }`                                                         |
 | Returning `details: { error: stack }` to clients             | Stack traces stay in `cause` / span; never serialise them out                          |
-| `console.error(e); throw e`                                  | Just throw — autotel's span will pick up the exception                                 |
+| `console.error(e); throw e`                                  | Just throw: autotel's span will pick up the exception                                  |
 | Two callers throwing different shapes for the same condition | Centralise: `function declined(reason: string) { throw createStructuredError({ … }) }` |

package/skills/review-otel-patterns/references/wide-spans.md

@@ -1,6 +1,6 @@
 # Designing wide spans
 
-A wide span is a single span per logical unit of work (request, job, message, fork) carrying _all_ the fields you'd ever want to filter or group by. autotel lets you build them with `useLogger().set({ … })` — fields are flattened to OTel attributes with stable dotted keys.
+A wide span is a single span per logical unit of work (request, job, message, fork) carrying _all_ the fields you'd ever want to filter or group by. autotel lets you build them with `useLogger().set({ … })`. Fields are flattened to OTel attributes with stable dotted keys.
 
 ## Anatomy
 
@@ -50,7 +50,7 @@ payment.authCode=auth_x
 2. **Group with objects.** `{ user: { id, plan } }` not `userId` / `userPlan`. The flatten step keeps the key shape stable.
 3. **Capture decisions, not just inputs.** Which branch ran, which promo applied, which fallback fired.
 4. **Keep cardinality bounded.** Don't put per-request UUIDs in `span.name`; use `SpanNameNormalizingProcessor`. Free-text labels go in attributes.
-5. **Avoid raw bodies.** Pick the shape: `{ user: { id, plan } }` — never `log.set({ user: requestBody })`.
+5. **Avoid raw bodies.** Pick the shape: `{ user: { id, plan } }`: never `log.set({ user: requestBody })`.
 6. **Trust the redactor.** PII you forgot to think about (emails, JWTs, cards) gets masked in production. See `attributeRedactor: 'default'`.
 
 ## When you need correlated child spans

package/skills/tune-sampling/SKILL.md

@@ -30,14 +30,14 @@ Total cost = (spans/sec × $/span) + (storage_GB × $/GB-month)
 Head sampling reduces this directly.
 ```
 
-Head sampling makes a decision **at span start** — fast, but coarse (it doesn't know if the span will fail).
-Tail sampling makes the decision **at span end** — slower, more storage upfront, but precise.
+Head sampling makes a decision **at span start**: fast but coarse, since it cannot know whether the span will fail.
+Tail sampling makes the decision **at span end**: slower and heavier on storage, but precise.
 
 The right mix:
 
 - **Head sample at the entry point** to keep volume tractable.
 - **Tail keep** the high-value subset (errors, slow, AI, debug-headered).
-- **Don't sample audit spans** — separate processor, see [`build-audit-trails`](../build-audit-trails/SKILL.md).
+- **Don't sample audit spans**: separate processor, see [`build-audit-trails`](../build-audit-trails/SKILL.md).
 
 ## Head sampling recipes
 
@@ -73,7 +73,7 @@ sampling: {
 
 ### Cloudflare Workers (per-colo budget)
 
-Workers run distributed — head sampling is your friend because there's no central queue:
+Workers run distributed. Head sampling is your friend because there's no central queue:
 
 ```typescript
 defineWorkerFetch(
@@ -85,7 +85,7 @@ defineWorkerFetch(
 );
 ```
 
-## Tail sampling — keep interesting traces
+## Tail sampling: keep interesting traces
 
 Tail sampling looks at the full trace (root span + children) before deciding. autotel ships `TailSamplingProcessor`:
 
@@ -138,9 +138,9 @@ spanProcessors: composeSpanProcessors([
 
 LLM calls produce 5–50 spans per request and are 100× more expensive than a typical handler call. Tradeoffs:
 
-- **Don't head-sample AI handlers below 50 %** — debugging "why did the model loop" requires the full chain.
-- **Always tail-keep AI traces** — the `gen_ai.*` attributes flag them.
-- **Cost-aware sampling** — keep all calls above a $ threshold:
+- **Don't head-sample AI handlers below 50 %**: debugging "why did the model loop" requires the full chain.
+- **Always tail-keep AI traces**: the `gen_ai.*` attributes flag them.
+- **Cost-aware sampling**: keep all calls above a $ threshold:
 
 ```typescript
 keep: (trace) => {
@@ -176,7 +176,79 @@ if (request.headers.get('x-debug-trace') === '1') {
 }
 ```
 
-Now any user can mark a request as "trace this fully" by sending the header — invaluable for reproducing customer reports.
+Now any user can mark a request as "trace this fully" by sending the header. Invaluable for reproducing customer reports.
+
+## Keeping the trace whole across services
+
+`RandomSampler` rolls the dice in each process. The API can keep a trace its
+worker drops, which leaves a waterfall with holes and no way to tell a dropped
+span from a fast one. `DeterministicSampler` hashes a key that travels with the
+request, so every service reaches the same verdict:
+
+```typescript
+import { DeterministicSampler } from 'autotel/sampling';
+import { trace } from '@opentelemetry/api';
+
+init({
+  service: 'checkout',
+  sampler: new DeterministicSampler({
+    sampleRate: 0.1,
+    key: () => trace.getActiveSpan()?.spanContext().traceId,
+  }),
+});
+```
+
+Give every service the same rate and the same key. Different rates break the
+agreement again.
+
+## Per-key target rates
+
+A single rate cannot fit skewed traffic. At 1 % your busiest endpoint still
+floods storage while the rare tenant whose failures you need disappears.
+`KeyTargetRateSampler` counts traffic per key over a rolling window and gives
+each key its own rate, so every key contributes about the same number of
+events:
+
+```typescript
+import { KeyTargetRateSampler } from 'autotel/sampling';
+
+new KeyTargetRateSampler({
+  key: (context) => context.operationName,
+  targetPerKey: 10, // ~10 events per key per window
+  windowMs: 30_000,
+  maxKeys: 1000, // keys past this share one overflow bucket
+});
+```
+
+The first window keeps everything, because no traffic history exists yet. Rates
+apply from the second window on.
+
+## Recording the rate
+
+Sampled counts lie unless you record what you discarded. A query over a 1 %
+sample reports a hundredth of your traffic, and the number looks plausible
+enough to act on.
+
+autotel writes `autotel.sampling.rate` on the span as "1 in N", so
+`COUNT * rate` estimates the population. It appears only when N exceeds 1, so
+fully captured spans stay clean. A custom sampler joins in by implementing
+`sampleRate()`:
+
+```typescript
+import type { Sampler } from 'autotel/sampling';
+
+class TenantSampler implements Sampler {
+  shouldSample(context) {
+    /* … */
+  }
+  sampleRate() {
+    return 20; // each kept event stands for 20
+  }
+}
+```
+
+Reach for `hashUnitInterval` from `autotel/sampling` when you need the same
+spread for your own keys.
 
 ## Sizing the rate
 
@@ -188,11 +260,11 @@ spans/sec ≈ requests/sec × spans_per_request × head_rate × tail_keep_rate
 
 Worked example for a 100 req/s API with 8 spans/req:
 
-| Head rate | Tail keep                        | Result                                       |
-| --------- | -------------------------------- | -------------------------------------------- |
-| 100 %     | 100 %                            | 800 spans/sec — expensive                    |
-| 10 %      | 100 % (errors + slow + AI ≈ 5 %) | ≈ 110 spans/sec — sweet spot                 |
-| 1 %       | 100 %                            | ≈ 18 spans/sec — too sparse for p99 alerting |
+| Head rate | Tail keep                        | Result                                      |
+| --------- | -------------------------------- | ------------------------------------------- |
+| 100 %     | 100 %                            | 800 spans/sec: expensive                    |
+| 10 %      | 100 % (errors + slow + AI ≈ 5 %) | ≈ 110 spans/sec: sweet spot                 |
+| 1 %       | 100 %                            | ≈ 18 spans/sec: too sparse for p99 alerting |
 
 For per-vendor pricing:
 
@@ -208,8 +280,11 @@ For per-vendor pricing:
 | 1 % sampling with no tail keep               | You'll miss every interesting failure                         |
 | Forgetting to tail-keep errors               | Sampled traces with errors → silent customer pain             |
 | Same rate for `server` and `internal`        | Internal sub-spans are 5–20× more numerous; sample harder     |
-| Ratio-based sampling on service entry point  | Use parent-based — children of a sampled trace stay together  |
+| Ratio-based sampling on service entry point  | Use parent-based: children of a sampled trace stay together   |
 | Head-sampling AI calls below 50 %            | Debugging tool loops requires the full chain                  |
 | Audit spans subject to sampling              | Route them to a separate processor (see `build-audit-trails`) |
 | Tail processor before exporter (loses spans) | Tail processor goes between head sampler and remote exporter  |
-| Rate-by-route hand-coded in handlers         | Use head sampler + tail keep — declarative, one place         |
+| Rate-by-route hand-coded in handlers         | Use head sampler + tail keep: declarative, one place          |
+| Counting sampled spans as the population     | Multiply by `autotel.sampling.rate`                           |
+| `RandomSampler` on a multi-service trace     | `DeterministicSampler` keyed on the trace id keeps it whole   |
+| One flat rate over skewed traffic            | `KeyTargetRateSampler` gives rare keys their own rate         |

package/dist/attribute-redacting-processor-DtTS9xxh.d.cts.map

@@ -1 +0,0 @@
-{"version":3,"file":"attribute-redacting-processor-DtTS9xxh.d.cts","names":[],"sources":["../src/attribute-redacting-processor.ts"],"mappings":";;;;;;;KAsCY,mBAAA,IACV,GAAA,UACA,KAAA,EAAO,cAAA,KACJ,cAAc;;AAuBJ;AAMf;KAxBY,uBAAA;;;AAwBiD;KAnBjD,MAAA,IAAU,KAAa;;;;UAKlB,kBAAA;EA8BM;EA5BrB,IAAA;EAqCW;EAnCX,OAAA,EAAS,MAAA;EAmCqB;EAjC9B,WAAA;EAec;EAbd,IAAA,GAAO,MAAM;AAAA;;;;KAMH,kBAAA,gBAAkC,eAAe;;;;UAK5C,uBAAA;EAoBe;EAlB9B,WAAA,GAAc,MAAA;EAwBC;EArBf,aAAA,GAAgB,kBAAA;;EAGhB,KAAA;EAmBA;EAhBA,QAAA,aAAqB,kBAAA;EAgBe;EAbpC,QAAA,GAAW,MAAA;EAagD;EAV3D,WAAA;EA6BQ;EA1BR,QAAA,GAAW,mBAAA;AAAA;;;;UAMI,kCAAA;EACf,QAAA,EAAU,uBAAA,GAA0B,uBAAuB;AAAA;;;;cAMhD,iBAAA;EAAA;;;;;;;;;;;;;cAmBA,eAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAoHA,gBAAA,EAAkB,MAAA,CAC7B,uBAAA,EACA,uBAAA;AAvDkB;AAqDpB;;;AArDoB,iBAsGJ,gCAAA,CACd,GAAA,EAAK,uBAAA,GAA0B,uBAAA,aAC9B,uBAAA,GAA0B,uBAAA;;;;;;;iBA4NpB,kBAAA,CACP,IAAA,EAAM,YAAA,EACN,QAAA,EAAU,mBAAA,GACT,YAAA;;AAhRsB;AA+CzB;;;;;;;;;;;iBAwQgB,uBAAA,CACd,MAAA,EAAQ,uBAAA,GAA0B,uBAAA,GACjC,mBAAA;;;;AAxQiD;AAsDnD;;;;;;;;cAkOY,2BAAA,YAAuC,aAAA;EAAA,iBACjC,gBAAA;EAAA,iBACA,QAAA;cAGf,gBAAA,EAAkB,aAAA,EAClB,OAAA,EAAS,kCAAA;EA/DV;;AAAY;EAyEb,OAAA,CAAQ,IAAA,EAAM,IAAA,EAAM,aAAA,EAAe,OAAA;EAlCE;;;EAyCrC,KAAA,CAAM,IAAA,EAAM,YAAA;EAWZ,UAAA,IAAc,OAAA;EAId,QAAA,IAAY,OAAA;AAAA"}

package/dist/attribute-redacting-processor-DtTS9xxh.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"attribute-redacting-processor-DtTS9xxh.d.ts","names":[],"sources":["../src/attribute-redacting-processor.ts"],"mappings":";;;;;;;KAsCY,mBAAA,IACV,GAAA,UACA,KAAA,EAAO,cAAA,KACJ,cAAc;;AAuBJ;AAMf;KAxBY,uBAAA;;;AAwBiD;KAnBjD,MAAA,IAAU,KAAa;;;;UAKlB,kBAAA;EA8BM;EA5BrB,IAAA;EAqCW;EAnCX,OAAA,EAAS,MAAA;EAmCqB;EAjC9B,WAAA;EAec;EAbd,IAAA,GAAO,MAAM;AAAA;;;;KAMH,kBAAA,gBAAkC,eAAe;;;;UAK5C,uBAAA;EAoBe;EAlB9B,WAAA,GAAc,MAAA;EAwBC;EArBf,aAAA,GAAgB,kBAAA;;EAGhB,KAAA;EAmBA;EAhBA,QAAA,aAAqB,kBAAA;EAgBe;EAbpC,QAAA,GAAW,MAAA;EAagD;EAV3D,WAAA;EA6BQ;EA1BR,QAAA,GAAW,mBAAA;AAAA;;;;UAMI,kCAAA;EACf,QAAA,EAAU,uBAAA,GAA0B,uBAAuB;AAAA;;;;cAMhD,iBAAA;EAAA;;;;;;;;;;;;;cAmBA,eAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAoHA,gBAAA,EAAkB,MAAA,CAC7B,uBAAA,EACA,uBAAA;AAvDkB;AAqDpB;;;AArDoB,iBAsGJ,gCAAA,CACd,GAAA,EAAK,uBAAA,GAA0B,uBAAA,aAC9B,uBAAA,GAA0B,uBAAA;;;;;;;iBA4NpB,kBAAA,CACP,IAAA,EAAM,YAAA,EACN,QAAA,EAAU,mBAAA,GACT,YAAA;;AAhRsB;AA+CzB;;;;;;;;;;;iBAwQgB,uBAAA,CACd,MAAA,EAAQ,uBAAA,GAA0B,uBAAA,GACjC,mBAAA;;;;AAxQiD;AAsDnD;;;;;;;;cAkOY,2BAAA,YAAuC,aAAA;EAAA,iBACjC,gBAAA;EAAA,iBACA,QAAA;cAGf,gBAAA,EAAkB,aAAA,EAClB,OAAA,EAAS,kCAAA;EA/DV;;AAAY;EAyEb,OAAA,CAAQ,IAAA,EAAM,IAAA,EAAM,aAAA,EAAe,OAAA;EAlCE;;;EAyCrC,KAAA,CAAM,IAAA,EAAM,YAAA;EAWZ,UAAA,IAAc,OAAA;EAId,QAAA,IAAY,OAAA;AAAA"}

package/dist/canonical-log-line-processor-BcRuAdRk.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"canonical-log-line-processor-BcRuAdRk.d.ts","names":[],"sources":["../src/processors/canonical-log-line-processor.ts"],"mappings":";;;;;AA6Ce;AAGf;;AAHe,KATH,mBAAA,IACV,GAAA,UACA,KAAA,EAAO,cAAA,KACJ,cAAc;AAAA,UAEF,qBAAA;EACf,IAAA,EAAM,YAAA;EACN,KAAA;EACA,OAAA;EACA,KAAA,EAAO,MAAM;AAAA;AAAA,UAGE,aAAA;EASuB;EAPtC,MAAA;EASS;EAPT,UAAA;EAqBoB;EAnBpB,IAAA;AAAA;AAAA,UAGe,uBAAA;EA4BgC;EA1B/C,MAAA,GAAS,MAAA;EA4BiD;EA1B1D,aAAA;EAFA;EAIA,QAAA;EAFA;EAIA,aAAA,IAAiB,IAAA,EAAM,YAAA;EAAvB;EAEA,yBAAA;EAFiB;;;;;EAQjB,iBAAA,GAAoB,mBAAA;EAEN;EAAd,UAAA,IAAc,GAAA,EAAK,qBAAA;EAQZ;;;;;;;EAAP,IAAA,GAAO,aAAA;EAIyB;EAFhC,KAAA,IAAS,GAAA,EAAK,qBAAA,YAAiC,OAAA;EAOzC;EALN,YAAA,IAAgB,KAAA,WAAgB,GAAA,EAAK,qBAAA;EAiE1B;;;;EA5DX,MAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4SyB;;;;;;;;;;;;;;;;;;;;cAhPd,yBAAA,YAAqC,aAAA;EAAA,QACxC,MAAA;EAAA,QACA,aAAA;EAAA,QACA,QAAA;EAAA,QACA,aAAA;EAAA,QACA,yBAAA;EAAA,QACA,iBAAA;EAAA,QACA,UAAA;EAAA,QACA,KAAA;EAAA,QACA,YAAA;EAAA,QACA,MAAA;EAAA,QACA,aAAA;cAGI,OAAA,GAAS,uBAAA;EAAA,QAsBb,kBAAA;EA8BR,OAAA;EAIA,KAAA,CAAM,IAAA,EAAM,YAAA;EAAA,QA+CJ,qBAAA;EAAA,QA+BA,gBAAA;EAAA,QAcA,aAAA;EAAA,QAQA,WAAA;EAAA,QA0BA,WAAA;EAAA,QAeA,SAAA;EAAA,QAKA,iBAAA;EAAA,QAUA,qBAAA;EAUF,UAAA,IAAc,OAAA;EAId,QAAA,IAAY,OAAA;AAAA"}