@heystack/otel 0.4.1 → 0.4.3

package/README.md

@@ -200,8 +200,11 @@ As of **0.3.1** the exporter **suppresses tracing for its own ingest POST**, and
 
 As belt-and-suspenders the exporter also drops any span whose HTTP target points at the configured ingest origin. As of **0.3.2** that match is **hostname-accurate**: full-URL attributes (`url.full`, `http.url`) are parsed and compared on `.hostname` (case-insensitive, port-stripped) so a sibling domain like `myingest.heystack.dev` is no longer a false positive and an explicit port like `ingest.heystack.dev:443` is correctly matched; host-only attributes (`server.address`, `net.peer.name`, `net.peer.hostname`, `http.host`, `peer.address`) are port-stripped and compared by hostname.
 
+**The `/node` (and Next-on-Node) path got the same guard in `0.4.3`.** Before then, only the Workers/Edge exporter dropped self-spans; on a plain Node runtime the OTLP-over-`http` exporter's own `POST /v1/traces` was still captured by the HTTP/undici auto-instrumentation and re-exported, so the **same feedback loop ran on Node** (production measurement: ~77% of all ingested spans were `fetch POST .../v1/traces`). `0.4.3` (a) configures the HTTP + undici auto-instrumentations to ignore outbound requests to the ingest host, and (b) wraps the exporter so any span targeting the ingest origin is filtered before export — the latter holds even if you pass your own `instrumentations` array. Same hostname-accurate matcher as the Workers path (shared module). No API change; upgrade and redeploy.
+
 ## Migration / versioning
 
+- **`0.4.3`** — **feedback-loop guard extended to the Node path (cost fix).** The self-instrumentation loop the Workers path fixed in 0.3.1/0.3.2 was still live on plain Node / Next-on-Node: the OTLP-over-`http` exporter's `POST /v1/traces` was auto-instrumented and re-exported, so ~77% of ingested spans in production were the exporter tracing itself — needless ingest + ClickHouse compute. 0.4.3 ignores ingest-host requests in the HTTP/undici auto-instrumentations **and** filters self-spans at the exporter boundary (covers caller-supplied `instrumentations` too). The hostname matcher is now a shared module used by both `/node` and `/workers`. No API change. **Action: upgrade and redeploy any Node/Next-on-Node app** — it cuts ingested span volume sharply.
 - **`0.3.5`** — **type-constraint fix (Workers).** A Worker whose `queue` consumer is typed with a concrete message body — `queue(batch: MessageBatch<MyJob>, …)`, the normal case — failed to compile against `instrument()` in 0.3.4 (`TS2345`: `MessageBatch<unknown>` not assignable to `MessageBatch<MyJob>`). The `WorkerHandler` constraint declared its entrypoints as arrow properties, whose parameters are checked **contravariantly** under `strictFunctionTypes`, so a narrowed handler wasn't assignable. 0.3.5 declares them with **method syntax** (bivariant parameters) and widens the batch to `MessageBatch<any>`, mirroring Cloudflare's own `ExportedHandler` — a typed-queue Worker now type-checks with a bare `instrument(handler, cfg)`. Runtime behaviour unchanged. Also adds a **consumer type-check gate** (`pnpm consumer-typecheck`, run in `check` and `prepublishOnly`) that compiles a fully-typed Worker against the built `dist` through the public `exports` map and asserts `satisfies ExportedHandler<Env>` — the regression that escaped in 0.3.3/0.3.4 now fails the build before publish.
 - **`0.3.4`** — **type-inference fix (Workers).** Restores `instrument()`'s ability to infer the handler's concrete `Env` type. In 0.3.3 the signature was `instrument<E = unknown, H extends WorkerHandler<E>>`, so `E` defaulted to `unknown` and was never recovered from the handler — under `strictFunctionTypes` a Worker typed `fetch(req, env: Env, ctx)` then failed to compile (`TS2345: 'Env' is not assignable to 'unknown'`) unless the caller passed `instrument<Env>(...)` explicitly. 0.3.4 infers `E` from the handler argument (`instrument<H extends WorkerHandler<any>>(...): Instrumented<EnvOf<H>, H>`), so a bare `instrument(handler, cfg)` type-checks again. Runtime behaviour is unchanged; no `0.3.3` consumer needs the explicit type arg after upgrading.
 - **`0.3.3`** — `/next` uses bare, exports-mapped dynamic imports so the OpenNext (Cloudflare Pages) build resolves the workers entry correctly (fixes a build break). Workers/Node paths unchanged.

