@rootcat/node 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+## 0.2.0
+
+**Alongside another tracer.** An application whose tracer owns the
+process's OpenTelemetry setup (Sentry, tested with 8.55, 9.47 and 10.51;
+an application's own `NodeSDK`) starts Rootcat after it with
+`startAlongside()` from `@rootcat/node/attach`, and gives a tracer that
+records spans the processors from `rootcatSpanProcessors()`; see
+"Alongside another tracer" in the README. Modes: `own`, `beside`,
+`inside`.
+
+- Sentry for errors only (no `tracesSampleRate`): the package runs its
+  own provider beside Sentry's, never registered globally, under Sentry's
+  context manager. Its spans are recorded without the sampled flag, so
+  the headers Sentry propagates and the error events it sends make the
+  same sampling statement as before. Sentry receives no transaction and
+  no span it did not receive before; its error events now carry the
+  Rootcat trace id, linking an error to its trace. Outgoing requests
+  carry Sentry's headers byte for byte as before, made before, during or
+  after the response. One client report is no longer sent:
+  the one counting an outgoing request's span Sentry skipped for want of
+  a parent, which now has one. A Hono route that `@sentry/hono` names
+  becomes the server span's `http.route`.
+- Sentry with tracing: `Sentry.init({ openTelemetrySpanProcessors:
+  rootcatSpanProcessors() })` puts the package's processor in Sentry's
+  provider. It exports a copy of every span Sentry records, with its
+  call site and the privacy rules, and leaves Sentry's spans as they
+  are. The package adds no span of its own; its Drizzle, pg pool and
+  postgres.js entry wrappers carry call sites to Sentry's query spans.
+- Nothing global is registered before `Sentry.init` in an application
+  that depends on a Sentry server SDK (listed in `package.json`, or
+  installed when there is none): loaded before it (the import line,
+  `NODE_OPTIONS`) the package starts nothing; `startAlongside()` above it
+  starts beside Sentry at once and settles a tick later: beside, or
+  inside a tracing Sentry with nothing of its own left on `node:http`, or
+  stopped (handlers removed, loader hook idle, processors inert). One
+  line on stderr either way.
+- Whether Sentry traces is read by its own rule per major version (8:
+  a `tracesSampleRate` key with no value is tracing on). Beside another
+  SDK, no wrapper of it is removed or wrapped over (Sentry 8's
+  `node:http`). The package patches `http` and `https` through the
+  CommonJS hook itself, so server spans are recorded with Sentry's and
+  the package's import-in-the-middle copies apart (pnpm). Its loader
+  hook takes over postgres.js's entry and Drizzle's query classes from
+  a hook that wraps every module (Sentry 8's).
+- Beside Sentry, outgoing `fetch` and `http` requests carry Sentry's
+  headers once, with the baggage they had without the package; the
+  package's spans below another SDK's unrecorded span (Next.js under
+  `@sentry/nextjs`) are kept.
+- Inside a tracing Sentry, the copies the package exports are cut to
+  what its own spans would hold: span names that are paths or URLs
+  masked, Redis statements reduced to the command, `cache.key` and
+  headers dropped, `url.fragment` emptied. The pg pool wrapper leaves
+  `connect` to Sentry, and a wrapper of the package never unwraps another
+  SDK's.
+- A registered provider is recognised in the same copy of
+  `@opentelemetry/api` as well; before, only one from another copy was.
+
+**Other changes.**
+
+- postgres.js: the driver's own queries on a new connection (the array
+  type lookup, the read-only check) are no longer traced; they showed as
+  a second span, with the call site, for the query that opened the
+  connection.
+- ioredis and redis: a command is traced only inside a traced operation.
+  A queue such as BullMQ polls Redis all the time outside any, which was
+  a trace per poll.
+- Request and response header attributes and Sentry's `sentry.*` keys
+  are never exported; `http.query` and `db.connection_string` are
+  emptied like `url.query`.
+- The ES module loader hook is an import-in-the-middle instance of the
+  package's own, never a second registration of the `hook.mjs` another
+  SDK registered (with one copy installed for both, that replaced the
+  other's list of modules to wrap); it wraps only postgres.js's entry file
+  and Drizzle's two query classes of those ES module packages (all of
+  their files before), and neither hook warns about the other.
+
+## 0.1.0
+
+First release: the import line, `--require`/`--import` entries, the
+curated instrumentations, the call-site processor, OTLP/HTTP protobuf
+to the host agent.

