@downtrace/agent 0.1.1 → 0.2.0

package/README.md

@@ -20,21 +20,35 @@ NODE_OPTIONS="--import @downtrace/agent/register" node server.js
 | Variable | Required | What it is |
 |---|---|---|
 | `DOWNTRACE_TOKEN` | yes | The project's ingest token |
-| `DOWNTRACE_URL` | yes | Base URL of the cloud (`https://…`) |
+| `DOWNTRACE_URL` | yes | Base URL of the cloud, `http://` or `https://`; trailing slashes are ignored |
 | `DOWNTRACE_ENV` | no | Environment; falls back to `NODE_ENV`, then `production` |
 | `DOWNTRACE_VERSION` | no | Deployed version or commit; detected from `APP_VERSION`, `GIT_SHA`, `VERCEL_GIT_COMMIT_SHA`, `HEROKU_SLUG_COMMIT`, `SOURCE_VERSION`, `RENDER_GIT_COMMIT`, `RAILWAY_GIT_COMMIT_SHA`; else `unknown` |
-| `DOWNTRACE_DEBUG` | no | `1` to log the agent's own activity to stderr |
-| `DOWNTRACE_INTERVAL_MS` | no | Aggregation interval (min 1000; default 10000) |
+| `DOWNTRACE_DEBUG` | no | `1` or `true` to log the agent's own activity to stderr |
+| `DOWNTRACE_INTERVAL_MS` | no | Aggregation interval in ms (min 1000; default 10000; anything else falls back to the default) |
+| `DOWNTRACE_INSTRUMENT` | no | `none` stops the agent from observing database drivers; anything else keeps it on |
 
