@glassflow-ai/rius 0.1.0 → 0.2.2

package/README.md

@@ -233,6 +233,11 @@ variables, then the defaults below.
 | `sampleRate`       | `RIUS_SAMPLE_RATE`       | `1.0`                                         |
 | `captureContent`   | `RIUS_CAPTURE_CONTENT`   | `true`                                        |
 | `mask`             | (options only)           | none                                          |
+| `heartbeat`        | `RIUS_HEARTBEAT`         | `true`                                        |
+| `heartbeatInterval` | `RIUS_HEARTBEAT_INTERVAL` | `15` (seconds; clamped 5-300)               |
+| `agentName`        | `RIUS_AGENT_NAME`        | `serviceName`                                 |
+| `partialSpans`     | `RIUS_PARTIAL_SPANS`     | `false`                                       |
+| `partialSpansDelay` | `RIUS_PARTIAL_SPANS_DELAY` | `0` (seconds; clamped 0-60)                |
 
 Traces are posted to `<endpoint>/v1/traces`.
 
@@ -255,6 +260,50 @@ optional integration is loaded, so no third-party module is patched in your
 process. `client.ready` resolves to an empty list. Spans can still be
 created and are simply dropped.
 
+## Agent liveness
+
+Traces only leave the process when a span ends, so an idle-but-alive agent
+and a crashed one look identical from the outside. Two independent
+mechanisms close that gap: a heartbeat that reports the process is still
+running, and partial spans that leave a durable trace of in-flight work if
+the process disappears before finishing it.
+
+### Heartbeat
+
+With `heartbeat: true` (the default), the SDK posts to `<endpoint>/v1/heartbeat`
+for the life of the process: an immediate first ping when `init()` runs,
+then one every `heartbeatInterval` seconds (default 15, clamped to 5-300).
+Each ping reports the count of currently open root spans, which is what
+lets the backend tell a live-but-idle agent from one that has vanished.
+
+The final ping, carrying `stopped: true`, is sent by `client.shutdown()`.
+The SDK also makes a best-effort attempt to send it when the process ends
+naturally, on Node's `beforeExit` event. An application that never calls
+`shutdown()` and exits abruptly, killed, crashed, or via `process.exit()`,
+misses that last ping and reports as gone rather than stopped, the same way
+a hard-killed agent looks in any language. Call `client.shutdown()` on a
+graceful exit if you want that distinction to show up.
+
+The heartbeat never keeps the process alive, its timer is unref'd, and never
+throws into your code; delivery failures are logged once per client and
+silent after that. `agentName` identifies the agent in heartbeat payloads
+and defaults to `serviceName`.
+
+### Partial spans
+
+With `partialSpans: true` (default `false`), every sampled span additionally
+exports a content-free snapshot the moment it starts, on top of the normal
+export when it ends. The snapshot carries only identity and taxonomy
+attributes, trace id, span id, name and timestamps, never content, whatever
+instrumentation set on the span. The backend stores it as an unfinished row
+and replaces it with the real span at end, so a snapshot that is never
+replaced is the durable record of what a crashed agent was doing.
+
+`partialSpansDelay` (default `0`, clamped to 0-60 seconds) debounces the
+snapshot: it is held for that long and only sent if the span is still open
+once the delay elapses, so a span that finishes quickly costs zero network
+calls.
+
 ## Reliability
 
 Export is designed to never block or crash your application:

package/dist/index.cjs