package/dist/node.d.ts

@@ -1,5 +1,7 @@
 import { NodeSDK } from "@opentelemetry/sdk-node";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+import { type ExportResult } from "@opentelemetry/core";
+import type { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";
 import { type HeystackOptions } from "./core.js";
 /**
  * The element type the NodeSDK `instrumentations` config accepts (an OTel
@@ -24,6 +26,32 @@ export interface NodeOptions extends HeystackOptions {
      */
     instrumentations?: InstrumentationConfigItem[];
 }
+/**
+ * Wraps a span exporter and drops any span that targets the Heystack ingest
+ * origin before it is exported. On Node/Next the runtime auto-instruments
+ * outbound HTTP, so the exporter's own POST to `/v1/traces` becomes a CLIENT
+ * span → exported → re-captured → a sustained self-feeding loop. We measured
+ * this loop accounting for ~77% of ingested spans in production.
+ *
+ * The `/workers` entry stops the loop at the exporter via a suppressed context;
+ * Node's OTLP-over-`http` exporter cannot rely on that being honoured by every
+ * instrumentation version, so we filter at the exporter boundary instead. This
+ * is the universal guard — it works regardless of which instrumentations are
+ * loaded (including a caller-supplied `instrumentations` array). The
+ * `ignore*RequestHook` config below is the cheaper primary defence that stops
+ * the self-span from being created in the first place.
+ */
+export declare class SelfSpanFilteringExporter implements SpanExporter {
+    private readonly inner;
+    /** Bare ingest hostname (lower-case, no port), e.g. `ingest.heystack.dev`. */
+    private readonly ingestHost;
+    constructor(inner: SpanExporter, 
+    /** Bare ingest hostname (lower-case, no port), e.g. `ingest.heystack.dev`. */
+    ingestHost: string);
+    export(spans: ReadableSpan[], cb: (result: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}
 /** Initialise Heystack tracing on a Node runtime. Call once, as early as possible. Returns the started SDK. */
 export declare function initHeystack(o: NodeOptions): NodeSDK;
 /** Flush + shutdown the SDK on SIGTERM/SIGINT so short-lived processes don't lose the last batch. Registers handlers at most once. */

package/dist/node.js

@@ -2,7 +2,78 @@ import { NodeSDK } from "@opentelemetry/sdk-node";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
+import { ExportResultCode } from "@opentelemetry/core";
 import { buildExporterConfig } from "./core.js";
+import { isSelfSpanAttrs, safeHostname } from "./self-span.js";
+/**
+ * Wraps a span exporter and drops any span that targets the Heystack ingest
+ * origin before it is exported. On Node/Next the runtime auto-instruments
+ * outbound HTTP, so the exporter's own POST to `/v1/traces` becomes a CLIENT
+ * span → exported → re-captured → a sustained self-feeding loop. We measured
+ * this loop accounting for ~77% of ingested spans in production.
+ *
+ * The `/workers` entry stops the loop at the exporter via a suppressed context;
+ * Node's OTLP-over-`http` exporter cannot rely on that being honoured by every
+ * instrumentation version, so we filter at the exporter boundary instead. This
+ * is the universal guard — it works regardless of which instrumentations are
+ * loaded (including a caller-supplied `instrumentations` array). The
+ * `ignore*RequestHook` config below is the cheaper primary defence that stops
+ * the self-span from being created in the first place.
+ */
+export class SelfSpanFilteringExporter {
+    inner;
+    ingestHost;
+    constructor(inner, 
+    /** Bare ingest hostname (lower-case, no port), e.g. `ingest.heystack.dev`. */
+    ingestHost) {
+        this.inner = inner;
+        this.ingestHost = ingestHost;
+    }
+    export(spans, cb) {
+        const kept = this.ingestHost
+            ? spans.filter((s) => !isSelfSpanAttrs(s.attributes, this.ingestHost))
+            : spans;
+        // Nothing left to send: report success without a no-op POST (which would
+        // itself be a self-span and re-prime the loop).
+        if (kept.length === 0) {
+            cb({ code: ExportResultCode.SUCCESS });
+            return;
+        }
+        this.inner.export(kept, cb);
+    }
+    shutdown() {
+        return this.inner.shutdown();
+    }
+    forceFlush() {
+        return this.inner.forceFlush?.() ?? Promise.resolve();
+    }
+}
+/**
+ * Per-instrumentation config that tells the HTTP + undici auto-instrumentations
+ * to skip outbound requests to the ingest host, so the exporter's own POST is
+ * never turned into a span. Keyed by instrumentation package name; unknown keys
+ * are ignored by `getNodeAutoInstrumentations`, so this stays version-tolerant.
+ */
+function ingestIgnoreConfig(ingestHost) {
+    if (!ingestHost)
+        return {};
+    return {
+        "@opentelemetry/instrumentation-http": {
+            // RequestOptions carries host/hostname (and sometimes a full URL).
+            ignoreOutgoingRequestHook: (options) => {
+                const h = (options.hostname ?? options.host ?? "")
+                    .toString()
+                    .toLowerCase();
+                // host may include :port — compare on the bare hostname.
+                return h.split(":")[0] === ingestHost;
+            },
+        },
+        "@opentelemetry/instrumentation-undici": {
+            // Undici/fetch request: `.origin` is a full URL string, `.path` the path.
+            ignoreRequestHook: (req) => safeHostname(req.origin ?? "") === ingestHost,
+        },
+    };
+}
 /**
  * Process-level guard so SIGTERM/SIGINT handlers are registered AT MOST ONCE,
  * even if `initHeystack` is called repeatedly (e.g. Next dev server reloads).
@@ -26,12 +97,21 @@ export function initHeystack(o) {
     if (o.debug)
         diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);
     const cfg = buildExporterConfig(o);
+    const ingestHost = safeHostname(cfg.url);
+    // Primary defence: don't even create a span for the exporter's own POST.
+    // Only applies to our default auto-instrumentation set — a caller-supplied
+    // `instrumentations` array is left untouched (the exporter filter still
+    // protects it).
     const instrumentations = o.autoInstrument === false
         ? []
-        : (o.instrumentations ?? [getNodeAutoInstrumentations()]);
+        : (o.instrumentations ??
+            [getNodeAutoInstrumentations(ingestIgnoreConfig(ingestHost))]);
+    // Universal defence: filter any self-span at the exporter boundary, so the
+    // loop is killed regardless of which instrumentations are active.
+    const traceExporter = new SelfSpanFilteringExporter(new OTLPTraceExporter({ url: cfg.url, headers: cfg.headers }), ingestHost);
     const sdk = new NodeSDK({
         serviceName: o.service,
-        traceExporter: new OTLPTraceExporter({ url: cfg.url, headers: cfg.headers }),
+        traceExporter,
         instrumentations,
     });
     sdk.start();

package/dist/self-span.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Parse the hostname (no port) out of a URL, lower-cased; empty string if it
+ * can't be parsed. We compare on hostname rather than `host` so that an ingest
+ * URL like `ingest.heystack.dev` matches a captured span attribute of
+ * `ingest.heystack.dev:443` (and vice-versa).
+ */
+export declare function safeHostname(url: string): string;
+/**
+ * Strip a trailing `:port` from a bare host attribute and lower-case it, so a
+ * host-only attr like `ingest.heystack.dev:443` compares equal to the ingest
+ * hostname. IPv6 literals (`[::1]:443`) keep their bracketed form. Returns ""
+ * for anything that isn't a non-empty string.
+ */
+export declare function hostnameOf(hostAttr: unknown): string;
+/** Attributes that carry a full HTTP URL on a CLIENT/SERVER span. */
+export declare const HTTP_URL_ATTRS: readonly ["url.full", "http.url"];
+/** Host-only attributes (host[:port], no scheme/path). */
+export declare const HTTP_HOST_ATTRS: readonly ["server.address", "net.peer.name", "net.peer.hostname", "http.host", "peer.address"];
+/**
+ * True if `attrs` looks like a request to the configured ingest origin — i.e. it
+ * is (or could be) the exporter's own self-trace. For full-URL attributes we
+ * parse the URL and compare its `.hostname` (case-insensitive, port stripped) so
+ * a sibling domain like `myingest.heystack.dev` is NOT a false positive and an
+ * explicit port like `ingest.heystack.dev:443` IS matched. For host-only attrs
+ * we strip any `:port` and compare hostname equality.
+ *
+ * `ingestHost` must be a bare hostname (lower-case, no port), as produced by
+ * `safeHostname(cfg.url)`.
+ */
+export declare function isSelfSpanAttrs(attrs: Record<string, unknown>, ingestHost: string): boolean;

package/dist/self-span.js

@@ -0,0 +1,83 @@
+// ---------------------------------------------------------------------------
+// Self-span detection (shared by /workers and /node)
+//
+// When a runtime auto-instruments outbound HTTP (undici/fetch on Next/OpenNext,
+// the http module on Node), the exporter's own POST to `/v1/traces` becomes a
+// CLIENT span → exported → re-captured → a sustained loop. These helpers detect
+// a span that targets the configured ingest origin so we can drop it before it
+// feeds the loop. Pure string logic — no runtime imports — safe in any entry
+// (including the WinterCG-only `/workers` build).
+// ---------------------------------------------------------------------------
+/**
+ * Parse the hostname (no port) out of a URL, lower-cased; empty string if it
+ * can't be parsed. We compare on hostname rather than `host` so that an ingest
+ * URL like `ingest.heystack.dev` matches a captured span attribute of
+ * `ingest.heystack.dev:443` (and vice-versa).
+ */
+export function safeHostname(url) {
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Strip a trailing `:port` from a bare host attribute and lower-case it, so a
+ * host-only attr like `ingest.heystack.dev:443` compares equal to the ingest
+ * hostname. IPv6 literals (`[::1]:443`) keep their bracketed form. Returns ""
+ * for anything that isn't a non-empty string.
+ */
+export function hostnameOf(hostAttr) {
+    if (typeof hostAttr !== "string" || hostAttr === "")
+        return "";
+    const v = hostAttr.trim();
+    // Bracketed IPv6, optionally with a port: `[::1]` or `[::1]:443`.
+    if (v.startsWith("[")) {
+        const close = v.indexOf("]");
+        if (close !== -1)
+            return v.slice(0, close + 1).toLowerCase();
+        return v.toLowerCase();
+    }
+    // Strip a single trailing :port (host:port). A bare hostname has no colon.
+    const colon = v.lastIndexOf(":");
+    if (colon !== -1 && v.indexOf(":") === colon) {
+        return v.slice(0, colon).toLowerCase();
+    }
+    return v.toLowerCase();
+}
+/** Attributes that carry a full HTTP URL on a CLIENT/SERVER span. */
+export const HTTP_URL_ATTRS = ["url.full", "http.url"];
+/** Host-only attributes (host[:port], no scheme/path). */
+export const HTTP_HOST_ATTRS = [
+    "server.address",
+    "net.peer.name",
+    "net.peer.hostname",
+    "http.host",
+    "peer.address",
+];
+/**
+ * True if `attrs` looks like a request to the configured ingest origin — i.e. it
+ * is (or could be) the exporter's own self-trace. For full-URL attributes we
+ * parse the URL and compare its `.hostname` (case-insensitive, port stripped) so
+ * a sibling domain like `myingest.heystack.dev` is NOT a false positive and an
+ * explicit port like `ingest.heystack.dev:443` IS matched. For host-only attrs
+ * we strip any `:port` and compare hostname equality.
+ *
+ * `ingestHost` must be a bare hostname (lower-case, no port), as produced by
+ * `safeHostname(cfg.url)`.
+ */
+export function isSelfSpanAttrs(attrs, ingestHost) {
+    if (!ingestHost)
+        return false;
+    for (const key of HTTP_URL_ATTRS) {
+        const v = attrs[key];
+        if (typeof v === "string" && safeHostname(v) === ingestHost)
+            return true;
+    }
+    for (const key of HTTP_HOST_ATTRS) {
+        if (hostnameOf(attrs[key]) === ingestHost)
+            return true;
+    }
+    return false;
+}

package/dist/workers.js

@@ -14,6 +14,7 @@ import { Resource } from "@opentelemetry/resources";
 import { BasicTracerProvider, SimpleSpanProcessor, } from "@opentelemetry/sdk-trace-base";
 import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 import { buildExporterConfig } from "./core.js";
+import { isSelfSpanAttrs, safeHostname } from "./self-span.js";
 // `ExportResult` / `ExportResultCode` mirror `@opentelemetry/core`. We define
 // them inline (structurally identical) rather than import them: core is only a
 // transitive dep of sdk-trace-base and isn't reliably resolvable, and keeping it
@@ -147,76 +148,9 @@ export function serializeSpans(spans) {
 // targets the ingest origin, so an upstream instrumentation that ignores
 // suppression still can't feed the loop.
 // ---------------------------------------------------------------------------
-/**
- * Parse the hostname (no port) out of a URL, lower-cased; empty string if it
- * can't be parsed. We compare on hostname rather than `host` so that an ingest
- * URL like `ingest.heystack.dev` matches a captured span attribute of
- * `ingest.heystack.dev:443` (and vice-versa).
- */
-function safeHostname(url) {
-    try {
-        return new URL(url).hostname.toLowerCase();
-    }
-    catch {
-        return "";
-    }
-}
-/**
- * Strip a trailing `:port` from a bare host attribute and lower-case it, so a
- * host-only attr like `ingest.heystack.dev:443` compares equal to the ingest
- * hostname. IPv6 literals (`[::1]:443`) keep their bracketed form. Returns ""
- * for anything that isn't a non-empty string.
- */
-function hostnameOf(hostAttr) {
-    if (typeof hostAttr !== "string" || hostAttr === "")
-        return "";
-    const v = hostAttr.trim();
-    // Bracketed IPv6, optionally with a port: `[::1]` or `[::1]:443`.
-    if (v.startsWith("[")) {
-        const close = v.indexOf("]");
-        if (close !== -1)
-            return v.slice(0, close + 1).toLowerCase();
-        return v.toLowerCase();
-    }
-    // Strip a single trailing :port (host:port). A bare hostname has no colon.
-    const colon = v.lastIndexOf(":");
-    if (colon !== -1 && v.indexOf(":") === colon) {
-        return v.slice(0, colon).toLowerCase();
-    }
-    return v.toLowerCase();
-}
-/** Attributes that carry a full HTTP URL on a CLIENT/SERVER span. */
-const HTTP_URL_ATTRS = ["url.full", "http.url"];
-/** Host-only attributes (host[:port], no scheme/path). */
-const HTTP_HOST_ATTRS = [
-    "server.address",
-    "net.peer.name",
-    "net.peer.hostname",
-    "http.host",
-    "peer.address",
-];
-/**
- * True if `span` looks like a request to the configured ingest origin — i.e. it
- * is (or could be) the exporter's own self-trace. For full-URL attributes we
- * parse the URL and compare its `.hostname` (case-insensitive, port stripped) so
- * a sibling domain like `myingest.heystack.dev` is NOT a false positive and an
- * explicit port like `ingest.heystack.dev:443` IS matched. For host-only attrs
- * we strip any `:port` and compare hostname equality.
- */
-function isSelfSpanAttrs(attrs, ingestHost) {
-    if (!ingestHost)
-        return false;
-    for (const key of HTTP_URL_ATTRS) {
-        const v = attrs[key];
-        if (typeof v === "string" && safeHostname(v) === ingestHost)
-            return true;
-    }
-    for (const key of HTTP_HOST_ATTRS) {
-        if (hostnameOf(attrs[key]) === ingestHost)
-            return true;
-    }
-    return false;
-}
+// `safeHostname` / `isSelfSpanAttrs` live in the shared, runtime-agnostic
+// `./self-span.js` module (also used by `/node`). They are pure string logic
+// with no runtime imports, so importing them keeps this entry WinterCG-safe.
 function isSelfSpan(span, ingestHost) {
     return isSelfSpanAttrs(span.attributes, ingestHost);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heystack/otel",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Runtime-aware OpenTelemetry tracing that exports to Heystack (Node, Next.js, Workers).",
   "license": "MIT",
   "type": "module",
@@ -60,5 +60,10 @@
     "typescript": "^5.7.0",
     "@types/node": "^22.0.0",
     "@cloudflare/workers-types": "^4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/heystack-hq/heystack.git",
+    "directory": "packages/otel-sdk"
   }
 }