package/README.md

@@ -74,10 +74,74 @@ bridge network, should set `ROOTCAT_OTLP_URL=http://127.0.0.1:4318`.
 `ROOTCAT_OTLP_URL` overrides discovery. The service name is `ROOTCAT_SERVICE`,
 else `OTEL_SERVICE_NAME`, else the `name` of the nearest `package.json`.
 
-If another OpenTelemetry SDK is already registered in the process (Sentry
-8 and later, an app's own `NodeSDK`), the package prints one line and
-does not start. If it starts first, the other SDK's registration fails
-instead; load one of them.
+**Alongside another tracer** (Sentry, tested with 8.55, 9.47 and 10.51;
+an app's own `NodeSDK`), the package starts after it: see Alongside
+another tracer below.
+
+## Alongside another tracer
+
+The package works alongside a tracer that owns the process's
+OpenTelemetry setup (its tracer provider, the context manager, the
+propagator): it starts after that tracer and takes none of them. Sentry 8
+and later is the worked example. In the file that initialises Sentry:
+
+```ts
+// src/instrument.ts (node --import ./dist/instrument.js ./dist/index.js)
+import { startAlongside } from '@rootcat/node/attach';
+import { initializeSentry } from './lib/sentry';
+
+initializeSentry(); // Sentry.init({ ... })
+startAlongside();
+```
+
+With Sentry tracing on (`tracesSampleRate` or `tracesSampler`), also give
+`Sentry.init` the package's processor:
+
+```ts
+import { rootcatSpanProcessors } from '@rootcat/node/attach';
+
+Sentry.init({ ...options, openTelemetrySpanProcessors: rootcatSpanProcessors() });
+```
+
+- **Sentry for errors only**: the package runs its own provider beside
+  Sentry's, unregistered, with the curated instrumentations. Sentry sends
+  what it sent before: no transaction, no span, the same error events
+  with their request scope and `beforeSend`; each error event now carries
+  the Rootcat trace id of its request. Outgoing requests carry
+  `sentry-trace` and `baggage` byte for byte as without Rootcat (ids
+  aside), whether made before, during or after the response, so
+  downstream Sentry quotas and a payment provider's callbacks see what
+  they saw. The one item not sent is a client report of a span
+  Sentry skipped for want of a parent, which now has one. With
+  `@sentry/hono` the server span gets the route (`http.route`).
+- **Sentry with tracing**: Sentry instruments the libraries; the package
+  adds no span and exports a copy of each span Sentry records, with its
+  call site, without changing what Sentry sends, cut to what the
+  package's own spans would hold (no headers, masked paths in span names,
+  Redis commands without keys). Sentry's sample rate decides which traces
+  exist; a query outside a request (a queue job) has no Sentry span, so
+  none here either.
+- Nothing global is registered before `Sentry.init`: that would take the
+  context manager from Sentry and break its request isolation. Loaded
+  before it (the import line first, or `NODE_OPTIONS`), the package starts
+  nothing and says so in one line. `startAlongside()` above `Sentry.init`
+  starts beside Sentry at once and settles a tick later (stays beside,
+  goes inside a tracing Sentry leaving nothing of its own on `node:http`,
+  or stops, leaving nothing running), one line on stderr; the ES
+  module drivers may go untraced in that order, so call it after
+  `Sentry.init`.
+- Trace context crosses services in Sentry's headers (`sentry-trace`,
+  `baggage`); Sentry's propagator does not read a W3C `traceparent`.
+
+With an application's own `NodeSDK`, pass `rootcatSpanProcessors()` in
+its `spanProcessors` and call `startAlongside()` after `sdk.start()`.
+Tested with `@sentry/hono` 10.51 (npm, and a pnpm deployment as the
+owner's API ships) and `@sentry/node` 8.55 and 9.47; expected to work
+with the other Sentry server SDKs of those versions and any
+OpenTelemetry SDK whose provider takes span processors; not with one whose provider does not (`dd-trace`), where the
+package does not start and says so. The cost per request beside and
+inside Sentry: see Cost. Details, and why not `skipOpenTelemetrySetup`:
+"Alongside another tracer" in `docs/v4-node-package.md`.
 
 ## What is traced
 
@@ -86,11 +150,11 @@ instead; load one of them.
 | `http`, `https` | server and client requests | client requests | through Next.js |
 | `fetch`, `undici` | client requests | yes | no |
 | `pg` | one span per query; cursors and streams (`pg-cursor`, `pg-query-stream`) are not traced | yes, through the pool as well | yes |
-| `postgres` (postgres.js) | one span per query | tagged templates, and queries made through Drizzle | yes |
+| `postgres` (postgres.js) | one span per query (not the driver's own queries on a new connection) | tagged templates, and queries made through Drizzle | yes |
 | `drizzle-orm` | the driver spans below it | yes, from where the query was built | yes, over `pg` and postgres.js |
 | `mysql2` | queries | yes | no |
 | `mongodb` | commands | yes | no |
-| `ioredis`, `redis` | commands | yes | no |
+| `ioredis`, `redis` | commands inside a traced operation (a queue's polling outside one is not traced) | yes | with Sentry, through BullMQ |
 | `@prisma/client` | when the app installs `@prisma/instrumentation` | the operation's | no |
 
 Every client span carries `code.filepath`, `code.lineno` and
@@ -116,7 +180,8 @@ letters, hyphens and underscores up to 32 bytes (not a mixed-case run of
 twelve or more) or a version such as `v1`, so a username or slug made of
 letters (`/u/kelvin`) is sent, and numbers, UUIDs, tokens, emails and file
 names are not. Client addresses and user agents. Request
-and response bodies and headers. Environment variables and command lines.
+and response bodies and headers (header attributes another SDK such as
+Sentry records are dropped). Connection strings. Environment variables and command lines.
 A database server's error message (only the error class and SQLSTATE
 travel). A recorded exception's stack trace is sent as frames only.
 
@@ -160,6 +225,22 @@ Loading the package adds 0.3 to 0.4 s to the start of a process, about
 half of it the module loader hook (every module load waits on its
 thread).
 
+Per request (`npm run bench:sentry`: a Hono route running one Drizzle
+query, 2000 sequential requests after a warm-up, medians of six rounds;
+ranges over three runs, which differ by up to a third on this machine):
+
+| Setup | Server CPU added per request |
+|---|---|
+| Rootcat on its own (no Sentry) | +990 µs (+76 %) |
+| Rootcat beside an errors-only Sentry | +1005 to +1220 µs (+65 to +88 %) |
+| Rootcat inside a Sentry that traces every request | +235 to +535 µs (+5 to +15 %) |
+
+The HTTP server span is the largest piece of a request's cost; budget
+about 1 ms per request and 0.2 ms per query. Beside Sentry, about
+0.2 ms of it is Sentry's context manager, which clones a scope at every
+context switch. Turning Sentry's own tracing on costs more (+2.9 ms on
+the same route).
+
 ## When the agent is not there
 
 Spans are batched (every 10 s, up to 512 per export, 4096 queued; past

package/dist/attach.d.ts

@@ -0,0 +1 @@
+export { rootcatSpanProcessors, startAlongside, type Mode, type Started, type StartOptions } from './sdk.js';

package/dist/attach.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startAlongside = exports.rootcatSpanProcessors = void 0;
+// @rootcat/node/attach: Rootcat in an application where another tracer
+// owns the process's OpenTelemetry setup (Sentry 8 and later, an app's
+// own NodeSDK). In the file that sets that tracer up, after it:
+//
+//   import { startAlongside } from "@rootcat/node/attach";
+//   Sentry.init({ ... });
+//   startAlongside();
+//
+// When that tracer records spans (Sentry with tracesSampleRate or
+// tracesSampler, a NodeSDK), its provider also takes the package's
+// processor:
+//
+//   import { rootcatSpanProcessors, startAlongside } from "@rootcat/node/attach";
+//   Sentry.init({ ..., openTelemetrySpanProcessors: rootcatSpanProcessors() });
+//   startAlongside();
+//
+// See coexist.ts for what each case does.
+var sdk_js_1 = require("./sdk.js");
+Object.defineProperty(exports, "rootcatSpanProcessors", { enumerable: true, get: function () { return sdk_js_1.rootcatSpanProcessors; } });
+Object.defineProperty(exports, "startAlongside", { enumerable: true, get: function () { return sdk_js_1.startAlongside; } });
+//# sourceMappingURL=attach.js.map

package/dist/attach.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.js","sourceRoot":"","sources":["../src/attach.ts"],"names":[],"mappings":";;;AAAA,uEAAuE;AACvE,uEAAuE;AACvE,gEAAgE;AAChE,EAAE;AACF,2DAA2D;AAC3D,0BAA0B;AAC1B,sBAAsB;AACtB,EAAE;AACF,kEAAkE;AAClE,mEAAmE;AACnE,aAAa;AACb,EAAE;AACF,kFAAkF;AAClF,gFAAgF;AAChF,sBAAsB;AACtB,EAAE;AACF,0CAA0C;AAC1C,mCAA6G;AAApG,+GAAA,qBAAqB,OAAA;AAAE,wGAAA,cAAc,OAAA"}

package/dist/coexist.d.ts

@@ -0,0 +1,183 @@
+import { type Context } from '@opentelemetry/api';
+import type { Resource } from '@opentelemetry/resources';
+import type { ReadableSpan, Span, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { type CallSiteProcessor } from './processor.js';
+/**
+ * ExistingSetup is what the package can tell about another tracer in the
+ * process. kind is 'sentry' when its options can be read (Sentry keeps its
+ * client on globalThis), 'other' when a provider is registered by an SDK
+ * whose options cannot be read.
+ */
+export interface ExistingSetup {
+    kind: 'sentry' | 'other';
+    /** registered says a tracer provider is registered globally. */
+    registered: boolean;
+    /** tracing says the owner records spans (Sentry: tracesSampleRate or tracesSampler; another SDK: assumed). */
+    tracing: boolean;
+    /** debug says the owner runs the OpenTelemetry diagnostic logger (Sentry's debug option). */
+    debug: boolean;
+    /**
+     * processors says whether the owner was given rootcatSpanProcessors():
+     * read from Sentry's options, unknown (undefined) for another SDK.
+     */
+    processors: boolean | undefined;
+}
+/**
+ * existingSetup describes the tracer that owns the process's
+ * OpenTelemetry setup, or undefined when there is none: no provider is
+ * registered and no Sentry client exists.
+ */
+export declare function existingSetup(): ExistingSetup | undefined;
+type OwnerOptions = {
+    tracesSampleRate?: unknown;
+    tracesSampler?: unknown;
+    enableTracing?: unknown;
+    debug?: unknown;
+    openTelemetrySpanProcessors?: unknown;
+};
+/**
+ * tracesByVersion is Sentry's own rule for whether it records spans, by its
+ * major version, so the package never runs beside a Sentry that installed
+ * its performance instrumentations:
+ * - 8: hasTracingEnabled, enableTracing or a tracesSampleRate or
+ *   tracesSampler key present, whatever its value (undefined included);
+ * - 9 and later: hasSpansEnabled, tracesSampleRate not null or undefined,
+ *   or a tracesSampler (enableTracing was removed in 9).
+ * An unknown version is taken as tracing: inside mode, which adds no
+ * instrumentation of the package's own, rather than beside a Sentry that
+ * might have installed its own.
+ */
+export declare function tracesByVersion(options: OwnerOptions, version: string): boolean;
+/**
+ * providerRegistered reports whether a tracer provider is registered
+ * globally (by another SDK). The API's global is a proxy whose delegate
+ * is the registered provider, or the no-op one; a proxy from another
+ * copy of the API answers the same way.
+ */
+export declare function providerRegistered(): boolean;
+/**
+ * tracerDependency names the package of a tracer the application
+ * initialises later (laterTracer) that it depends on: the one the nearest
+ * package.json above cwd lists (at most eight
+ * levels, 64 KiB), else, when no readable package.json lists the
+ * application's dependencies (an image of a bundle and its node_modules),
+ * a Sentry SDK installed in a node_modules on the way up. undefined when
+ * neither.
+ */
+export declare function tracerDependency(cwd: string): string | undefined;
+/**
+ * UrlSource marks the package's spans beside a Sentry that traces
+ * nothing as named after a URL (sentry.source "url"), and keeps them so:
+ * Sentry writes the name of a span with any other source into the
+ * dynamic sampling context it propagates (sentry-transaction in baggage)
+ * and sends with error events. @sentry/hono names the route on the active
+ * span as the response goes out (source "route"), so a call made after
+ * the response (a payment callback fired in the background) would carry
+ * the route; a source another SDK sets is kept aside instead
+ * (rootcat.source, read by routeFromHost for http.route). Neither key is
+ * exported. Outgoing requests and error events then carry the dynamic
+ * sampling context they carried without the package, before, during and
+ * after the response.
+ */
+export declare class UrlSource implements SpanProcessor {
+    onStart(span: Span): void;
+    onEnd(): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/** keptSourceKey holds the source another SDK set on a pinned span. */
+export declare const keptSourceKey = "rootcat.source";
+type UndiciRequest = {
+    headers?: unknown;
+    addHeader?: (name: string, value: string) => unknown;
+};
+/** hasHeader reports whether an undici request already carries a header. */
+export declare function hasHeader(request: UndiciRequest, name: string): boolean;
+/**
+ * propagatedOnce makes an undici instrumentation leave a request's
+ * headers alone when Sentry's fetch instrumentation has already propagated
+ * (it subscribes to the same channel first, and from the same active
+ * span): the instrumentation would otherwise add a second sentry-trace
+ * and baggage, which a downstream service reads as one comma-joined
+ * value. The span still starts. The instrumentation subscribed to its
+ * channels when it was created; it is disabled and enabled again around
+ * the change, so the subscriptions take the new handler.
+ */
+export declare function propagatedOnce<T extends object>(instrumentation: T): T;
+/**
+ * FlaggedExport hands the spans the package records beside Sentry
+ * (recorded, not flagged sampled; see RecordOnlySampler) to an exporting
+ * processor as sampled views, which the batch processor exports.
+ */
+export declare class FlaggedExport implements SpanProcessor {
+    private readonly inner;
+    constructor(inner: SpanProcessor);
+    onStart(span: Span, parentContext: Context): void;
+    onEnd(span: ReadableSpan): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/**
+ * InProviderProcessor is the one processor the package puts in Sentry's
+ * provider: the read-only call-site processor, and a copy of each span
+ * Sentry records (and ROOTCAT_SAMPLE keeps) to the exporting processors,
+ * under the package's resource. Sentry's spans are never changed.
+ */
+export declare class InProviderProcessor implements SpanProcessor {
+    readonly callSites: CallSiteProcessor;
+    private readonly exporting;
+    private readonly resource;
+    private readonly ratio;
+    constructor(callSites: CallSiteProcessor, exporting: SpanProcessor[], resource: Resource, ratio: number);
+    /** stopped is set by stop(): the processor then does nothing. */
+    private stopped;
+    /**
+     * stop makes the processor inert and flushes what it holds: the
+     * package stopped (startAlongside() found no tracer to run alongside)
+     * after this processor was given to a provider.
+     */
+    stop(): void;
+    onStart(span: Span, parentContext: Context): void;
+    onEnd(span: ReadableSpan): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/**
+ * keeps applies ROOTCAT_SAMPLE to a trace Sentry records: the same share
+ * of trace ids the OpenTelemetry ratio sampler keeps, so every span of a
+ * trace gets the same answer.
+ */
+export declare function keeps(traceId: string, ratio: number): boolean;
+/**
+ * activeDatabaseSpan is the active span when it is a recorded database
+ * span (the one Sentry's postgres.js instrumentation starts just before the
+ * query is handled), the span a postgres.js origin belongs to; anything
+ * else (a server span, when Sentry skipped the query for want of a
+ * parent) is not given the query's site.
+ */
+export declare function activeDatabaseSpan(): object | undefined;
+/**
+ * guardWrappers keeps an instrumentation's hands off another SDK's
+ * wrappers. Upstream instrumentations unwrap whatever wrapper they find
+ * on a method before wrapping it (meant for their own second enable),
+ * which would remove another SDK's: Sentry 8's http instrumentation,
+ * behind its request isolation, for one. With the guard the
+ * instrumentation only ever unwraps the package's own wrappers, and
+ * marks its wrappers as the package's. With keepForeign (beside another
+ * SDK) it also leaves alone a method another SDK already wrapped: that
+ * SDK's instrumentation stays the only one, and the package records no
+ * span there.
+ */
+export declare function guardWrappers<T extends object>(instrumentation: T, keepForeign: boolean): T;
+/**
+ * sentryLoaderShared reports whether the application's Sentry and the
+ * package load one import-in-the-middle copy (npm dedupes them; pnpm
+ * keeps a copy each). Unknown counts as not shared. It decides how much
+ * the package's loader hook may wrap before Sentry.init: registered first,
+ * that hook sits inside Sentry's, and a module it marks for itself is
+ * then wrapped through its copy alone, so with copies apart Sentry's own
+ * instrumentation of that module (postgres.js, pg, with tracing on) would
+ * never run.
+ */
+export declare function sentryLoaderShared(cwd: string): boolean;
+export {};