-Without `DOWNTRACE_TOKEN` and `DOWNTRACE_URL` the agent prints one warning and does nothing else.
+Without `DOWNTRACE_TOKEN` and `DOWNTRACE_URL` (or with a `DOWNTRACE_URL` that is not `http(s)://`) the agent prints one warning and does nothing else.
 
 ## What leaves your server
 
 Only structural metadata: method, **route template** (`/products/:id`, never the actual URL), status, counts and a fixed-bucket latency histogram per route and interval, plus the process identity (random id, hostname, pid) and the deploy (version, environment). No bodies, no headers, no query strings. The exact contract is the JSON Schema in [`@downtrace/protocol`](https://www.npmjs.com/package/@downtrace/protocol).
 
+### Database work per request
+
+When your application uses `pg`, the agent also counts the queries each request makes, how long they took in total
+and the slowest one, and reports that distribution per route. It is what turns "this endpoint got slower" into "this
+endpoint went from 12 queries per request to 65". **It never reads the query text or its values**, only counts and
+durations.
+
+The agent loads before your application (`node --import`), so it wraps the driver before you import it and you write
+no code. The wrapper passes arguments, results and errors through untouched, and a failure inside it runs your query
+anyway. `DOWNTRACE_INSTRUMENT=none` turns it off.
+
 ## Guarantees
 
-- Observation through Node's `diagnostics_channel`; nothing in your application is monkey-patched.
+- HTTP requests are observed through Node's `diagnostics_channel`, without touching your code. To count queries per
+  request the agent does wrap one method, `pg`'s `Client.prototype.query`: it passes arguments, results and errors
+  through untouched, and if the wrapper itself fails your query still runs. `DOWNTRACE_INSTRUMENT=none` disables it.
 - Sending is asynchronous with `fetch`, off the request path; a bounded queue of 6 intervals — if the cloud is unreachable, the oldest is dropped.
 - Every hook is guarded; after 10 internal errors the agent disables itself and says so once.
 - At most 500 distinct routes per interval; the rest fold into `(other)`.

package/dist/{config-IDWW6i_8.js → config-K6GUM60m.js}

@@ -1,7 +1,10 @@
+import { createRequire } from "node:module";
 import { randomUUID } from "node:crypto";
 import diagnostics_channel from "node:diagnostics_channel";
 import { hostname } from "node:os";
-import { AGGREGATES_PATH, LATENCY_BUCKETS_V0, PROTOCOL_VERSION, latencyBucket } from "@downtrace/protocol";
+import { AGGREGATES_PATH, LATENCY_BUCKETS_V0, PROTOCOL_VERSION, QUERIES_PER_REQUEST_BUCKETS_V0, latencyBucket, queriesPerRequestBucket } from "@downtrace/protocol";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { performance as performance$1 } from "node:perf_hooks";
 //#region src/routes.ts
 const METHODS = /* @__PURE__ */ new Set([
 	"GET",
@@ -64,7 +67,7 @@ var IntervalAggregator = class {
 	get size() {
 		return this.endpoints.size;
 	}
-	record(method, route, status, ms) {
+	record(method, route, status, ms, work) {
 		let key = `${method} ${route}`;
 		let acc = this.endpoints.get(key);
 		if (!acc) {
@@ -85,7 +88,8 @@ var IntervalAggregator = class {
 					serverError: 0,
 					counts: new Uint32Array(LATENCY_BUCKETS_V0),
 					sum: 0,
-					max: 0
+					max: 0,
+					pg: void 0
 				};
 				this.endpoints.set(key, acc);
 			}
@@ -102,6 +106,17 @@ var IntervalAggregator = class {
 		acc.counts[bucket] = (acc.counts[bucket] ?? 0) + 1;
 		acc.sum += latency;
 		if (latency > acc.max) acc.max = latency;
+		if (work) {
+			acc.pg ??= {
+				counts: new Uint32Array(QUERIES_PER_REQUEST_BUCKETS_V0),
+				sum: 0,
+				max: 0
+			};
+			const bucket = queriesPerRequestBucket(work.queries);
+			acc.pg.counts[bucket] = (acc.pg.counts[bucket] ?? 0) + 1;
+			acc.pg.sum += work.queryMs;
+			if (work.queryMaxMs > acc.pg.max) acc.pg.max = work.queryMaxMs;
+		}
 	}
 	/** Closes the current interval and starts a new one. Returns null when nothing was recorded. */
 	rotate() {
@@ -113,23 +128,31 @@ var IntervalAggregator = class {
 		this.start = now;
 		if (endpoints.size === 0) return null;
 		const out = [];
-		for (const acc of endpoints.values()) out.push({
-			method: acc.method,
-			route: acc.route,
-			count: acc.count,
-			errors: acc.errors,
-			status: {
-				success: acc.success,
-				redirect: acc.redirect,
-				clientError: acc.clientError,
-				serverError: acc.serverError
-			},
-			latency: {
-				counts: Array.from(acc.counts),
-				sum: round3(acc.sum),
-				max: round3(acc.max)
-			}
-		});
+		for (const acc of endpoints.values()) {
+			const postgres = acc.pg ? {
+				queriesPerRequest: Array.from(acc.pg.counts),
+				totalMs: round3(acc.pg.sum),
+				max: round3(acc.pg.max)
+			} : void 0;
+			out.push({
+				method: acc.method,
+				route: acc.route,
+				count: acc.count,
+				errors: acc.errors,
+				status: {
+					success: acc.success,
+					redirect: acc.redirect,
+					clientError: acc.clientError,
+					serverError: acc.serverError
+				},
+				latency: {
+					counts: Array.from(acc.counts),
+					sum: round3(acc.sum),
+					max: round3(acc.max)
+				},
+				...postgres ? { postgres } : {}
+			});
+		}
 		return {
 			start: Math.floor(start),
 			durationMs: Math.max(1, Math.round(now - start)),
@@ -141,6 +164,107 @@ function round3(n) {
 	return Math.round(n * 1e3) / 1e3;
 }
 //#endregion
+//#region src/context.ts
+const storage = new AsyncLocalStorage();
+/**
+* Opens the context for a request. Called from the `http.server.request.start` subscriber, which Node publishes
+* inside the request's own async context, so `enterWith` reaches the handler and everything it awaits. Verified
+* against concurrent keep-alive traffic: each request counts its own work.
+*/
+function enterRequest() {
+	const ctx = {
+		queries: 0,
+		queryMs: 0,
+		queryMaxMs: 0
+	};
+	storage.enterWith(ctx);
+	return ctx;
+}
+/** Records one finished query against the current request. Work outside a request is not attributed to any route. */
+function recordQuery(ms) {
+	const ctx = storage.getStore();
+	if (!ctx) return;
+	ctx.queries += 1;
+	ctx.queryMs += ms;
+	if (ms > ctx.queryMaxMs) ctx.queryMaxMs = ms;
+}
+//#endregion
+//#region src/instrument/pg.ts
+const MARK = Symbol.for("downtrace.pg.instrumented");
+/**
+* Wraps `pg`'s `Client.prototype.query` so every query counts towards the request that issued it.
+*
+* The agent loads before the application (`node --import`), resolves `pg` from the application's own root and
+* patches the prototype. CommonJS modules are cached by resolved path, so the instance the application later
+* imports is the one patched here: no loader hooks, no dependency, and it works whether the app is ESM or CJS.
+*
+* Returns the instrumented module's version, or undefined when there is nothing to instrument.
+*/
+function instrumentPg(deps) {
+	let pg;
+	let version = "unknown";
+	try {
+		if (deps.moduleImpl !== void 0) pg = deps.moduleImpl;
+		else {
+			const base = deps.from ?? process.argv[1] ?? `${process.cwd()}/`;
+			const require = createRequire(base);
+			pg = require("pg");
+			const pkg = require("pg/package.json");
+			if (typeof pkg.version === "string") version = pkg.version;
+		}
+	} catch {
+		return;
+	}
+	const proto = pg.Client?.prototype;
+	if (!proto || typeof proto.query !== "function") {
+		deps.log.debug("pg found but Client.prototype.query is not a function; not instrumenting");
+		return;
+	}
+	if (proto[MARK] === true) return version;
+	const original = proto.query;
+	const wrapped = function(...args) {
+		let done;
+		try {
+			const started = performance$1.now();
+			let counted = false;
+			done = () => {
+				if (counted) return;
+				counted = true;
+				recordQuery(performance$1.now() - started);
+			};
+			const last = args.at(-1);
+			if (typeof last === "function") {
+				const callback = last;
+				const finish = done;
+				args[args.length - 1] = function(...cbArgs) {
+					finish();
+					return callback.apply(this, cbArgs);
+				};
+				return original.apply(this, args);
+			}
+		} catch {
+			return original.apply(this, args);
+		}
+		const result = original.apply(this, args);
+		if (result && typeof result.then === "function") {
+			const settle = done;
+			return result.then((value) => {
+				settle?.();
+				return value;
+			}, (err) => {
+				settle?.();
+				throw err;
+			});
+		}
+		done?.();
+		return result;
+	};
+	proto.query = wrapped;
+	proto[MARK] = true;
+	deps.log.debug(`instrumented pg ${version}`);
+	return version;
+}
+//#endregion
 //#region src/log.ts
 const PREFIX = "[downtrace]";
 /** Minimal stderr logger. `debug` lines only appear with DOWNTRACE_DEBUG. */
@@ -236,7 +360,7 @@ var Sender = class {
 //#endregion
 //#region src/version.ts
 /** Version of this agent build, from package.json. */
-const AGENT_VERSION = "0.1.1";
+const AGENT_VERSION = "0.2.0";
 //#endregion
 //#region src/agent.ts
 const REQUEST_START = "http.server.request.start";
@@ -258,6 +382,8 @@ var Agent = class {
 	sender;
 	handleSignals;
 	starts = /* @__PURE__ */ new WeakMap();
+	contexts = /* @__PURE__ */ new WeakMap();
+	instrumented = false;
 	timer;
 	started = false;
 	recorded = 0;
@@ -317,6 +443,11 @@ var Agent = class {
 	start() {
 		if (this.started || this.disabled) return;
 		this.started = true;
+		if (this.config.instrument) {
+			const pg = instrumentPg({ log: this.log });
+			this.instrumented = pg !== void 0;
+			if (pg) this.log.debug(`instrumented pg ${pg}`);
+		}
 		diagnostics_channel.subscribe(REQUEST_START, this.onStart);
 		diagnostics_channel.subscribe(RESPONSE_FINISH, this.onFinish);
 		this.timer = setInterval(() => void this.flushNow(), this.config.intervalMs);
@@ -349,7 +480,9 @@ var Agent = class {
 	}
 	requestStarted(message) {
 		const request = message.request;
-		if (request) this.starts.set(request, performance.now());
+		if (!request) return;
+		this.starts.set(request, performance.now());
+		if (this.instrumented) this.contexts.set(request, enterRequest());
 	}
 	responseFinished(message) {
 		const { request, response } = message;
@@ -357,7 +490,9 @@ var Agent = class {
 		const startedAt = this.starts.get(request);
 		this.starts.delete(request);
 		const ms = startedAt === void 0 ? 0 : performance.now() - startedAt;
-		this.recorder.record(normalizeMethod(request.method), routeOf(request), response?.statusCode ?? 0, ms);
+		const work = this.contexts.get(request);
+		this.contexts.delete(request);
+		this.recorder.record(normalizeMethod(request.method), routeOf(request), response?.statusCode ?? 0, ms, work);
 		this.recorded += 1;
 	}
 	/** Every hook runs through here: an agent bug must never reach the application. */
@@ -439,7 +574,8 @@ function configFromEnv(env = process.env) {
 			environment: clamp(env.DOWNTRACE_ENV ?? env.NODE_ENV ?? "production", 64),
 			version: detectVersion(env),
 			debug: env.DOWNTRACE_DEBUG === "1" || env.DOWNTRACE_DEBUG === "true",
-			intervalMs: Number.isInteger(interval) && interval >= MIN_INTERVAL_MS ? interval : DEFAULT_INTERVAL_MS
+			intervalMs: Number.isInteger(interval) && interval >= MIN_INTERVAL_MS ? interval : DEFAULT_INTERVAL_MS,
+			instrument: (env.DOWNTRACE_INSTRUMENT ?? "auto") !== "none"
 		}
 	};
 }

package/dist/index.d.ts

@@ -19,8 +19,14 @@ declare function routeOf(req: RouteSource): string;
 declare function heuristicTemplate(url: string): string;
 //#endregion
 //#region src/aggregator.d.ts
+/** What one finished request did in Postgres, as seen by the instrumented driver. */
+interface QueryWork {
+  queries: number;
+  queryMs: number;
+  queryMaxMs: number;
+}
 interface Recorder {
-  record(method: Method, route: string, status: number, ms: number): void;
+  record(method: Method, route: string, status: number, ms: number, work?: QueryWork | undefined): void;
   rotate(): Interval | null;
 }
 declare const DEFAULT_MAX_ROUTES = 500;
@@ -36,7 +42,7 @@ declare class IntervalAggregator implements Recorder {
   private readonly now;
   constructor(maxRoutes?: number, now?: () => number);
   get size(): number;
-  record(method: Method, route: string, status: number, ms: number): void;
+  record(method: Method, route: string, status: number, ms: number, work?: QueryWork | undefined): void;
   /** Closes the current interval and starts a new one. Returns null when nothing was recorded. */
   rotate(): Interval | null;
 }
@@ -51,6 +57,8 @@ interface AgentConfig {
   debug: boolean;
   /** Aggregation interval; 10 s in production. */
   intervalMs: number;
+  /** Observe database drivers to attribute work to each request. `DOWNTRACE_INSTRUMENT=none` turns it off. */
+  instrument: boolean;
 }
 type ConfigResult = {
   ok: true;
@@ -139,6 +147,8 @@ declare class Agent {
   private readonly sender;
   private readonly handleSignals;
   private readonly starts;
+  private readonly contexts;
+  private instrumented;
   private timer;
   private started;
   private recorded;

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as createAgent, c as Sender, d as IntervalAggregator, f as OTHER_ROUTE, h as routeOf, i as Agent, l as createLogger, m as normalizeMethod, n as configFromEnv, o as AGENT_VERSION, p as heuristicTemplate, r as detectVersion, s as DEFAULT_MAX_QUEUED, t as DEFAULT_INTERVAL_MS, u as DEFAULT_MAX_ROUTES } from "./config-IDWW6i_8.js";
+import { a as createAgent, c as Sender, d as IntervalAggregator, f as OTHER_ROUTE, h as routeOf, i as Agent, l as createLogger, m as normalizeMethod, n as configFromEnv, o as AGENT_VERSION, p as heuristicTemplate, r as detectVersion, s as DEFAULT_MAX_QUEUED, t as DEFAULT_INTERVAL_MS, u as DEFAULT_MAX_ROUTES } from "./config-K6GUM60m.js";
 export { AGENT_VERSION, Agent, DEFAULT_INTERVAL_MS, DEFAULT_MAX_QUEUED, DEFAULT_MAX_ROUTES, IntervalAggregator, OTHER_ROUTE, Sender, configFromEnv, createAgent, createLogger, detectVersion, heuristicTemplate, normalizeMethod, routeOf };

package/dist/register.js

@@ -1,4 +1,4 @@
-import { a as createAgent, l as createLogger, n as configFromEnv } from "./config-IDWW6i_8.js";
+import { a as createAgent, l as createLogger, n as configFromEnv } from "./config-K6GUM60m.js";
 //#region src/register.ts
 /**
 * Entry point users load with `node --import @downtrace/agent/register`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downtrace/agent",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Downtrace agent for Node.js: a flight recorder for your backend. Observes HTTP requests, aggregates locally, ships compact batches, never in your request path.",
   "type": "module",
   "exports": {
@@ -22,7 +22,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@downtrace/protocol": "0.1.0"
+    "@downtrace/protocol": "0.2.0"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",