@foam-ai/node 0.1.0-alpha.2 → 0.1.0-alpha.4

package/README.md

@@ -1,123 +1,470 @@
-# @foam-ai/node
+# Foam OpenTelemetry SDK for Node.js
 
-Foam observability SDK for Node.js. Sends traces, logs, and metrics to Foam with zero configuration overhead.
+`@foam-ai/node` is Foam's OpenTelemetry distribution for Node.js. It configures
+the official OpenTelemetry JavaScript SDK, node automatic instrumentations, and
+OTLP/HTTP exporters with one `init()` call.
+
+## Requirements
+
+- Node.js `^18.19.0 || >=20.6.0`, matching the supported engine range of
+  `@opentelemetry/auto-instrumentations-node`
+- A Foam ingest token, stored as `FOAM_OTEL_TOKEN`
 
 ## Install
 
-```bash
+```sh
 npm install @foam-ai/node
 ```
 
-## Quick start
+## Initialize
+
+Call `init()` before any application code loads so OpenTelemetry can patch
+libraries as they import. Don't import the app from the same file: ESM runs
+static imports before `init()`. Set `enabled: false` to disable Foam. Store
+the ingest token as `FOAM_OTEL_TOKEN` and pass `process.env.FOAM_OTEL_TOKEN`;
+do not hardcode it.
+
+### TypeScript
 
-Call `init()` as early as possible in your application entry point:
+Create `instrumentation.ts`:
 
-```typescript
-import foam from '@foam-ai/node';
+```ts
+import { init } from "@foam-ai/node";
 
-foam.init({
-  apiKey: process.env.FOAM_API_KEY,
-  serviceName: 'my-service',
-  isProduction: process.env.NODE_ENV === 'production',
+init({
+  name: "checkout-api",
+  environment: "production",
+  enabled: true,
+  token: process.env.FOAM_OTEL_TOKEN,
+  version: "1.0.0",
 });
 ```
 
-That's it. In production, Foam will automatically collect:
+Compile it with the app. If TypeScript emits ESM:
 
-- **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`
+```sh
+node --import ./dist/instrumentation.js ./dist/app.js
+```
+
+If TypeScript emits CommonJS:
 
-In non-production environments, `init()` is a silent no-op.
+```sh
+node --require ./dist/instrumentation.js ./dist/app.js
+```
 
-## Capturing errors
+To run TypeScript without compiling first:
 
-Unhandled exceptions and rejections are captured automatically. For caught errors you want to report, use `captureException`:
+```sh
+node --import tsx --import ./instrumentation.ts ./src/app.ts
+```
 
-```typescript
-import { captureException } from '@foam-ai/node';
+### ESM
 
-try {
-  await chargeCustomer(order);
-} catch (err) {
-  captureException(err);
-  return res.status(500).json({ error: 'Payment failed' });
-}
+Create `instrumentation.mjs` with the same `init()` call, then:
+
+```sh
+node --import ./instrumentation.mjs ./app.js
 ```
 
-`captureException` works with or without an active trace span. It always emits an OpenTelemetry log record so errors reach Foam regardless of instrumentation setup.
+### CommonJS
 
-## Auto-instrumentation (optional)
+Create `instrumentation.cjs`:
 
-By default, no auto-instrumentations are registered. This keeps the SDK webpack/Turbopack-safe with no bundler configuration needed.
+```js
+const { init } = require("@foam-ai/node");
 
-For plain Node.js servers (Express, Fastify, etc.), you can opt into automatic HTTP, DNS, and framework instrumentation:
+init({
+  name: "checkout-api",
+  environment: "production",
+  enabled: true,
+  token: process.env.FOAM_OTEL_TOKEN,
+  version: "1.0.0",
+});
+```
 
