feat: add adaptive sampling to node sdk

[jy-tan]

Summary

Add the Node half of adaptive sampling so the SDK can shed root-request recording load locally based on queue, exporter, event-loop, and memory pressure signals while preserving whole-trace semantics and pre-app-start capture.

This keeps admission decisions local to the SDK process and defers backend-driven rarity sampling in favor of app and exporter protection.

Changes

• Parse recording.sampling.mode, base_rate, and min_rate while keeping legacy recording.sampling_rate behavior and supporting TUSK_SAMPLING_RATE as a compatibility alias alongside canonical TUSK_RECORDING_SAMPLING_RATE
• Add AdaptiveSamplingController and wire it into TuskDrift with periodic health updates driven by queue fill, dropped spans, export failures/timeouts, event-loop lag, and memory pressure
• Replace the opaque batching path with a Drift-owned DriftBatchSpanProcessor so queue health, dropped spans, and export failures are first-class control signals for load shedding
• Add exporter retry and circuit-breaker resilience in the API span adapter and surface exporter health through TdSpanExporter
• Gate inbound HTTP and Next.js root requests through adaptive admission and run sampled-out requests under explicit no-record context propagation
• Preserve pre-app-start capture for the first inbound HTTP request before auto-marking the app ready
• Update the Node docs for adaptive sampling configuration and add focused tests for controller behavior, env-var precedence, batch-processor health, and HTTP pre-app-start admission

[cubic-dev-ai]

5 issues found across 18 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/core/tracing/adapters/ApiSpanAdapter.ts">

<violation number="1" location="src/core/tracing/adapters/ApiSpanAdapter.ts:233">
P2: Timeout failures are not counted because the abort check only matches `AbortError`, while this code aborts with `new Error(...)` as the reason.</violation>
</file>

<file name="docs/nextjs-initialization.md">

<violation number="1" location="docs/nextjs-initialization.md:207">
P2: The startup note overstates pre-ready capture semantics. It says all requests before `markAppAsReady()` are always recorded, but this feature is described as preserving only the first inbound pre-app-start request.</violation>
</file>

<file name="src/core/tracing/TdSpanExporter.ts">

<violation number="1" location="src/core/tracing/TdSpanExporter.ts:102">
P2: Preserve `null` when no export latency has been observed instead of coercing it to `0` during aggregation.</violation>
</file>

<file name="src/core/sampling/AdaptiveSamplingController.ts">

<violation number="1" location="src/core/sampling/AdaptiveSamplingController.ts:205">
P2: When adaptive load shedding drives `effectiveRate` to exactly 0 (hot/warm state with `minRate = 0`), the reason is misreported as `"not_sampled"` instead of `"load_shed"`. This breaks observability: operators cannot distinguish "configured rate is zero" from "adaptive controller suppressed all traffic".</violation>
</file>

<file name="src/core/tracing/DriftBatchSpanProcessor.ts">

<violation number="1" location="src/core/tracing/DriftBatchSpanProcessor.ts:51">
P2: `void this.flushOneBatch()` discards the returned promise. If the exporter throws synchronously inside `export()`, the resulting rejection is unhandled and can crash the process. Add a `.catch()` at these fire-and-forget call sites, or wrap the `this.exporter.export(...)` call in a try/catch that calls `resolve()`.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}