@autter/runtime-node 1.7.0 → 1.9.0

package/README.md

@@ -127,7 +127,39 @@ export const POST = createBrowserRelayFetchHandler({
 ```
 
 Options: `endpoint` (default `https://otlp.autter.dev`), `maxBodyBytes`
-(default 64 KB), `onError`.
+(default 64 KB), `perIpRateLimit` (default 120 requests a minute per client;
+`false` when a WAF already limits the route), `trustProxy`, `redact`,
+`compatCheck`, `onError`.
+
+**Rate-limit key and `trustProxy`.** The relay route is public, so it limits
+each visitor. Any caller can write anything into `X-Forwarded-For`, so by
+default (`trustProxy: "auto"`) the relay never takes that header's first entry.
+Proxies append the address they saw to the right of the header, or overwrite
+it, so the relay reads it right to left and takes the first public address,
+skipping hops on your own network. That works behind load balancers, CDNs and
+hosting platforms with no setup:
+
+| Where the relay runs | What `"auto"` keys |
+| --- | --- |
+| Node, reached directly | The connection's own address; the header is ignored |
+| Node behind a load balancer or ingress on your network | The address that proxy appended |
+| Next.js route handlers, Vercel, Netlify, Deno Deploy and other fetch runtimes | The rightmost public entry, which the platform's edge wrote |
+| Cloudflare Workers | `CF-Connecting-IP` |
+
+Other settings:
+
+- `trustProxy: 1` (or any count) when exactly that many proxies you control
+  sit in front, such as a Node origin behind Cloudflare with no load balancer.
+- `trustProxy: true` when every proxy in front strips client values: the
+  leftmost entry.
+- `trustProxy: false` never reads the header: the socket address in Node, one
+  shared bucket in fetch runtimes.
+- `clientIp: (request) => string` to supply the address yourself, for example
+  Deno's `info.remoteAddr` or Bun's `server.requestIP`.
+
+Strings from environment variables work too (`"auto"`, `"false"`, `"2"`).
+A fetch handler exposed straight to the internet with no proxy in front can
+still be fooled by a forged header; set `trustProxy: false` or `clientIp` there.
 
 ## 2. Server tracker
 
@@ -242,6 +274,76 @@ when the error was already reported). Errors from another JavaScript realm
 message and stack. `autterErrorResponse()` reports the same way and also
 answers the request.
 
+### Sample and ignore errors (1.8.0)
+
+```ts
+initAutterServer({
+  ...,
+  sampleRate: 0.5,                                        // half of captured errors
+  ignoreErrors: ["ECONNRESET", /^AbortError$/, /^billing\.declined/],
+});
+```
+
+- `sampleRate` (0..1, default 1): the share of captured errors reported:
+  `captureException`, error-level `captureMessage` and `reportOutcome`.
+  Never a fatal message, a crash (uncaught exception) or an unhandled
+  rejection (which may be one); warnings and info are never sampled. Not
+  `traceSampleRate`, which samples healthy traces.
+- `ignoreErrors`: never reported. A string matches when the error's type
+  (`error.name`) or message contains it (case-sensitive); a RegExp is tested
+  against the type, the message and `"<type>: <message>"`. Every capture
+  path, crashes included.
+- A value filtered out is marked captured, so a later hook (error
+  middleware, `onRequestError`) does not report it either. A request that
+  failed still exports its failed span, which the ingester turns into a
+  stackless `HttpServerError` for a 5xx; leave those out with a
+  suppression rule.
+- `initAutterLogging` takes the same two options; `registerAutter`
+  (`@autter/runtime-next`) passes them through.
+
+What the SDK filters never leaves the process and is counted nowhere. For
+volume control that is counted, applies to every SDK and service at once and
+is changed without a deploy, use **suppression rules** in Autter's Runtime
+settings (drop or sample by error type, message, service, environment,
+route, release or source; ingester 1.9.0). The ingester also collapses a
+looping error into one sample a minute with an exact count.
+
+### Caught errors and deliberate fallbacks
+
+Errors you catch and log count on their own — no `captureException` needed.
+An `Error` passed to `console.error`, pino, winston, bunyan or
+`runtimeLogger.error` becomes an occurrence at `error` severity, with the log
+line as context and the error's stack, marked
+`autter.handling: "caught"`. A log line with no error object is untouched, and
+an error you also pass to `captureException` in the same tick is reported
+once. A caught error never fails the request it happened in, and handled
+occurrences stay out of your error rate — they are issues to see, not
+failures. A burst limit per error kind keeps ten at once, then one every ten
+seconds; the ones left out are counted.
+
+```ts
+initAutterServer({ ... });                 // on by default
+initAutterServer({ ..., captureLoggedErrors: false });        // off
+initAutterServer({ ..., captureLoggedErrors: { console: false } }); // keep loggers, not console
+```
+
+When you mean to ignore an error — a fallback you chose — say so in one line:
+
+```ts
+try {
+  prices = await pricingService.get();
+} catch (err) {
+  runtimeContext.degraded(err, "pricing service down, using cached prices");
+  prices = cached;
+}
+```
+
+`runtimeContext.degraded(err, reason)` records the error at `warning`
+severity, marked `autter.handling: "deliberate"` with the reason (grouped by
+its code when the error is coded), and never pages anyone. The current
+request or operation ends `degraded` unless it already failed or set its own
+outcome — so a crash, a caught error and a deliberate fallback are told apart.
+
 ### Unhandled promise rejections
 
 Recorded as errors (severity `error`, `autter.unhandled_rejection: true`, not

package/dist/{chunk-HKVFURYT.cjs → chunk-AN45KLWD.cjs}

@@ -5,7 +5,7 @@
 
 
 
-var _chunkGYTQLITWcjs = require('./chunk-GYTQLITW.cjs');
+var _chunkBHYHORUDcjs = require('./chunk-BHYHORUD.cjs');
 
 // src/doctor.ts
 var _fs = require('fs');
@@ -30,19 +30,19 @@ function installedSdks(cwd) {
     }
     if (_path.dirname.call(void 0, dir) === dir) break;
   }
-  if (!found.has(_chunkGYTQLITWcjs.SDK_IDENTITY.name)) found.set(_chunkGYTQLITWcjs.SDK_IDENTITY.name, _chunkGYTQLITWcjs.SDK_IDENTITY.version);
+  if (!found.has(_chunkBHYHORUDcjs.SDK_IDENTITY.name)) found.set(_chunkBHYHORUDcjs.SDK_IDENTITY.name, _chunkBHYHORUDcjs.SDK_IDENTITY.version);
   return [...found].map(([name, version]) => ({ name, version }));
 }
 function featuresInUse(sdks) {
-  return _chunkGYTQLITWcjs.COMPAT_MANIFEST.features.filter(
+  return _chunkBHYHORUDcjs.COMPAT_MANIFEST.features.filter(
     (feature) => sdks.some((sdk) => {
       const min = feature.sdks[sdk.name];
-      return min !== void 0 && _chunkGYTQLITWcjs.versionAtLeast.call(void 0, sdk.version, min) === true;
+      return min !== void 0 && _chunkBHYHORUDcjs.versionAtLeast.call(void 0, sdk.version, min) === true;
     })
   ).map((feature) => feature.id);
 }
 async function checkKey(endpoint, key, timeoutMs) {
-  const res = await _chunkGYTQLITWcjs.compatRequest.call(void 0, "POST", `${endpoint}/v1/traces`, {
+  const res = await _chunkBHYHORUDcjs.compatRequest.call(void 0, "POST", `${endpoint}/v1/traces`, {
     body: JSON.stringify({ resourceSpans: [] }),
     headers: { authorization: `Bearer ${key}` },
     unref: false,
@@ -62,10 +62,10 @@ async function runDoctor(options = {}) {
   const features = _optionalChain([options, 'access', _ => _.features, 'optionalAccess', _2 => _2.length]) ? options.features : featuresInUse(sdks);
   const routes = [
     ...new Set(
-      features.map((id) => _optionalChain([_chunkGYTQLITWcjs.COMPAT_MANIFEST, 'access', _3 => _3.features, 'access', _4 => _4.find, 'call', _5 => _5((f) => f.id === id), 'optionalAccess', _6 => _6.route])).filter((route) => Boolean(route))
+      features.map((id) => _optionalChain([_chunkBHYHORUDcjs.COMPAT_MANIFEST, 'access', _3 => _3.features, 'access', _4 => _4.find, 'call', _5 => _5((f) => f.id === id), 'optionalAccess', _6 => _6.route])).filter((route) => Boolean(route))
     )
   ];
-  const { info, error } = await _chunkGYTQLITWcjs.fetchIngesterCompat.call(void 0, endpoint, { probeRoutes: routes, unref: false, timeoutMs });
+  const { info, error } = await _chunkBHYHORUDcjs.fetchIngesterCompat.call(void 0, endpoint, { probeRoutes: routes, unref: false, timeoutMs });
   const issues = [];
   const seen = /* @__PURE__ */ new Set();
   const add = (issue) => {
@@ -75,15 +75,15 @@ async function runDoctor(options = {}) {
       issues.push(issue);
     }
   };
-  _chunkGYTQLITWcjs.evaluateCompat.call(void 0, { features, ingester: info }).forEach(add);
+  _chunkBHYHORUDcjs.evaluateCompat.call(void 0, { features, ingester: info }).forEach(add);
   for (const sdk of sdks) {
     if (_optionalChain([options, 'access', _7 => _7.features, 'optionalAccess', _8 => _8.length])) {
-      _chunkGYTQLITWcjs.evaluateCompat.call(void 0, { features: options.features, ingester: null, sdk }).forEach(add);
+      _chunkBHYHORUDcjs.evaluateCompat.call(void 0, { features: options.features, ingester: null, sdk }).forEach(add);
     }
   }
   const key = options.key ? await checkKey(endpoint, options.key, timeoutMs) : void 0;
   const featureRows = features.flatMap((id) => {
-    const feature = _chunkGYTQLITWcjs.COMPAT_MANIFEST.features.find((f) => f.id === id);
+    const feature = _chunkBHYHORUDcjs.COMPAT_MANIFEST.features.find((f) => f.id === id);
     if (!feature) return [];
     const bad = issues.some((issue) => issue.feature === id);
     const known = _optionalChain([info, 'optionalAccess', _9 => _9.version]) != null || feature.route !== void 0 && _optionalChain([info, 'optionalAccess', _10 => _10.routes, 'optionalAccess', _11 => _11[feature.route]]) !== void 0;
@@ -153,7 +153,7 @@ Checks that your Autter SDKs, ingester and ClickHouse schema versions match.
 Options:
   --endpoint <url>    Ingester base URL (default: $AUTTER_ENDPOINT, $OTEL_EXPORTER_OTLP_ENDPOINT, or ${DEFAULT_ENDPOINT})
   --key <key>         Also verify an ingest key (default: $AUTTER_RUNTIME_KEY)
-  --features <a,b>    Only check these features (${_chunkGYTQLITWcjs.COMPAT_MANIFEST.features.map((f) => f.id).join(", ")})
+  --features <a,b>    Only check these features (${_chunkBHYHORUDcjs.COMPAT_MANIFEST.features.map((f) => f.id).join(", ")})
   --json              Machine-readable output
   --timeout <ms>      Per-request timeout (default 5000)
 

package/dist/{chunk-GYTQLITW.cjs → chunk-BHYHORUD.cjs}

@@ -156,6 +156,57 @@ var compat_manifest_default = {
       ingester: "1.8.0",
       migrations: ["0020-occurrence-frame-resolution"],
       sdks: {}
+    },
+    {
+      id: "ingest_suppression",
+      title: "Suppression rules: drop or sample matching errors at ingest",
+      ingester: "1.9.0",
+      migrations: [],
+      sdks: {}
+    },
+    {
+      id: "loop_collapse",
+      title: "Loop collapse: a looping error stored as one sample a minute with an exact count",
+      ingester: "1.9.0",
+      migrations: ["0021-occurrence-collapsed-count"],
+      sdks: {}
+    },
+    {
+      id: "edge_request_counts",
+      title: "Edge requests counted from their request summaries",
+      ingester: "1.10.0",
+      migrations: [],
+      route: "/v1/logs",
+      sdks: { "@autter/runtime-edge": "1.3.0" }
+    },
+    {
+      id: "caught_errors",
+      title: "Caught errors and deliberate fallbacks recorded as handled occurrences",
+      ingester: "1.11.0",
+      migrations: [],
+      sdks: { "@autter/runtime-node": "1.9.0", "@autter/runtime-edge": "1.4.0", "@autter/runtime-next": "1.9.0", "@autter/runtime-browser": "1.8.0" }
+    },
+    {
+      id: "route_percentiles",
+      title: "Per-route p95 and p99 latency in the 1-minute rollups",
+      ingester: "1.11.0",
+      migrations: ["0022-route-latency-1m"],
+      sdks: {}
+    },
+    {
+      id: "server_source_maps",
+      title: "Server bundles symbolicated, with source context lines",
+      ingester: "1.11.0",
+      migrations: [],
+      route: "/v1/sourcemaps",
+      sdks: { "@autter/runtime-cli": "1.3.0", "@autter/runtime-node": "1.9.0", "@autter/runtime-edge": "1.4.0", "@autter/runtime-next": "1.9.0" }
+    },
+    {
+      id: "cause_fingerprint",
+      title: "Wrapped errors grouped with their root cause (cause-v1)",
+      ingester: "1.11.0",
+      migrations: [],
+      sdks: { "@autter/runtime-node": "1.9.0", "@autter/runtime-edge": "1.4.0", "@autter/runtime-next": "1.9.0" }
     }
   ]
 };
@@ -501,7 +552,7 @@ var _https = require('https');
 // package.json
 var package_default = {
   name: "@autter/runtime-node",
-  version: "1.7.0",
+  version: "1.9.0",
   description: "Autter Runtime for Node.js: request wide events, coded errors, operation logging, same-origin browser relay and a curated OpenTelemetry server tracker",
   license: "MIT",
   type: "module",
@@ -546,16 +597,20 @@ var package_default = {
     "@opentelemetry/sdk-metrics": "^1.30.1",
     "@opentelemetry/sdk-node": "^0.57.1",
     "@opentelemetry/sdk-trace-base": "^1.30.1",
-    "@opentelemetry/semantic-conventions": "^1.28.0"
+    "@opentelemetry/semantic-conventions": "^1.28.0",
+    "require-in-the-middle": "^7.5.2"
   },
   devDependencies: {
     "@autter/runtime-core": "0.0.0",
     "@types/node": "^22.10.0",
+    bunyan: "^1.8.15",
     express: "^4.21.2",
     fastify: "^5.12.5",
     koa: "^3.2.1",
+    pino: "^10.4.0",
     tsup: "^8.3.5",
-    typescript: "^5.7.0"
+    typescript: "^5.7.0",
+    winston: "^3.19.0"
   },
   engines: {
     node: ">=20"