@foam-ai/node 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -0,0 +1,123 @@
+# @foam-ai/node
+
+Foam observability SDK for Node.js. Sends traces, logs, and metrics to Foam with zero configuration overhead.
+
+## Install
+
+```bash
+npm install @foam-ai/node
+```
+
+## Quick start
+
+Call `init()` as early as possible in your application entry point:
+
+```typescript
+import foam from '@foam-ai/node';
+
+foam.init({
+  apiKey: process.env.FOAM_API_KEY,
+  serviceName: 'my-service',
+  isProduction: process.env.NODE_ENV === 'production',
+});
+```
+
+That's it. In production, Foam will automatically collect:
+
+- **Traces** — distributed traces via OpenTelemetry
+- **Logs** — console.log/info/error/warn/debug output
+- **Metrics** — runtime and custom metrics
+- **Uncaught errors** — process-level `uncaughtException` and `unhandledRejection`
+
+In non-production environments, `init()` is a silent no-op.
+
+## Capturing errors
+
+Unhandled exceptions and rejections are captured automatically. For caught errors you want to report, use `captureException`:
+
+```typescript
+import { captureException } from '@foam-ai/node';
+
+try {
+  await chargeCustomer(order);
+} catch (err) {
+  captureException(err);
+  return res.status(500).json({ error: 'Payment failed' });
+}
+```
+
+`captureException` works with or without an active trace span. It always emits an OpenTelemetry log record so errors reach Foam regardless of instrumentation setup.
+
+## Auto-instrumentation (optional)
+
+By default, no auto-instrumentations are registered. This keeps the SDK webpack/Turbopack-safe with no bundler configuration needed.
+
+For plain Node.js servers (Express, Fastify, etc.), you can opt into automatic HTTP, DNS, and framework instrumentation:
+
+```typescript
+import foam from '@foam-ai/node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+
+foam.init({
+  apiKey: process.env.FOAM_API_KEY,
+  serviceName: 'my-api',
+  isProduction: process.env.NODE_ENV === 'production',
+  instrumentations: getNodeAutoInstrumentations(),
+});
+```
+
+```bash
+npm install @opentelemetry/auto-instrumentations-node
+```
+
+## Next.js
+
+In a Next.js app, create an `instrumentation.ts` file at the project root:
+
+```typescript
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    const foam = await import('@foam-ai/node');
+    foam.init({
+      apiKey: process.env.FOAM_API_KEY!,
+      serviceName: 'my-nextjs-app',
+      isProduction: process.env.NODE_ENV === 'production',
+    });
+  }
+}
+```
+
+No webpack externals or bundler config needed.
+
+## Coexistence with other SDKs
+
+Foam detects each OpenTelemetry signal independently. If another SDK (Sentry, @vercel/otel, Datadog, etc.) has already registered a TracerProvider, LoggerProvider, or MeterProvider, Foam attaches its exporters on top rather than replacing them. Both SDKs receive data.
+
+If no providers exist, Foam creates its own. This means Foam works in any combination:
+
+- Foam alone
+- Foam + Sentry
+- Foam + @vercel/otel
+- Foam + any OpenTelemetry-compatible SDK
+
+## API
+
+### `init(options)`
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `apiKey` | `string` | Yes | Your Foam API key |
+| `serviceName` | `string` | Yes | Name of your service (appears in Foam dashboard) |
+| `isProduction` | `boolean` | Yes | Set to `true` to enable telemetry. `false` = no-op. |
+| `instrumentations` | `InstrumentationBase[]` | No | OpenTelemetry instrumentations to register |
+
+### `captureException(error)`
+
+Captures a caught error and sends it to Foam. Works with or without an active span.
+
+## Design
+
+- **HTTP-only exporters** — no gRPC, no Node.js built-in dependencies that break bundlers
+- **Zero latency** — all setup is synchronous; exporting happens in background batch intervals
+- **Crash-safe** — each signal (traces, logs, metrics, console, process handlers) is independently wrapped in try/catch
+- **Idempotent** — safe to call `init()` multiple times; console patching and process handlers use Symbols to prevent double-registration

package/dist/node/src/index.d.ts

@@ -1,9 +1,13 @@
 import { captureException } from './capture-exception';
 import { init } from './init';
-export { captureException, init };
+import { incrementCounter, recordHistogram, recordGauge } from './metrics';
+export { captureException, init, incrementCounter, recordHistogram, recordGauge };
 export type { FoamNodeInitOptions } from './init';
 declare const foam: {
     captureException: (error: unknown) => void;
     init: (options: import("./init").FoamNodeInitOptions) => void;
+    incrementCounter: (name: string, value?: number, attributes?: import("@opentelemetry/api").Attributes) => void;
+    recordHistogram: (name: string, value: number, attributes?: import("@opentelemetry/api").Attributes) => void;
+    recordGauge: (name: string, value: number, attributes?: import("@opentelemetry/api").Attributes) => void;
 };
 export default foam;

package/dist/node/src/index.js

@@ -1,12 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.init = exports.captureException = void 0;
+exports.recordGauge = exports.recordHistogram = exports.incrementCounter = exports.init = exports.captureException = void 0;
 const capture_exception_1 = require("./capture-exception");
 Object.defineProperty(exports, "captureException", { enumerable: true, get: function () { return capture_exception_1.captureException; } });
 const init_1 = require("./init");
 Object.defineProperty(exports, "init", { enumerable: true, get: function () { return init_1.init; } });
