@rootcat/node 0.0.0-stage → 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/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Kelvin Guchu
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,295 @@
-# Temporary Holding Version
+# @rootcat/node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Tracing for Node services that report to the Rootcat host agent, with the
+line of application code behind every database and HTTP client call.
+Loading the package starts an OpenTelemetry tracer with a curated set of
+instrumentations and posts the spans to the agent's OTLP intake on the
+same host. It talks to the host agent and to nothing else; it needs no
+token.
+
+## Enable
+
+**Next.js** (the recommended setup): add `instrumentation.ts` beside
+`next.config.js`. Next loads it before the application, in every server
+it starts, including the standalone output:
+
+```ts
+// instrumentation.ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') await import('@rootcat/node');
+}
+```
+
+With `output: 'standalone'`, keep the package and the drivers out of the
+server bundles (a bundled driver cannot be patched):
+
+```js
+// next.config.js
+module.exports = {
+  output: 'standalone',
+  serverExternalPackages: ['@rootcat/node', 'postgres', 'drizzle-orm'],
+  experimental: { serverSourceMaps: true },
+};
+```
+
+**CommonJS apps** (Express, Fastify, a worker): one line, first in the
+entry file, before anything else is required:
+
+```js
+require('@rootcat/node');
+```
+
+**ES module apps** (`"type": "module"`): an entry of two files, so the
+application's imports are resolved after the package is loaded:
+
+```js
+// main.mjs
+import '@rootcat/node';
+await import('./app.mjs');
+```
+
+A single file with `import '@rootcat/node'` above `import pg from 'pg'`
+does not work: an ES module's static imports are all resolved and loaded
+before any of them runs, so the drivers are already in memory, unpatched,
+when the package starts. The dynamic `import()` runs after it.
+
+**When the code cannot change**, set the variable instead (in Dokploy, the
+application's Environment tab):
+
+```
+NODE_OPTIONS="--require @rootcat/node"          # CommonJS
+NODE_OPTIONS="--import @rootcat/node/esm"       # ES modules
+```
+
+Using the line and the variable together is harmless: the tracer starts
+once.
+
+The intake address is discovered: inside a container on a Docker bridge
+it is the container's default gateway (the bridge address the agent
+listens on); on the host, or in a container on the host's network, it is
+loopback; port 4318 either way. Discovery never picks a public address.
+The host-network check looks for a Docker bridge in `/sys/class/net`: a
+container on the host's network under Podman, or on a Docker host with no
+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`.
+
+**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
+
+| Package | Spans | Call site | Tested here |
+|---|---|---|---|
+| `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 (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 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
+`code.function` for the first application frame: outside `node_modules`,
+resolved through the file's source map when it has one, and skipped when
+the map sends it into a bundled library. `code.filepath` is relative to
+the working directory (or, outside it, to the parent of the file's
+package), cut from the front to 120 bytes; the server's absolute layout
+is not sent. A query run where no application frame is on the stack (a
+pool handing it to a client on the next tick, an awaited ORM promise)
+takes the site captured where the application made the call; a query
+issued in the continuation of another gets its own.
+
+## What never leaves the process
+
+Literals in query text: strings, numbers and dollar-quoted bodies become
+`?`, comments are dropped, placeholders (`$1`) and identifiers stay
+(`ROOTCAT_DB_STATEMENT=off` keeps only the first keyword). Parameter
+values (never read). Query strings and fragments on URLs, and every path
+segment that could hold an identifier or a token (`/users/42/orders` is
+sent as `/users/{id}/orders`): a segment is kept only when it is a name of
+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 (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.
+
+## Settings
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `ROOTCAT_SAMPLE` | `1` | share of traces recorded, `0` to `1`; a trace is kept or dropped whole, and an incoming `traceparent`'s sampled flag is ignored |
+| `ROOTCAT_CALLSITE_SAMPLE` | `1` | capture a call site for one recorded client span in N; `0` for none |
+| `ROOTCAT_OTLP_URL` | discovered | intake origin, or a full `/v1/traces` URL |
+| `ROOTCAT_SERVICE` | `OTEL_SERVICE_NAME`, then package.json | service name |
+| `ROOTCAT_ENVIRONMENT` | `NODE_ENV` | `deployment.environment.name` |
+| `ROOTCAT_DB_STATEMENT` | `masked` | `off` keeps only the statement's first keyword |
+| `ROOTCAT_DISABLE` | | comma list: `http,undici,pg,postgres,drizzle,mysql2,mongodb,ioredis,redis,prisma` |
+| `ROOTCAT_DEBUG` | | `1` prints the OpenTelemetry diagnostics and the chosen intake to stderr |
+| `ROOTCAT_DISABLED` | | `1` loads nothing |
+
+The two sampling settings are the only tuning; batching and the stack
+walk are fixed. The `OTEL_EXPORTER_OTLP_*` and `OTEL_TRACES_SAMPLER`
+variables are not read: spans go to the agent, sampled as above.
+
+## Cost
+
+Measured in one warmed-up process on a loop of sequential `pg` queries
+over loopback, the worst case for a per-query cost (`npm run bench`;
+WSL2, Node 24.21). Each loopback query costs 174 µs of CPU untraced.
+
+| Setting | CPU added per query | Wall added per query |
+|---|---|---|
+| Defaults (every query traced, every call site) | +190 µs | +204 µs |
+| `ROOTCAT_CALLSITE_SAMPLE=0` (no call sites) | +114 µs | +137 µs |
+| `ROOTCAT_CALLSITE_SAMPLE=10` | +142 µs | +166 µs |
+| `ROOTCAT_SAMPLE=0.1` (one trace in ten) | +63 µs | +82 µs |
+| A query in an unsampled trace | +29 µs | +45 µs |
+
+On a 20 ms request with five queries that is about 1 ms of CPU with the
+defaults and 0.3 ms at one trace in ten. Hot, a call-site capture costs
+11 µs, a span 4 µs, encoding a span 3.1 µs; in a server waiting on its
+database each query runs on cold caches and pays about four times that.
+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
+that the newest are dropped and stderr says so once), bounded (4 KiB per
+attribute value, statements and exception stacks included) and posted as
+protobuf in requests of at most 900 KiB, under the agent's 1 MiB bound,
+with a 2 s timeout and at most two exports in flight. A request the
+intake refuses as too large is said once on stderr. A failed export
+drops its batch. The application never waits on the exporter and never
+sees its errors. A process exiting with the intake unreachable waits up
+to 2 s for the last flush; on SIGTERM or SIGINT with no handler of the
+application's own, the flush is bounded to 2 s and the signal re-raised.
+A `process.exit()` ends the process before any flush: the spans of its
+last batch interval are lost.
+
+## Next.js details
+
+`pg`, `mongodb` and `@prisma/client` are external in Next.js by default;
+`postgres` and `drizzle-orm` are bundled unless listed. With
+`serverSourceMaps` the call sites name the original source files; the
+standalone output does not copy the maps, so a Dockerfile that copies
+`.next/standalone` should also copy every `.map` under `.next/server`,
+keeping its path (route chunks, `chunks/ssr/` for server components, and
+`app/**/page.js.map`), or the call sites name positions in the chunk:
+
+```dockerfile
+# after copying .next/standalone and .next/static
+COPY --from=builder /app/.next/server /tmp/next-server
+RUN cd /tmp/next-server && find . -name '*.map' -exec cp --parents {} /app/.next/server/ \; && rm -rf /tmp/next-server
+```
+
+## Bundlers
+
+An application bundled into one file (esbuild, webpack, Next.js server
+bundles) no longer loads its drivers through `require` or `import`, so
+nothing can patch them. Keep the drivers external (`--packages=external`
+in esbuild, `externals` in webpack, `serverExternalPackages` in Next.js).
+Call sites inside a bundle resolve through its source map when the bundle
+has one. Source maps are read once per file, at most 32 MiB each and
+64 MiB held at once, synchronously the first time a file appears on a
+captured stack.
+
+## Development
+
+```
+npm install
+npm test            # builds, then node:test; docker tests skip without docker
+npm run setup:next  # installs the Next.js fixture for its test (once)
+npm run bench       # call-site cost, startup and the pg loop
+```
+
+The package is not published yet.

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"}