@downtrace/agent 0.2.1 → 0.3.0

package/README.md

@@ -33,12 +33,39 @@ Without `DOWNTRACE_TOKEN` and `DOWNTRACE_URL` (or with a `DOWNTRACE_URL` that is
 
 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).
 
+### The health of your process
+
+Every interval the agent also reports how late Node's event loop ran (median, p99 and worst), how much time went to
+garbage collection, heap and resident memory, and the peak number of requests in flight. In Node many slowdowns are
+neither the database nor the network but the process itself, and a diagnosis that does not measure it will blame
+whatever it does measure. It all comes from Node's own instruments, which run whether anyone looks at them or not.
+
 ### 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.
+When your application uses `pg`, the agent also counts the calls each request makes to it, how long they took in
+total, the slowest one and how many failed, 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.
+
+### Calls to other services
+
+Outgoing HTTP is reported the same way, grouped by the host your application asked for: how many calls per request,
+how long they took, the slowest one, and how many failed. A 5xx from a dependency counts as a failure of that
+dependency, because for "is this service degraded?" a 500 and a timeout are the same answer.
+
+`fetch` and the `node:http` client both publish on Node's `diagnostics_channel`, and the agent listens. There is one
+exception: when a `fetch` cannot connect at all, undici publishes nothing, and that is exactly the case where a
+dependency is down. For that, and only that, the agent wraps `globalThis.fetch`: if a call rejects and nothing was
+recorded for it, it counts as a failed call. On every other path the wrapper does nothing.
+
+### Redis
+
+The commands each request issues are reported the same way, per server: how many per request, how long they took and
+how many failed. ioredis publishes on a tracing channel, so nothing is patched.
+
+Every dependency carries a **target** saying which instance of its kind it is, taken from the driver: the host for
+outgoing HTTP, host and port for Postgres and Redis. A read replica and a primary are two dependencies, not one.
+MySQL will appear the same way when it is added.
 
 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

package/dist/index.d.ts

@@ -1,4 +1,16 @@
-import { AgentInfo, DeployInfo, Endpoint, InstanceInfo, Interval } from "@downtrace/protocol";
+import { AgentInfo, Dependency, DeployInfo, Endpoint, InstanceInfo, Interval } from "@downtrace/protocol";
+//#region src/context.d.ts
+type DependencyKind = Dependency["kind"];
+/** What one request did against one dependency. Counters only: never the query text, never the values. */
+interface DependencyWork {
+  kind: DependencyKind;
+  target: string;
+  calls: number;
+  ms: number;
+  maxMs: number;
+  errors: number;
+}
+//#endregion
 //#region src/routes.d.ts
 type Method = Endpoint["method"];
 /** Route used when the per-interval cardinality cap is hit. */
@@ -19,14 +31,8 @@ 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, work?: QueryWork | undefined): void;
+  record(method: Method, route: string, status: number, ms: number, work?: Map<string, DependencyWork> | undefined): void;
   rotate(): Interval | null;
 }
 declare const DEFAULT_MAX_ROUTES = 500;
@@ -42,7 +48,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, work?: QueryWork | undefined): void;
+  record(method: Method, route: string, status: number, ms: number, work?: Map<string, DependencyWork> | undefined): void;
   /** Closes the current interval and starts a new one. Returns null when nothing was recorded. */
   rotate(): Interval | null;
 }
@@ -148,7 +154,10 @@ declare class Agent {
   private readonly handleSignals;
   private readonly starts;
   private readonly contexts;
+  private readonly runtime;
   private instrumented;
+  private stopHttp;
+  private stopRedis;
   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-B_GsH0f7.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-Dai_3scM.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-B_GsH0f7.js";
+import { a as createAgent, l as createLogger, n as configFromEnv } from "./config-Dai_3scM.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.2.1",
+  "version": "0.3.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.2.1"
+    "@downtrace/protocol": "0.3.0"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",