@rootcat/node 0.0.0-stage → 0.1.0

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,214 @@
-# 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`.
+
+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.
+
+## 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 | 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 |
+| `@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. 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).
+
+## 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/callsite.d.ts

@@ -0,0 +1,109 @@
+import { TraceMap } from '@jridgewell/trace-mapping';
+/** CallSiteLocation is one resolved frame. */
+export interface CallSiteLocation {
+    /** file is an absolute path, or a bundler path such as app/route.ts. */
+    file: string;
+    /** line is 1-based. */
+    line: number;
+    /** column is 1-based, 0 when unknown. */
+    column: number;
+    /** function is the enclosing function's name, "" when anonymous. */
+    function: string;
+}
+type V8CallSite = NodeJS.CallSite;
+/** defaultDepth is how many frames a full capture walks. */
+export declare const defaultDepth = 32;
+/**
+ * shortDepth is the first walk from an entry wrapper: its caller is the
+ * application or an ORM a few frames above it. A stack frame costs about
+ * a microsecond to collect; the full walk is the fallback.
+ */
+export declare const shortDepth = 3;
+/** Bounds on source maps: per map, and for all maps held at once. */
+export declare const maxSourceMapBytes: number;
+export declare const sourceMapBudgetBytes: number;
+/** maxDisplayPathBytes keeps code.filepath within the agent's 128-byte bound. */
+export declare const maxDisplayPathBytes = 120;
+/**
+ * captureFrames returns up to depth frames as V8 CallSite objects,
+ * starting below the topmost call of above (or of captureFrames itself).
+ * Error.prepareStackTrace and Error.stackTraceLimit are swapped for the
+ * duration of the capture only. When above is not on the stack, V8 gives
+ * nothing; the caller falls back to an uncut walk.
+ */
+export declare function captureFrames(depth: number, above?: Function): V8CallSite[];
+/**
+ * normalizeFile turns a CallSite file name into a path: file URLs become
+ * paths, webpack-internal URLs lose their prefix; node: internals, eval
+ * and other non-paths give undefined.
+ */
+export declare function normalizeFile(file: string | null | undefined): string | undefined;
+/**
+ * isAppFile reports whether a path belongs to the application: no
+ * node_modules segment (absolute or bundler-relative, as a source map
+ * names a bundled library) and not this package's own code.
+ */
+export declare function isAppFile(file: string, own?: readonly string[]): boolean;
+/** firstAppFrame returns the first captured frame whose generated file is application code, unresolved. */
+export declare function firstAppFrame(sites: readonly V8CallSite[], isApp?: (file: string) => boolean): CallSiteLocation | undefined;
+/**
+ * appLocation walks the frames, resolves each candidate through its
+ * source map, and returns the first whose original source is application
+ * code: a frame in a bundle that maps into a bundled library is passed
+ * over, as an unbundled library frame is.
+ */
+export declare function appLocation(sites: readonly V8CallSite[], isApp?: (file: string) => boolean): CallSiteLocation | undefined;
+/** resetSourceMapCache forgets loaded maps (tests). */
+export declare function resetSourceMapCache(): void;
+/** sourceMapBytesHeld reports what the cache holds (tests). */
+export declare function sourceMapBytesHeld(): number;
+/**
+ * sourceMapFor loads the source map a generated file points at through
+ * its sourceMappingURL comment (inline data URL or a file beside it),
+ * once per file, and remembers the result; null when none. A map over
+ * maxSourceMapBytes is not read; the maps held together stay within
+ * sourceMapBudgetBytes, the least recently loaded given up first (and
+ * read again if their file comes back). The read is synchronous and
+ * happens the first time a file is seen on a captured stack.
+ */
+export declare function sourceMapFor(file: string): TraceMap | null;
+/** sourceMappingURL finds the last sourceMappingURL comment in text. */
+export declare function sourceMappingURL(text: string): string | undefined;
+/**
+ * originalPath makes a mapped source readable: file URLs become paths and
+ * bundler schemes (webpack://, turbopack://) are reduced to the project
+ * relative path they carry.
+ */
+export declare function originalPath(source: string): string;
+/**
+ * resolveLocation maps a generated position to the original source when
+ * the file has a source map: the one Node already holds (with
+ * --enable-source-maps, or a loader such as tsx registering its maps),
+ * else the file's own. Otherwise the location is returned as is.
+ */
+export declare function resolveLocation(location: CallSiteLocation): CallSiteLocation;
+/**
+ * parseStack finds the first application frame in a formatted V8 stack
+ * (one a driver captured itself, such as postgres.js's query origin) and
+ * resolves it. undefined when there is none.
+ */
+export declare function parseStack(stack: string, isApp?: (file: string) => boolean): CallSiteLocation | undefined;
+/**
+ * captureCallSite is the whole operation: capture, pick the application
+ * frame, resolve it. From an entry wrapper (above), a short walk below
+ * the wrapper first, the full walk only when that finds no application
+ * frame. undefined when no application frame is on the stack.
+ */
+export declare function captureCallSite(depth?: number, isApp?: (file: string) => boolean, above?: Function): CallSiteLocation | undefined;
+/**
+ * displayPath is what code.filepath carries: a bundler path as it is, a
+ * file under the working directory relative to it, any other file
+ * relative to the parent of its nearest package.json directory (so it
+ * names its package), and at most maxDisplayPathBytes from the end, so
+ * the file name survives the agent's bound. The server's absolute layout
+ * (a home directory, a deploy path) is not sent.
+ */
+export declare function displayPath(file: string, cwd?: string): string;
+/** clipFromStart keeps the last bytes of a path, cut at a segment. */
+export declare function clipFromStart(text: string, limit: number): string;
+export {};