@@ -20,6 +20,16 @@ var __copyProps = (to, from, except, desc) => {
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl, importMetaUrl;
+var init_cjs_shims = __esm({
+  "node_modules/tsup/assets/cjs_shims.js"() {
+    "use strict";
+    getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+    importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+  }
+});
+
 // src/config.ts
 function bool(name, raw, fallback) {
   if (raw === void 0) return fallback;
@@ -37,24 +47,64 @@ function rate(raw, fallback) {
   if (Number.isNaN(parsed)) return fallback;
   return Math.min(1, Math.max(0, parsed));
 }
+function seconds(raw, fallback) {
+  if (raw === void 0) return fallback;
+  const parsed = Number.parseFloat(raw);
+  if (Number.isNaN(parsed)) return fallback;
+  return parsed;
+}
+function clamp(name, value, min, max) {
+  if (value >= min && value <= max) return value;
+  const clamped = Math.min(Math.max(value, min), max);
+  console.warn(`[rius] ${name}=${value} is outside [${min}, ${max}]; clamped to ${clamped}.`);
+  return clamped;
+}
 function resolveConfig(options = {}, env = process.env) {
   const endpoint = (options.endpoint ?? env.RIUS_ENDPOINT ?? DEFAULT_ENDPOINT).replace(/\/+$/, "");
+  const serviceName = options.serviceName ?? env.RIUS_SERVICE_NAME ?? DEFAULT_SERVICE_NAME;
+  const heartbeatIntervalSeconds = clamp(
+    "heartbeatInterval",
+    options.heartbeatInterval ?? seconds(env.RIUS_HEARTBEAT_INTERVAL, DEFAULT_HEARTBEAT_INTERVAL),
+    HEARTBEAT_INTERVAL_MIN,
+    HEARTBEAT_INTERVAL_MAX
+  );
+  const partialSpansDelaySeconds = clamp(
+    "partialSpansDelay",
+    options.partialSpansDelay ?? seconds(env.RIUS_PARTIAL_SPANS_DELAY, DEFAULT_PARTIAL_SPANS_DELAY),
+    PARTIAL_SPANS_DELAY_MIN,
+    PARTIAL_SPANS_DELAY_MAX
+  );
   return {
     endpoint,
     apiKey: options.apiKey ?? env.RIUS_API_KEY,
-    serviceName: options.serviceName ?? env.RIUS_SERVICE_NAME ?? DEFAULT_SERVICE_NAME,
+    serviceName,
     disabled: options.disabled ?? bool("RIUS_DISABLED", env.RIUS_DISABLED, false),
     sampleRate: options.sampleRate ?? rate(env.RIUS_SAMPLE_RATE, 1),
     captureContent: options.captureContent ?? bool("RIUS_CAPTURE_CONTENT", env.RIUS_CAPTURE_CONTENT, true),
-    mask: options.mask
+    mask: options.mask,
+    heartbeat: options.heartbeat ?? bool("RIUS_HEARTBEAT", env.RIUS_HEARTBEAT, true),
+    heartbeatIntervalMs: heartbeatIntervalSeconds * 1e3,
+    heartbeatEndpoint: `${endpoint}/v1/heartbeat`,
+    // Empty falls through to serviceName rather than shipping a blank identity
+    // on every heartbeat payload, so `??` would be wrong here.
+    agentName: options.agentName || env.RIUS_AGENT_NAME || serviceName,
+    partialSpans: options.partialSpans ?? bool("RIUS_PARTIAL_SPANS", env.RIUS_PARTIAL_SPANS, false),
+    partialSpansDelayMs: partialSpansDelaySeconds * 1e3
   };
 }
-var DEFAULT_ENDPOINT, DEFAULT_SERVICE_NAME, AFFIRMATIVE, NEGATIVE;
+var DEFAULT_ENDPOINT, DEFAULT_SERVICE_NAME, HEARTBEAT_INTERVAL_MIN, HEARTBEAT_INTERVAL_MAX, DEFAULT_HEARTBEAT_INTERVAL, PARTIAL_SPANS_DELAY_MIN, PARTIAL_SPANS_DELAY_MAX, DEFAULT_PARTIAL_SPANS_DELAY, AFFIRMATIVE, NEGATIVE;
 var init_config = __esm({
   "src/config.ts"() {
     "use strict";
+    init_cjs_shims();
     DEFAULT_ENDPOINT = "https://ingest.eu.console.rius-glassflow.com";
     DEFAULT_SERVICE_NAME = "unknown_service";
+    HEARTBEAT_INTERVAL_MIN = 5;
+    HEARTBEAT_INTERVAL_MAX = 300;
+    DEFAULT_HEARTBEAT_INTERVAL = 15;
+    PARTIAL_SPANS_DELAY_MIN = 0;
+    PARTIAL_SPANS_DELAY_MAX = 60;
+    DEFAULT_PARTIAL_SPANS_DELAY = 0;
     AFFIRMATIVE = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
     NEGATIVE = /* @__PURE__ */ new Set(["0", "false", "no", "off"]);
   }
@@ -65,6 +115,7 @@ var DelegatingSpanProcessor;
 var init_delegatingProcessor = __esm({
   "src/delegatingProcessor.ts"() {
     "use strict";
+    init_cjs_shims();
     DelegatingSpanProcessor = class {
       delegates = [];
       add(processor) {
@@ -102,6 +153,7 @@ var ExportResultCode;
 var init_ExportResult = __esm({
   "node_modules/@opentelemetry/core/build/esm/ExportResult.js"() {
     "use strict";
+    init_cjs_shims();
     (function(ExportResultCode2) {
       ExportResultCode2[ExportResultCode2["SUCCESS"] = 0] = "SUCCESS";
       ExportResultCode2[ExportResultCode2["FAILED"] = 1] = "FAILED";
@@ -113,6 +165,7 @@ var init_ExportResult = __esm({
 var init_esm = __esm({
   "node_modules/@opentelemetry/core/build/esm/index.js"() {
     "use strict";
+    init_cjs_shims();
     init_ExportResult();
   }
 });
@@ -122,6 +175,7 @@ var ExportOutcomeExporter;
 var init_exportHealth = __esm({
   "src/exportHealth.ts"() {
     "use strict";
+    init_cjs_shims();
     init_esm();
     ExportOutcomeExporter = class {
       constructor(inner, onFirstFailure = (m) => console.warn(m)) {
@@ -164,6 +218,134 @@ var init_exportHealth = __esm({
   }
 });
 
+// src/heartbeat.ts
+function httpTransport(url, headers) {
+  return async (payload, timeoutMs) => {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...headers },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    await response.body?.cancel().catch(() => {
+    });
+    if (!response.ok) {
+      throw new Error(`heartbeat POST ${url} returned ${response.status}`);
+    }
+  };
+}
+var import_node_crypto, import_node_module, PAYLOAD_VERSION, OPEN_TRACES_CAP, DEFAULT_PING_TIMEOUT_MS, DEFAULT_FINAL_PING_TIMEOUT_MS, SDK_VERSION, OpenRootSpanTracker, HeartbeatSender;
+var init_heartbeat = __esm({
+  "src/heartbeat.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_node_crypto = require("crypto");
+    import_node_module = require("module");
+    PAYLOAD_VERSION = 1;
+    OPEN_TRACES_CAP = 32;
+    DEFAULT_PING_TIMEOUT_MS = 3e3;
+    DEFAULT_FINAL_PING_TIMEOUT_MS = 1e3;
+    SDK_VERSION = (() => {
+      try {
+        const pkg = (0, import_node_module.createRequire)(importMetaUrl)("../package.json");
+        return pkg.version ?? "0.0.0";
+      } catch {
+        return "0.0.0";
+      }
+    })();
+    OpenRootSpanTracker = class {
+      // trace id (32-hex) -> count of open root spans in that trace. A trace id
+      // normally has one root, but the count guards against duplicates.
+      open = /* @__PURE__ */ new Map();
+      onStart(span, _parentContext) {
+        if (span.parentSpanContext !== void 0) return;
+        const traceId = span.spanContext().traceId;
+        this.open.set(traceId, (this.open.get(traceId) ?? 0) + 1);
+      }
+      onEnd(span) {
+        if (span.parentSpanContext !== void 0) return;
+        const traceId = span.spanContext().traceId;
+        const count = (this.open.get(traceId) ?? 0) - 1;
+        if (count <= 0) {
+          this.open.delete(traceId);
+        } else {
+          this.open.set(traceId, count);
+        }
+      }
+      /** Trace ids of currently-open root spans, in the order they opened. */
+      openTraceIds() {
+        return [...this.open.keys()];
+      }
+      async forceFlush() {
+      }
+      async shutdown() {
+      }
+    };
+    HeartbeatSender = class {
+      /** Identity of one process lifetime, fresh per sender. */
+      instanceId = (0, import_node_crypto.randomUUID)();
+      agentName;
+      tracker;
+      intervalMs;
+      pingTimeoutMs;
+      finalPingTimeoutMs;
+      send;
+      timer;
+      stopped = false;
+      deliveryWarned = false;
+      constructor(opts) {
+        this.agentName = opts.agentName;
+        this.tracker = opts.tracker;
+        this.intervalMs = opts.intervalMs;
+        this.pingTimeoutMs = opts.pingTimeoutMs ?? DEFAULT_PING_TIMEOUT_MS;
+        this.finalPingTimeoutMs = opts.finalPingTimeoutMs ?? DEFAULT_FINAL_PING_TIMEOUT_MS;
+        this.send = opts.transport ?? httpTransport(opts.url, opts.headers);
+      }
+      /** Starts pinging: an immediate first ping, then every `intervalMs`. */
+      start() {
+        void this.ping(this.pingTimeoutMs, false);
+        const timer = setInterval(() => void this.ping(this.pingTimeoutMs, false), this.intervalMs);
+        if (typeof timer.unref === "function") timer.unref();
+        this.timer = timer;
+      }
+      /** Stops the interval and sends the final `stopped: true` ping. Idempotent. */
+      async stop() {
+        if (this.stopped) return;
+        this.stopped = true;
+        if (this.timer !== void 0) clearInterval(this.timer);
+        await this.ping(this.finalPingTimeoutMs, true);
+      }
+      buildPayload(stopped) {
+        const openIds = this.tracker.openTraceIds();
+        const payload = {
+          v: PAYLOAD_VERSION,
+          instance_id: this.instanceId,
+          agent_name: this.agentName,
+          // RFC3339 UTC with millisecond precision and a Z suffix, already.
+          sent_at: (/* @__PURE__ */ new Date()).toISOString(),
+          sdk_language: "typescript",
+          sdk_version: SDK_VERSION,
+          open_traces: openIds.slice(0, OPEN_TRACES_CAP),
+          open_trace_count: openIds.length
+        };
+        if (stopped) payload.stopped = true;
+        return payload;
+      }
+      async ping(timeoutMs, stopped) {
+        try {
+          await this.send(this.buildPayload(stopped), timeoutMs);
+        } catch (error) {
+          if (!this.deliveryWarned) {
+            this.deliveryWarned = true;
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`[rius] heartbeat delivery failed (${message}); further failures are silent.`);
+          }
+        }
+      }
+    };
+  }
+});
+
 // src/semconv.ts
 function kindAttributes(kind) {
   const attributes = { [OPENINFERENCE_SPAN_KIND]: kind };
@@ -171,10 +353,11 @@ function kindAttributes(kind) {
   if (operation !== void 0) attributes[GEN_AI_OPERATION_NAME] = operation;
   return attributes;
 }
-var TRACER_NAME, OPENINFERENCE_SPAN_KIND, INPUT_VALUE, OUTPUT_VALUE, GEN_AI_OPERATION_NAME, GEN_AI_PROVIDER_NAME, GEN_AI_REQUEST_MODEL, GEN_AI_RESPONSE_MODEL, GEN_AI_USAGE_INPUT_TOKENS, GEN_AI_USAGE_OUTPUT_TOKENS, GEN_AI_INPUT_MESSAGES, GEN_AI_OUTPUT_MESSAGES, GEN_AI_RESPONSE_FINISH_REASONS, GEN_AI_TOOL_NAME, GEN_AI_REQUEST_PREFIX, MCP_RESULT_TYPE, GEN_AI_FIRST_TOKEN_EVENT, SpanKind, OPERATION_BY_KIND, CONTENT_ATTRIBUTES, CONTENT_ATTRIBUTE_PREFIXES, CONTENT_ATTRIBUTE_SUFFIXES;
+var TRACER_NAME, OPENINFERENCE_SPAN_KIND, INPUT_VALUE, OUTPUT_VALUE, GEN_AI_OPERATION_NAME, GEN_AI_PROVIDER_NAME, GEN_AI_REQUEST_MODEL, GEN_AI_RESPONSE_MODEL, GEN_AI_USAGE_INPUT_TOKENS, GEN_AI_USAGE_OUTPUT_TOKENS, GEN_AI_INPUT_MESSAGES, GEN_AI_OUTPUT_MESSAGES, GEN_AI_RESPONSE_FINISH_REASONS, GEN_AI_TOOL_NAME, GEN_AI_REQUEST_PREFIX, MCP_RESULT_TYPE, GEN_AI_FIRST_TOKEN_EVENT, SpanKind, OPERATION_BY_KIND, CONTENT_ATTRIBUTES, CONTENT_ATTRIBUTE_PREFIXES, CONTENT_ATTRIBUTE_SUFFIXES, GLASSFLOW_SPAN_PENDING, PENDING_IDENTITY_ATTRIBUTES, PENDING_IDENTITY_PREFIXES;
 var init_semconv = __esm({
   "src/semconv.ts"() {
     "use strict";
+    init_cjs_shims();
     TRACER_NAME = "glassflow";
     OPENINFERENCE_SPAN_KIND = "openinference.span.kind";
     INPUT_VALUE = "input.value";
@@ -239,6 +422,14 @@ var init_semconv = __esm({
       ".document.content",
       ".embedding.text"
     ];
+    GLASSFLOW_SPAN_PENDING = "glassflow.span.pending";
+    PENDING_IDENTITY_ATTRIBUTES = /* @__PURE__ */ new Set([
+      OPENINFERENCE_SPAN_KIND,
+      GEN_AI_OPERATION_NAME,
+      GEN_AI_PROVIDER_NAME,
+      GEN_AI_TOOL_NAME
+    ]);
+    PENDING_IDENTITY_PREFIXES = [GEN_AI_REQUEST_PREFIX];
   }
 });
 
@@ -267,6 +458,7 @@ function toAttributeValue(value) {
 var init_serde = __esm({
   "src/serde.ts"() {
     "use strict";
+    init_cjs_shims();
   }
 });
 
@@ -303,6 +495,7 @@ var import_api, Observation;
 var init_spans = __esm({
   "src/spans.ts"() {
     "use strict";
+    init_cjs_shims();
     import_api = require("@opentelemetry/api");
     init_client();
     init_semconv();
@@ -396,6 +589,7 @@ var INPUT_REQUIRED;
 var init_instrumentationMcp = __esm({
   "src/instrumentationMcp.ts"() {
     "use strict";
+    init_cjs_shims();
     init_semconv();
     init_spans();
     INPUT_REQUIRED = "input_required";
@@ -446,7 +640,7 @@ function warnBroken(subject, error) {
 function cachedCjsExports(pkg, toPatchable) {
   let cache;
   try {
-    cache = (0, import_node_module.createRequire)((0, import_node_path.join)(process.cwd(), "noop.js")).cache;
+    cache = (0, import_node_module2.createRequire)((0, import_node_path.join)(process.cwd(), "noop.js")).cache;
   } catch {
     return void 0;
   }
@@ -511,11 +705,12 @@ async function enableInstrumentations(sink, tracerProvider, names) {
   }
   return enabled;
 }
-var import_node_module, import_node_path, import_instrumentation, dynamicImport, REGISTRY;
+var import_node_module2, import_node_path, import_instrumentation, dynamicImport, REGISTRY;
 var init_instrumentation = __esm({
   "src/instrumentation.ts"() {
     "use strict";
-    import_node_module = require("module");
+    init_cjs_shims();
+    import_node_module2 = require("module");
     import_node_path = require("path");
     import_instrumentation = require("@opentelemetry/instrumentation");
     dynamicImport = new Function("s", "return import(s)");
@@ -611,6 +806,7 @@ var import_api2, EXCEPTION_EVENT_NAME, EXCEPTION_CONTENT_KEYS, MaskingSpanExport
 var init_masking = __esm({
   "src/masking.ts"() {
     "use strict";
+    init_cjs_shims();
     import_api2 = require("@opentelemetry/api");
     init_semconv();
     init_serde();
@@ -673,6 +869,93 @@ var init_masking = __esm({
   }
 });
 
+// src/pending.ts
+function identityAttributes(attributes) {
+  if (!attributes) return {};
+  const result = {};
+  for (const [key, value] of Object.entries(attributes)) {
+    if (PENDING_IDENTITY_ATTRIBUTES.has(key) || PENDING_IDENTITY_PREFIXES.some((p) => key.startsWith(p))) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function buildSnapshot(span) {
+  const attributes = identityAttributes(span.attributes);
+  attributes[GLASSFLOW_SPAN_PENDING] = true;
+  return {
+    name: span.name,
+    kind: span.kind,
+    spanContext: () => span.spanContext(),
+    parentSpanContext: span.parentSpanContext,
+    startTime: span.startTime,
+    endTime: span.startTime,
+    duration: [0, 0],
+    status: { code: import_api3.SpanStatusCode.UNSET },
+    attributes,
+    links: [],
+    events: [],
+    resource: span.resource,
+    instrumentationScope: span.instrumentationScope,
+    droppedAttributesCount: 0,
+    droppedEventsCount: 0,
+    droppedLinksCount: 0,
+    ended: true
+  };
+}
+function spanKey(context) {
+  return `${context.traceId}:${context.spanId}`;
+}
+var import_api3, PendingSpanProcessor;
+var init_pending = __esm({
+  "src/pending.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_api3 = require("@opentelemetry/api");
+    init_semconv();
+    PendingSpanProcessor = class {
+      delegate;
+      delayMs;
+      scheduled = /* @__PURE__ */ new Map();
+      constructor(delegate, opts) {
+        this.delegate = delegate;
+        this.delayMs = opts?.delayMs ?? 0;
+      }
+      onStart(span, _parentContext) {
+        if (!span.isRecording()) return;
+        const snapshot = buildSnapshot(span);
+        if (this.delayMs <= 0) {
+          this.delegate.onEnd(snapshot);
+          return;
+        }
+        const key = spanKey(span.spanContext());
+        const timer = setTimeout(() => {
+          this.scheduled.delete(key);
+          try {
+            this.delegate.onEnd(snapshot);
+          } catch {
+          }
+        }, this.delayMs);
+        if (typeof timer.unref === "function") timer.unref();
+        this.scheduled.set(key, timer);
+      }
+      onEnd(span) {
+        const key = spanKey(span.spanContext());
+        const timer = this.scheduled.get(key);
+        if (timer === void 0) return;
+        clearTimeout(timer);
+        this.scheduled.delete(key);
+      }
+      async shutdown() {
+        for (const timer of this.scheduled.values()) clearTimeout(timer);
+        this.scheduled.clear();
+      }
+      async forceFlush() {
+      }
+    };
+  }
+});
+
 // src/client.ts
 function init(options = {}) {
   if (globalClient !== void 0) {
@@ -683,18 +966,23 @@ function init(options = {}) {
   }
   const config = resolveConfig(options);
   const processors = new DelegatingSpanProcessor();
+  const authHeaders = config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {};
   let health;
   if (!config.disabled) {
     const base = options.spanExporter ?? new import_exporter_trace_otlp_http.OTLPTraceExporter({
       url: `${config.endpoint}/v1/traces`,
-      headers: config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : void 0
+      headers: config.apiKey ? authHeaders : void 0
     });
     health = new ExportOutcomeExporter(base);
     const exporter = !config.captureContent || config.mask !== void 0 ? new MaskingSpanExporter(health, {
       captureContent: config.captureContent,
       mask: config.mask
     }) : health;
-    processors.add(new import_sdk_trace_base.BatchSpanProcessor(exporter));
+    const batch = new import_sdk_trace_base.BatchSpanProcessor(exporter);
+    if (config.partialSpans) {
+      processors.add(new PendingSpanProcessor(batch, { delayMs: config.partialSpansDelayMs }));
+    }
+    processors.add(batch);
   }
   const provider = new import_sdk_trace_node.NodeTracerProvider({
     resource: (0, import_resources.resourceFromAttributes)({ [import_semantic_conventions.ATTR_SERVICE_NAME]: config.serviceName }),
@@ -708,17 +996,37 @@ function init(options = {}) {
   });
   const ready = config.disabled ? Promise.resolve([]) : enableInstrumentations(processors, provider).catch(() => []);
   provider.register();
-  globalClient = createClient({ provider, processors, health, ready });
+  let heartbeat;
+  if (config.heartbeat && !config.disabled) {
+    const tracker = new OpenRootSpanTracker();
+    processors.add(tracker);
+    const sender = new HeartbeatSender({
+      url: config.heartbeatEndpoint,
+      headers: authHeaders,
+      intervalMs: config.heartbeatIntervalMs,
+      agentName: config.agentName,
+      tracker,
+      transport: options.heartbeatTransport
+    });
+    sender.start();
+    const beforeExitHandler = () => {
+      void sender.stop();
+    };
+    process.once("beforeExit", beforeExitHandler);
+    heartbeat = { sender, beforeExitHandler };
+  }
+  globalClient = createClient({ provider, processors, health, ready, heartbeat });
   return globalClient;
 }
 function getTracer() {
-  return import_api3.trace.getTracer(TRACER_NAME);
+  return import_api4.trace.getTracer(TRACER_NAME);
 }
-var import_api3, import_exporter_trace_otlp_http, import_resources, import_sdk_trace_base, import_sdk_trace_node, import_semantic_conventions, sinks, createClient, RiusClient, globalClient;
+var import_api4, import_exporter_trace_otlp_http, import_resources, import_sdk_trace_base, import_sdk_trace_node, import_semantic_conventions, sinks, heartbeats, createClient, RiusClient, globalClient;
 var init_client = __esm({
   "src/client.ts"() {
     "use strict";
-    import_api3 = require("@opentelemetry/api");
+    init_cjs_shims();
+    import_api4 = require("@opentelemetry/api");
     import_exporter_trace_otlp_http = require("@opentelemetry/exporter-trace-otlp-http");
     import_resources = require("@opentelemetry/resources");
     import_sdk_trace_base = require("@opentelemetry/sdk-trace-base");
@@ -727,10 +1035,13 @@ var init_client = __esm({
     init_config();
     init_delegatingProcessor();
     init_exportHealth();
+    init_heartbeat();
     init_instrumentation();
     init_masking();
+    init_pending();
     init_semconv();
     sinks = /* @__PURE__ */ new WeakMap();
+    heartbeats = /* @__PURE__ */ new WeakMap();
     RiusClient = class _RiusClient {
       provider;
       health;
@@ -741,6 +1052,7 @@ var init_client = __esm({
         this.health = parts.health;
         this.ready = parts.ready;
         sinks.set(this, parts.processors);
+        if (parts.heartbeat) heartbeats.set(this, parts.heartbeat);
       }
       static {
         createClient = (parts) => new _RiusClient(parts);
@@ -753,14 +1065,25 @@ var init_client = __esm({
       /**
        * Drains and tears down the provider, then releases the global registration
        * so a later init() can reconfigure the SDK.
+       *
+       * The heartbeat's final `stopped: true` ping is sent before the provider
+       * shuts down, so the backend hears "stopped" while the trace pipeline can
+       * still export it. Idempotent: `sender.stop()` no-ops on a second call, and
+       * the `beforeExit` listener is removed here so repeated init/shutdown
+       * cycles never leak listeners.
        */
       async shutdown() {
+        const heartbeat = heartbeats.get(this);
+        if (heartbeat) {
+          process.removeListener("beforeExit", heartbeat.beforeExitHandler);
+          await heartbeat.sender.stop();
+        }
         try {
           await this.provider.shutdown();
         } finally {
           if (globalClient === this) {
             globalClient = void 0;
-            import_api3.trace.disable();
+            import_api4.trace.disable();
           }
         }
       }
@@ -785,9 +1108,11 @@ __export(index_exports, {
   startSpan: () => startSpan
 });
 module.exports = __toCommonJS(index_exports);
+init_cjs_shims();
 init_client();
 
 // src/generation.ts
+init_cjs_shims();
 init_client();
 init_semconv();
 init_serde();
@@ -875,6 +1200,7 @@ function startAsCurrentGeneration(name, optionsOrFn, maybeFn) {
 }
 
 // src/observe.ts
+init_cjs_shims();
 init_spans();
 function observe(fn, options = {}) {
   const name = options.name ?? (fn.name || "anonymous");
@@ -896,7 +1222,7 @@ function observe(fn, options = {}) {
 // src/index.ts
 init_semconv();
 init_spans();
-var VERSION = "0.1.0";
+var VERSION = "0.2.2";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Generation,