-```typescript
-import foam from '@foam-ai/node';
-import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+```sh
+node --require ./instrumentation.cjs ./app.js
+```
+
+## Public API
+
+### `init(options)`
 
-foam.init({
-  apiKey: process.env.FOAM_API_KEY,
-  serviceName: 'my-api',
-  isProduction: process.env.NODE_ENV === 'production',
-  instrumentations: getNodeAutoInstrumentations(),
+Starts Foam: resource, sampler, OTLP exporters, automatic instrumentations,
+and the W3C propagator.
+
+Call this once when Foam can own all of one of OTEL slots. 
+
+```js
+import { init } from "@foam-ai/node";
+
+init({
+  name: "checkout-api",
+  environment: "production",
+  enabled: true,
+  token: process.env.FOAM_OTEL_TOKEN,
+  version: "1.0.0",
 });
 ```
 
-```bash
-npm install @opentelemetry/auto-instrumentations-node
+```ts
+init({
+  name,
+  environment,
+  enabled,
+  token,
+  version?,
+  sampleRate?,
+  additionalInstrumentations?,
+  additionalSpanProcessors?,
+  additionalLogRecordProcessors?,
+  additionalMetricReaders?,
+  additionalResourceAttributes?,
+  disableLogSending?,
+  networkCapture?,
+  ignoredOutboundHosts?,
+  diagnostics?,
+}): void
 ```
 
-## Next.js
+`name`, `environment`, and `enabled` are required.
+`token` is required only when enabled; store it as `FOAM_OTEL_TOKEN`.
+`sampleRate` accepts values from `0` through `1` and defaults to
+`1`.
+
+Foam always installs this sampler rather than reading `OTEL_TRACES_SAMPLER`.
+Diagnostics default to enabled.
+
+`additionalResourceAttributes` adds custom resource attributes (for example
+`team` or `cloud.region`) to all telemetry. The Basic API's `name`,
+`environment`, and `version` options take precedence over matching keys.
+Foam also sets `telemetry.sdk.*` from the OpenTelemetry SDK and
+`telemetry.distro.name` / `telemetry.distro.version` for this distribution.
+
+Foam detects process, host, and OS attributes from this machine. It does not
+run cloud or container resource detectors (AWS, GCP, Azure, Alibaba, or cgroup
+`container.id`), which call metadata APIs at startup. Set cloud or container
+identity with `additionalResourceAttributes`.
+
+`additionalInstrumentations` registers extra OpenTelemetry instrumentations
+alongside Foam's Node auto bundle and `ConsoleInstrumentation`. Foam already
+enables [`@opentelemetry/instrumentation-openai`](https://www.npmjs.com/package/@opentelemetry/instrumentation-openai)
+from that bundle (`openai` `>=4.19 <7`); message content is captured only when
+`networkCapture` is `"advanced"`. Use this option for libraries Foam does not
+ship, such as community Anthropic instrumentations
+([`@traceloop/instrumentation-anthropic`](https://www.npmjs.com/package/@traceloop/instrumentation-anthropic)
+or
+[`@arizeai/openinference-instrumentation-anthropic`](https://www.npmjs.com/package/@arizeai/openinference-instrumentation-anthropic)),
+or to replace a bundled instrumentation by name: last entry wins, and Foam
+disables its own copy. Replacing HTTP or Undici this way also replaces Foam's
+network capture hooks.
+
+### `createFoamIngestSpanProcessor(name, environment, token)`
+
+Returns a span processor that exports traces to Foam without taking over the
+global TracerProvider.
+
+Use this when another OpenTelemetry SDK already owns traces and you only need
+Foam as an extra export destination.
+
+```js
+import { createFoamIngestSpanProcessor } from "@foam-ai/node";
+
+const spanProcessor = createFoamIngestSpanProcessor(
+  "checkout-api",
+  "production",
+  process.env.FOAM_OTEL_TOKEN,
+);
+tracerProvider.addSpanProcessor(spanProcessor);
+```
+
+### `createFoamIngestLogRecordProcessor(name, environment, token)`
+
+Returns a log-record processor that exports logs to Foam without taking over
+the global LoggerProvider.
+
+Use this when another SDK already owns logs and you want those records in Foam.
 
-In a Next.js app, create an `instrumentation.ts` file at the project root:
+```js
+import { createFoamIngestLogRecordProcessor } from "@foam-ai/node";
 
-```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',
-    });
-  }
-}
+const logRecordProcessor = createFoamIngestLogRecordProcessor(
+  "checkout-api",
+  "production",
+  process.env.FOAM_OTEL_TOKEN,
+);
+loggerProvider.addLogRecordProcessor(logRecordProcessor);
 ```
 
-No webpack externals or bundler config needed.
+### `createFoamIngestMetricReader(name, environment, token)`
 
-## Coexistence with other SDKs
+Returns a metric reader that exports metrics to Foam without taking over the
+global MeterProvider.
 
-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.
+Use this when another SDK already owns metrics and you want those meters in
+Foam.
 
-If no providers exist, Foam creates its own. This means Foam works in any combination:
+```js
+import { createFoamIngestMetricReader } from "@foam-ai/node";
 