+const metrics_1 = require("./metrics");
+Object.defineProperty(exports, "incrementCounter", { enumerable: true, get: function () { return metrics_1.incrementCounter; } });
+Object.defineProperty(exports, "recordHistogram", { enumerable: true, get: function () { return metrics_1.recordHistogram; } });
+Object.defineProperty(exports, "recordGauge", { enumerable: true, get: function () { return metrics_1.recordGauge; } });
 const foam = {
     captureException: capture_exception_1.captureException,
     init: init_1.init,
+    incrementCounter: metrics_1.incrementCounter,
+    recordHistogram: metrics_1.recordHistogram,
+    recordGauge: metrics_1.recordGauge,
 };
 exports.default = foam;

package/dist/node/src/init.js

@@ -190,8 +190,23 @@ function patchConsole() {
         const original = console[method].bind(console);
         console[method] = (...args) => {
             original(...args);
-            // logger.emit is non-blocking — it queues into the BatchLogRecordProcessor
-            logger.emit({ severityNumber, severityText, body: (0, util_1.format)(...args) });
+            let ctx;
+            let traceAttributes;
+            try {
+                ctx = api_1.context.active();
+                const spanContext = api_1.trace.getSpanContext(ctx);
+                if (spanContext && (0, api_1.isSpanContextValid)(spanContext)) {
+                    traceAttributes = { 'trace.id': spanContext.traceId, 'span.id': spanContext.spanId };
+                }
+            }
+            catch { /* never break the caller's console.log */ }
+            logger.emit({
+                context: ctx,
+                severityNumber,
+                severityText,
+                body: (0, util_1.format)(...args),
+                attributes: traceAttributes,
+            });
         };
     };
     patch('log', api_logs_1.SeverityNumber.INFO, 'INFO');

package/dist/node/src/metrics.d.ts

@@ -0,0 +1,28 @@
+import { type Attributes } from '@opentelemetry/api';
+/**
+ * Increments a counter metric by the given value (default 1).
+ *
+ * Counters are monotonically increasing — use for things like request counts,
+ * items processed, or errors encountered.
+ *
+ * Safe to call before `init()` — silently no-ops via the OTel noop meter.
+ */
+export declare const incrementCounter: (name: string, value?: number, attributes?: Attributes) => void;
+/**
+ * Records a value on a histogram metric.
+ *
+ * Histograms capture distributions — use for latencies, request sizes,
+ * or any measurement where percentiles and averages matter.
+ *
+ * Safe to call before `init()` — silently no-ops via the OTel noop meter.
+ */
+export declare const recordHistogram: (name: string, value: number, attributes?: Attributes) => void;
+/**
+ * Records a point-in-time gauge value.
+ *
+ * Gauges represent a current measurement that can go up or down — use for
+ * things like queue depth, active connections, or memory usage.
+ *
+ * Safe to call before `init()` — silently no-ops via the OTel noop meter.
+ */
+export declare const recordGauge: (name: string, value: number, attributes?: Attributes) => void;

package/dist/node/src/metrics.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordGauge = exports.recordHistogram = exports.incrementCounter = void 0;
+const api_1 = require("@opentelemetry/api");
+const util_1 = require("../../shared/util");
+const METER_NAME = 'foam';
+const counters = new Map();
+const histograms = new Map();
+const gauges = new Map();
+function getMeter() {
+    return api_1.metrics.getMeter(METER_NAME);
+}
+function getOrCreateCounter(name) {
+    let counter = counters.get(name);
+    if (!counter) {
+        counter = getMeter().createCounter(name);
+        counters.set(name, counter);
+    }
+    return counter;
+}
+function getOrCreateHistogram(name) {
+    let histogram = histograms.get(name);
+    if (!histogram) {
+        histogram = getMeter().createHistogram(name);
+        histograms.set(name, histogram);
+    }
+    return histogram;
+}
+function getOrCreateGauge(name) {
+    let gauge = gauges.get(name);
+    if (!gauge) {
+        gauge = getMeter().createGauge(name);
+        gauges.set(name, gauge);
+    }
+    return gauge;
+}
+/**
+ * Increments a counter metric by the given value (default 1).
+ *
+ * Counters are monotonically increasing — use for things like request counts,
+ * items processed, or errors encountered.
+ *
+ * Safe to call before `init()` — silently no-ops via the OTel noop meter.
+ */
+exports.incrementCounter = (0, util_1.safe)((name, value, attributes) => {
+    getOrCreateCounter(name).add(value ?? 1, attributes);
+});
+/**
+ * Records a value on a histogram metric.
+ *
+ * Histograms capture distributions — use for latencies, request sizes,
+ * or any measurement where percentiles and averages matter.
+ *
+ * Safe to call before `init()` — silently no-ops via the OTel noop meter.
+ */
+exports.recordHistogram = (0, util_1.safe)((name, value, attributes) => {
+    getOrCreateHistogram(name).record(value, attributes);
+});
+/**
+ * Records a point-in-time gauge value.
+ *
+ * Gauges represent a current measurement that can go up or down — use for
+ * things like queue depth, active connections, or memory usage.
+ *
+ * Safe to call before `init()` — silently no-ops via the OTel noop meter.
+ */
+exports.recordGauge = (0, util_1.safe)((name, value, attributes) => {
+    getOrCreateGauge(name).record(value, attributes);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foam-ai/node",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.3",
   "main": "dist/node/src/index.js",
   "types": "dist/node/src/index.d.ts",
   "exports": {