-- Foam alone
-- Foam + Sentry
-- Foam + @vercel/otel
-- Foam + any OpenTelemetry-compatible SDK
+const metricReader = createFoamIngestMetricReader(
+  "checkout-api",
+  "production",
+  process.env.FOAM_OTEL_TOKEN,
+);
+meterProvider.addMetricReader(metricReader);
+```
+
+The factories do not claim global OTel providers. `name`, `environment`, and
+`token` are required; Foam stamps `service.name`,
+`deployment.environment.name`, and `foam.ingest.tier=external` onto the
+exported resource. If the other SDK already set `service.name` or environment,
+Foam's values overwrite them on the copy sent to Foam only. The original
+spans, logs, and metrics are not mutated.
+
+Use `init()` or ingest, not both on the same signal. If another SDK already
+owns traces (or another slot), call `init()` for the free signals and attach
+ingest only to the provider you do not own. Do not pass ingest factories as
+`additionalSpanProcessors` / readers: `init()` already installs Foam exporters.
+
+The global propagator is also first-wins. OpenTelemetry allows only one, and
+HTTP, Express, Undici, and Fetch all call it to copy trace headers onto
+requests. Foam registers W3C Trace Context and W3C Baggage
+(`traceparent`, `tracestate`, `baggage`) and nothing else: not B3, Jaeger, or
+AWS X-Ray. If Foam wins the slot, auto-instrumented HTTP is W3C-only. If
+another SDK already registered a propagator, Foam keeps it,
+`getState().signals.baggage` is `false`, and HTTP speaks that winner's format.
+A B3-only (or Jaeger/X-Ray-only) winner will not send or honor `traceparent`,
+so a Foam peer that only understands W3C starts a new trace. Foam does not
+wrap inject/extract to dual-read those formats or add W3C headers on top.
+Initialize Foam first, or have the other SDK register a composite that
+includes W3C, if those headers must be on HTTP.
+
+### `injectTraceContext(headers)`
+
+Writes W3C `traceparent`, `tracestate`, and `baggage` onto a header map.
+
+Use this when you send a message yourself (Kafka, a queue, a custom socket).
+Auto-instrumented HTTP, Express, Undici, and Fetch already inject these
+headers; do not call this on ordinary HTTP. This path uses Foam's local W3C
+propagator even if Foam lost the global slot.
+
+```js
+const headers = {};
+injectTraceContext(headers);
+await kafka.send({ value: payload, headers });
+```
 
-## API
+### `extractTraceContext(headers)`
 
-### `init(options)`
+Reads W3C trace and baggage headers and returns a parent OpenTelemetry context.
+
+Use this when you receive a message on a custom transport so the work continues
+the same trace. Ignoring those headers starts a new one.
+
+```js
+import { context } from "@opentelemetry/api";
+
+const parent = extractTraceContext(message.headers);
+await context.with(parent, () => handle(message));
+```
+
+### `setBaggage(key, value)`
+
+Stores a small string on the current request context.
+
+Use this for request-scoped identity (tenant, user id) that should follow the
+request across `await`s without being passed through every function. Values do
+not leak to other concurrent requests. Auto-instrumented HTTP does not send
+these keys until you call `injectTraceContext`.
+
+```js
+setBaggage("tenant.id", "acme");
+```
+
+### `getBaggage(key)`
+
+Returns a baggage value from the current request, or `undefined`.
 
-| 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 |
+Use this later in the same request to read a value set with `setBaggage`, or a
+key that arrived on an inbound `baggage` header.
+
+```js
+const tenant = getBaggage("tenant.id"); // "acme"
+```
+
+### `incrementCounter(name, value?, attributes?, options?)`
+
+Adds to a counter that only increases.
+
+Use this for event counts: orders created, jobs finished, errors.
+
+```js
+incrementCounter("orders.created", 1, { "cloud.region": "us-west-1" });
+```
 
-### `captureException(error)`
+### `recordHistogram(name, value, attributes?, options?)`
 
-Captures a caught error and sends it to Foam. Works with or without an active span.
+Records a measurement in a distribution.
 
-## Design
+Use this for values you want percentiles or averages of: latency, duration,
+payload size.
+
+```js
+recordHistogram("checkout.duration", 0.142, undefined, { unit: "s" });
+```
+
+### `addUpDownCounter(name, value, attributes?, options?)`
+
+Adds a signed delta to a counter that can go up or down.
+
+Use this for occupancy: active jobs, open connections, items in a pool.
+
+```js
+addUpDownCounter("jobs.active", -1);
+```
+
+### `setMetric(name, value, attributes?, options?)`
+
+Sets the current value of a gauge.
+
+Use this for a point-in-time level: queue depth, heap used, cache size.
+
+```js
+setMetric("queue.depth", 27);
+```
+
+Each metric helper caches instruments by kind and name. `unit` and
+`description` therefore apply on first use. Observable (pull) instruments are
+not part of this API; use `@opentelemetry/api` or automatic instrumentation
+when a value should be sampled on export rather than recorded on an event.
+
+### `getState()`
+
+Returns whether Foam initialized, which instrumentations registered, and which
+signals have an export path.
+
+Use this in health checks, tests, or diagnostics to confirm Foam is running.
+
+```js
+import { getState } from "@foam-ai/node";
+
+getState();
+// {
+//   initialized: true,
+//   instrumentations: ["http", "express", "pg", ...],
+//   signals: {
+//     traces: true,
+//     metrics: true,
+//     logs: true,
+//     baggage: true,
+//     profile: false,
+//   },
+// }
+```
 
-- **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
+`instrumentations` contains only the instrumentations registered with a
+successfully started Foam SDK, after upstream defaults and
+`OTEL_NODE_ENABLED_INSTRUMENTATIONS` /
+`OTEL_NODE_DISABLED_INSTRUMENTATIONS` filtering. Registration means an
+instrumentation is ready to patch a supported module when that module loads; it
+does not prove that the module has loaded or emitted spans.
+
+Each `signals` boolean means Foam successfully constructed an export path for
+that signal. This can be a Foam-owned provider from `init()` or a
+processor/reader returned by an ingest factory. For ingest factories, Foam
+cannot prove that the caller subsequently registered the returned object. The
+boolean therefore means telemetry is expected, not that the application has
+already produced or successfully exported it.
+
+## Network capture
+
+`networkCapture` defaults to `"basic"` and controls HTTP enrichment: `"off"`
+keeps standard OpenTelemetry HTTP/Undici telemetry with no extra capture,
+`"basic"` adds allowlisted `content-type`, `content-length`, and
+`content-encoding` headers, and `"advanced"` adds those headers plus complete
+Node `http`/`https` (and Fetch/Undici, when diagnostics exist) request and
+response bodies as raw wire bytes up to 1 MiB. Bodies are emitted as
+correlated `foam.http.body.chunk` log events; the HTTP span records semantic
+`http.*.body.size` and, for textual bodies, `http.*.body.content`, while
+`authorization`, `cookie`, HTTP/2, and gRPC are never captured. Advanced
+capture requires Foam to own the logger provider, closes incomplete bodies
+after 60 seconds of inactivity, and is replaced if you override the bundled
+HTTP instrumentation through `additionalInstrumentations`. Foam partitions
+serialized trace and log export batches below 19 MiB to stay under the
+ClickStack collector's 20 MiB OTLP/HTTP limit.
+
+## Logger support and ownership
+
+Foam follows the compatibility ranges of its OpenTelemetry logger
+instrumentations:
+
+- Bunyan `>=1 <2`
+- Pino `>=5.14 <11`
+- Winston `>=1 <4`
+
+The init log line that lists registered instrumentations also names each
+detected logger with its installed version. Initialize Foam before importing or
+constructing the logger; registration alone does not prove that a logger was
+loaded, patched, or produced records.
+
+Logger trace correlation remains enabled by default. With
+`disableLogSending: false` (the default), OpenTelemetry automatically sends:
+
+- Bunyan records through its added OTel stream
+- Pino 7 and newer records through an added main-thread multistream
+- Winston 3 records through the bundled `OpenTelemetryTransportV3`
+
+Pino 5 and 6 and Winston 1 and 2 support correlation only. Set
+`disableLogSending: true` when the application manually installs a Bunyan OTel
+stream, configures `pino-opentelemetry-transport`, installs a Winston OTel
+transport, or otherwise gives another pipeline ownership of logger records.
+This disables automatic sending for Bunyan, Pino, and Winston while preserving
+trace correlation.
+
+OpenTelemetry cannot reliably deduplicate manually configured streams and
+transports; explicit `disableLogSending` ownership is the correctness
+mechanism.
+
+`ConsoleInstrumentation` separately turns calls to `console.*` into OTel log
+records. It does not make arbitrary stdout/stderr writes observable.
+
+## OpenTelemetry configuration and compliance
+
+Foam composes the official OpenTelemetry JavaScript API, SDK, resource,
+propagation, instrumentation, and OTLP exporter packages. It does not fork
+their data model or redefine spans, metrics, logs, resources, or context.
+
+Foam does not use any of environment configuration. So they remain available, including:
+
+- `OTEL_RESOURCE_ATTRIBUTES` (the Basic API's required service name and
+  environment take precedence for those resource attributes)
+- `OTEL_NODE_ENABLED_INSTRUMENTATIONS` and
+  `OTEL_NODE_DISABLED_INSTRUMENTATIONS`
+- `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`
+- `OTEL_TRACES_SAMPLER`
+
+The [OpenTelemetry JavaScript compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix/js.yaml)
+describes `opentelemetry-js`, not this distro. It uses `+` (implemented),
+`-` (not implemented), `?` (unknown), and `N/A`. Foam does not reimplement
+those SDK features and does not inherit every `+` row: `init()` only
+constructs the packages and options this distro actually wires (W3C
+propagation, OTLP/HTTP to Foam, a parent-based ratio sampler). Rows the
+matrix marks `+` for JavaScript but Foam never installs stay unavailable
+here, including OTLP/gRPC, Zipkin, Prometheus, Jaeger remote sampling,
+B3/Jaeger propagators, metric views, and `OTEL_TRACES_SAMPLER`. Foam also
+does not implement rows marked `-` or `?`.
+
+## TODO(pcga11): OpenTelemetry profiling
+
+Profiling is not supported: the official OpenTelemetry JavaScript SDK has no
+in-process Profiles provider, processor, or exporter yet.
+
+Add profiling and report `getState().signals.profile: true` after that ships.
+
+Track upstream progress:
+
+- [OpenTelemetry JS profiling implementation issue](https://github.com/open-telemetry/opentelemetry-js/issues/6500)
+- [Profiling SIG language SDK support tracker](https://github.com/open-telemetry/sig-profiling/issues/106)
+- [OpenTelemetry Profiles public alpha announcement](https://opentelemetry.io/blog/2026/profiles-alpha/)
+- [OpenTelemetry eBPF profiler](https://github.com/open-telemetry/opentelemetry-ebpf-profiler)

package/dist/constants.d.ts

@@ -0,0 +1,42 @@
+export declare const FOAM_ENDPOINT = "https://otel.api.foam.ai";
+export declare const FOAM_IDENTIFIER_NAME = "foam-otel";
+export declare const FOAM_DISTRO_NAME = "@foam-ai/node";
+export declare const FOAM_DISTRO_VERSION = "0.1.0-alpha.4";
+export declare const FOAM_INGEST_TIER = "foam.ingest.tier";
+export declare const FOAM_OTLP_TRACES_PATH = "/v1/traces";
+export declare const FOAM_OTLP_LOGS_PATH = "/v1/logs";
+export declare const FOAM_OTLP_METRICS_PATH = "/v1/metrics";
+export declare const NETWORK_BODY_CHUNK_BYTES: number;
+export declare const NETWORK_BODY_MAX_CAPTURE_BYTES: number;
+export declare const NETWORK_CAPTURE_EVENT = "foam.http.body.chunk";
+export declare const NETWORK_CAPTURE_EVENT_BODY = "HTTP body chunk";
+export declare const NETWORK_CAPTURE_DEADLINE_MS = 60000;
+export declare const MAX_ACTIVE_CAPTURES = 128;
+export declare const ATTR_HTTP_REQUEST_BODY_SIZE = "http.request.body.size";
+export declare const ATTR_HTTP_RESPONSE_BODY_SIZE = "http.response.body.size";
+export declare const ATTR_HTTP_REQUEST_BODY_CONTENT = "http.request.body.content";
+export declare const ATTR_HTTP_RESPONSE_BODY_CONTENT = "http.response.body.content";
+export declare const ATTR_FOAM_HTTP_BODY_ID = "foam.http.body.id";
+export declare const ATTR_FOAM_HTTP_BODY_SIDE = "foam.http.body.side";
+export declare const ATTR_FOAM_HTTP_BODY_DIRECTION = "foam.http.body.direction";
+export declare const ATTR_FOAM_HTTP_BODY_COMPLETE = "foam.http.body.complete";
+export declare const ATTR_FOAM_HTTP_BODY_TRUNCATED = "foam.http.body.truncated";
+export declare const ATTR_FOAM_HTTP_BODY_OUTCOME = "foam.http.body.outcome";
+export declare const ATTR_FOAM_HTTP_BODY_CAPTURED_BYTES = "foam.http.body.captured_bytes";
+export declare const ATTR_FOAM_HTTP_BODY_CHUNK_COUNT = "foam.http.body.chunk.count";
+export declare const ATTR_FOAM_HTTP_BODY_CHUNK_INDEX = "foam.http.body.chunk.index";
+export declare const ATTR_FOAM_HTTP_BODY_CHUNK_BYTES = "foam.http.body.chunk.bytes";
+export declare const ATTR_FOAM_HTTP_BODY_CHUNK_CONTENT = "foam.http.body.chunk.content";
+export declare const ATTR_FOAM_HTTP_REQUEST_BODY_CAPTURE_ID = "foam.http.request.body.capture_id";
+export declare const ATTR_FOAM_HTTP_RESPONSE_BODY_CAPTURE_ID = "foam.http.response.body.capture_id";
+export declare const ATTR_FOAM_HTTP_REQUEST_BODY_COMPLETE = "foam.http.request.body.complete";
+export declare const ATTR_FOAM_HTTP_RESPONSE_BODY_COMPLETE = "foam.http.response.body.complete";
+export declare const ATTR_FOAM_HTTP_REQUEST_BODY_TRUNCATED = "foam.http.request.body.truncated";
+export declare const ATTR_FOAM_HTTP_RESPONSE_BODY_TRUNCATED = "foam.http.response.body.truncated";
+export declare const SAFE_NETWORK_HEADERS: readonly ["content-type", "content-length", "content-encoding"];
+export declare const DIAG_LOG_LEVEL = "OTEL_LOG_LEVEL";
+export declare const SEVERITY_TEXT: {
+    readonly 9: "INFO";
+    readonly 13: "WARN";
+    readonly 17: "ERROR";
+};

package/dist/constants.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEVERITY_TEXT = exports.DIAG_LOG_LEVEL = exports.SAFE_NETWORK_HEADERS = exports.ATTR_FOAM_HTTP_RESPONSE_BODY_TRUNCATED = exports.ATTR_FOAM_HTTP_REQUEST_BODY_TRUNCATED = exports.ATTR_FOAM_HTTP_RESPONSE_BODY_COMPLETE = exports.ATTR_FOAM_HTTP_REQUEST_BODY_COMPLETE = exports.ATTR_FOAM_HTTP_RESPONSE_BODY_CAPTURE_ID = exports.ATTR_FOAM_HTTP_REQUEST_BODY_CAPTURE_ID = exports.ATTR_FOAM_HTTP_BODY_CHUNK_CONTENT = exports.ATTR_FOAM_HTTP_BODY_CHUNK_BYTES = exports.ATTR_FOAM_HTTP_BODY_CHUNK_INDEX = exports.ATTR_FOAM_HTTP_BODY_CHUNK_COUNT = exports.ATTR_FOAM_HTTP_BODY_CAPTURED_BYTES = exports.ATTR_FOAM_HTTP_BODY_OUTCOME = exports.ATTR_FOAM_HTTP_BODY_TRUNCATED = exports.ATTR_FOAM_HTTP_BODY_COMPLETE = exports.ATTR_FOAM_HTTP_BODY_DIRECTION = exports.ATTR_FOAM_HTTP_BODY_SIDE = exports.ATTR_FOAM_HTTP_BODY_ID = exports.ATTR_HTTP_RESPONSE_BODY_CONTENT = exports.ATTR_HTTP_REQUEST_BODY_CONTENT = exports.ATTR_HTTP_RESPONSE_BODY_SIZE = exports.ATTR_HTTP_REQUEST_BODY_SIZE = exports.MAX_ACTIVE_CAPTURES = exports.NETWORK_CAPTURE_DEADLINE_MS = exports.NETWORK_CAPTURE_EVENT_BODY = exports.NETWORK_CAPTURE_EVENT = exports.NETWORK_BODY_MAX_CAPTURE_BYTES = exports.NETWORK_BODY_CHUNK_BYTES = exports.FOAM_OTLP_METRICS_PATH = exports.FOAM_OTLP_LOGS_PATH = exports.FOAM_OTLP_TRACES_PATH = exports.FOAM_INGEST_TIER = exports.FOAM_DISTRO_VERSION = exports.FOAM_DISTRO_NAME = exports.FOAM_IDENTIFIER_NAME = exports.FOAM_ENDPOINT = void 0;
+const api_logs_1 = require("@opentelemetry/api-logs");
+exports.FOAM_ENDPOINT = "https://otel.api.foam.ai";
+exports.FOAM_IDENTIFIER_NAME = "foam-otel";
+exports.FOAM_DISTRO_NAME = "@foam-ai/node";
+exports.FOAM_DISTRO_VERSION = "0.1.0-alpha.4";
+exports.FOAM_INGEST_TIER = "foam.ingest.tier";
+exports.FOAM_OTLP_TRACES_PATH = "/v1/traces";
+exports.FOAM_OTLP_LOGS_PATH = "/v1/logs";
+exports.FOAM_OTLP_METRICS_PATH = "/v1/metrics";
+exports.NETWORK_BODY_CHUNK_BYTES = 64 * 1024; // 64Kib
+exports.NETWORK_BODY_MAX_CAPTURE_BYTES = 1024 * 1024; // 1Mib
+exports.NETWORK_CAPTURE_EVENT = "foam.http.body.chunk";
+exports.NETWORK_CAPTURE_EVENT_BODY = "HTTP body chunk";
+exports.NETWORK_CAPTURE_DEADLINE_MS = 60_000;
+exports.MAX_ACTIVE_CAPTURES = 128;
+// pcga11: Do not change these.
+// Spec names copied from OpenTelemetry HTTP semantic conventions. 1.43.0 does
+// not export BODY_CONTENT, and OTel JS recommends copying unstable names
+// instead of importing `@opentelemetry/semantic-conventions/incubating`.
+exports.ATTR_HTTP_REQUEST_BODY_SIZE = "http.request.body.size";
+exports.ATTR_HTTP_RESPONSE_BODY_SIZE = "http.response.body.size";
+exports.ATTR_HTTP_REQUEST_BODY_CONTENT = "http.request.body.content";
+exports.ATTR_HTTP_RESPONSE_BODY_CONTENT = "http.response.body.content";
+exports.ATTR_FOAM_HTTP_BODY_ID = "foam.http.body.id";
+exports.ATTR_FOAM_HTTP_BODY_SIDE = "foam.http.body.side";
+exports.ATTR_FOAM_HTTP_BODY_DIRECTION = "foam.http.body.direction";
+exports.ATTR_FOAM_HTTP_BODY_COMPLETE = "foam.http.body.complete";
+exports.ATTR_FOAM_HTTP_BODY_TRUNCATED = "foam.http.body.truncated";
+exports.ATTR_FOAM_HTTP_BODY_OUTCOME = "foam.http.body.outcome";
+exports.ATTR_FOAM_HTTP_BODY_CAPTURED_BYTES = "foam.http.body.captured_bytes";
+exports.ATTR_FOAM_HTTP_BODY_CHUNK_COUNT = "foam.http.body.chunk.count";
+exports.ATTR_FOAM_HTTP_BODY_CHUNK_INDEX = "foam.http.body.chunk.index";
+exports.ATTR_FOAM_HTTP_BODY_CHUNK_BYTES = "foam.http.body.chunk.bytes";
+exports.ATTR_FOAM_HTTP_BODY_CHUNK_CONTENT = "foam.http.body.chunk.content";
+exports.ATTR_FOAM_HTTP_REQUEST_BODY_CAPTURE_ID = "foam.http.request.body.capture_id";
+exports.ATTR_FOAM_HTTP_RESPONSE_BODY_CAPTURE_ID = "foam.http.response.body.capture_id";
+exports.ATTR_FOAM_HTTP_REQUEST_BODY_COMPLETE = "foam.http.request.body.complete";
+exports.ATTR_FOAM_HTTP_RESPONSE_BODY_COMPLETE = "foam.http.response.body.complete";
+exports.ATTR_FOAM_HTTP_REQUEST_BODY_TRUNCATED = "foam.http.request.body.truncated";
+exports.ATTR_FOAM_HTTP_RESPONSE_BODY_TRUNCATED = "foam.http.response.body.truncated";
+exports.SAFE_NETWORK_HEADERS = [
+    "content-type",
+    "content-length",
+    "content-encoding",
+];
+exports.DIAG_LOG_LEVEL = "OTEL_LOG_LEVEL";
+exports.SEVERITY_TEXT = {
+    [api_logs_1.SeverityNumber.INFO]: "INFO",
+    [api_logs_1.SeverityNumber.WARN]: "WARN",
+    [api_logs_1.SeverityNumber.ERROR]: "ERROR",
+};

package/dist/diagnostics.d.ts

@@ -0,0 +1,13 @@
+import { SeverityNumber } from "@opentelemetry/api-logs";
+export declare function configureDiagnostics(): void;
+export declare const info: (message: string) => void;
+export declare const warn: (message: string) => void;
+export declare const error: (message: string) => void;
+export declare function sendStateDiagnosticLog({ name, environment, token, tier, severity, error, }: {
+    name: string;
+    environment: string;
+    token: string;
+    tier: "internal" | "external";
+    severity: SeverityNumber;
+    error?: string;
+}): Promise<void>;