@arcote.tech/arc-otel 0.7.6

package/dist/sanitize.d.ts

@@ -0,0 +1,39 @@
+/** Keys matching this pattern are dropped wholesale, regardless of nesting. */
+export declare const DEFAULT_REDACT_KEY_PATTERN: RegExp;
+/** Truncate string values longer than this; backends typically cap span
+ *  attributes around 8-16 KB total, so 2 KB per value is generous but safe. */
+export declare const DEFAULT_MAX_STRING_LEN = 2048;
+/** Serialized objects/arrays beyond this size are truncated. Some backends
+ *  silently drop spans whose attributes exceed their limit (Tempo ~16 KB). */
+export declare const DEFAULT_MAX_JSON_LEN = 4096;
+export interface SanitizeOptions {
+    /** Override the default redaction pattern. Combined via OR. */
+    redactKeyPattern?: RegExp;
+    /** Max string length (per value). Default 2048. */
+    maxStringLen?: number;
+    /** Max serialized object/array length (per value). Default 4096. */
+    maxJsonLen?: number;
+}
+/**
+ * Build a flat attribute map suitable for OpenTelemetry's setAttributes().
+ *
+ * - Removes any key matching the redact pattern (case-insensitive).
+ * - Recursively walks objects/arrays; nested redacted keys are dropped too.
+ * - Primitive values (string/number/boolean) pass through.
+ * - Objects/arrays are JSON-stringified with size cap.
+ * - Strings beyond the cap are truncated with an explicit suffix.
+ * - undefined/null values are dropped (OTel rejects them anyway).
+ *
+ * The output is intentionally a flat `Record<string, primitive>` because the
+ * OTel SDK only persists primitive attribute values.
+ */
+export declare function sanitizeAttrs(input: Record<string, unknown> | null | undefined, opts?: SanitizeOptions): Record<string, string | number | boolean>;
+/**
+ * Strip password from a Postgres-style connection string for safe logging.
+ * Returns the URL unchanged when no password component is present, and
+ * "[unparseable]" if the input is not a URL at all.
+ *
+ *   postgresql://arc:secret@db:5432/arc → postgresql://arc:***@db:5432/arc
+ */
+export declare function redactConnectionString(url: string | undefined | null): string;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"AAUA,+EAA+E;AAC/E,eAAO,MAAM,0BAA0B,QAC2D,CAAC;AAEnG;+EAC+E;AAC/E,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C;8EAC8E;AAC9E,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EACjD,IAAI,GAAE,eAAoB,GACzB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAa3C;AA6CD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAS7E"}

package/dist/telemetry.d.ts

@@ -0,0 +1,99 @@
+import { SpanKind, type Attributes, type Span, type Tracer } from "@opentelemetry/api";
+import { type Logger } from "@opentelemetry/api-logs";
+import { type Meter } from "@opentelemetry/api";
+import { type SanitizeOptions } from "./sanitize";
+export type ObservabilityMode = "development" | "production" | "disabled";
+export interface TelemetryConfig {
+    /** OTel `service.name` resource attribute. Required. */
+    serviceName: string;
+    /** Side this runs on. Determines default sampler + propagator setup in init. */
+    environment: "client" | "server";
+    /** OTLP HTTP endpoint, e.g. `http://otel-collector:4318`. Init functions
+     *  append signal-specific paths (`/v1/traces`, `/v1/logs`, `/v1/metrics`). */
+    endpoint?: string;
+    /** When false, all telemetry APIs are no-ops. Default true. */
+    enabled?: boolean;
+    /** Head-based sample rate at the SDK level. Default 1.0 (server) / 0.1 (client).
+     *  Collector tail-sampling can still drop or upgrade these. */
+    sampleRate?: number;
+    /** development = verbose attrs + 100% sample; production = strict redaction
+     *  + low sample. `disabled` is equivalent to enabled=false. */
+    mode?: ObservabilityMode;
+    /** Override the auto default for `includePayloads` (true in dev, false elsewhere). */
+    includePayloads?: boolean;
+    /** Extra debug logging to stdout during init. Off by default. */
+    debug?: boolean;
+    /** Override sanitization defaults (regex / size caps). */
+    sanitize?: SanitizeOptions;
+}
+/** Span options. Same shape as OTel's but with optional Arc-friendly defaults. */
+export interface SpanOptions {
+    kind?: SpanKind;
+    attributes?: Record<string, unknown>;
+    /** Skip sanitization for `attributes`. Use only when the caller has filtered
+     *  payloads themselves AND the values fit the size cap. */
+    unsafeAttrs?: boolean;
+}
+export declare class ArcTelemetry {
+    readonly config: Required<Pick<TelemetryConfig, "enabled" | "sampleRate" | "mode" | "debug">> & TelemetryConfig;
+    private tracer;
+    private logger;
+    private meter;
+    private histograms;
+    private counters;
+    constructor(config: TelemetryConfig);
+    /** Called by init-server / init-browser after the SDK provider is wired. */
+    attach(opts: {
+        tracer: Tracer;
+        logger?: Logger;
+        meter?: Meter;
+    }): void;
+    /** Whether the SDK is wired and exporting. False during construction or when disabled. */
+    get active(): boolean;
+    /** True in dev mode by default, false in prod. Instrumentation uses this to
+     *  decide whether to attach raw payloads as attributes. */
+    shouldIncludePayloads(): boolean;
+    /**
+     * Run `fn` inside an active span. The span auto-records exceptions, sets
+     * ERROR status on throw, and ends in the finally block.
+     *
+     * When telemetry is disabled or unattached, the span argument passed to
+     * `fn` is the OTel non-recording span. Calls on it (setAttribute, etc.)
+     * are no-ops, so callers don't need to null-check.
+     */
+    startSpan<T>(name: string, fn: (span: Span) => T | Promise<T>, options?: SpanOptions): Promise<T>;
+    /**
+     * Manually create a span without an active scope. Caller is responsible
+     * for ending it. Useful for fire-and-forget instrumentation (e.g. a
+     * long-lived WebSocket connection).
+     */
+    createSpan(name: string, options?: SpanOptions): Span;
+    /** Get the currently active span (if any) for adding attributes / events
+     *  outside the immediate `startSpan` callback. */
+    getCurrentSpan(): Span | undefined;
+    /** Run `fn` with `parent` as the active span. Lets us bridge async
+     *  boundaries where AsyncLocalStorage doesn't help (e.g. WS message
+     *  dispatch, where the parent came over the wire as `traceparent`). */
+    withSpan<T>(parent: Span, fn: () => T): T;
+    /**
+     * Extract a W3C trace context from a carrier (HTTP headers, WS message
+     * payload) and run `fn` inside it. Convenience wrapper so callers don't
+     * need to import from `@opentelemetry/api` directly. Returns whatever
+     * `fn` returns. Safe when telemetry is disabled — falls through to
+     * `fn(activeContext)`.
+     */
+    runWithExtractedContext<T>(carrier: Record<string, unknown> | Headers | null | undefined, fn: () => T): T;
+    /** Mark a span as errored. Safe to call with non-Error throwables. */
+    recordError(span: Span, error: unknown): void;
+    /** Attach attributes to the currently active span. No-op when none exists. */
+    addAttributes(attrs: Record<string, unknown>, unsafeAttrs?: boolean): void;
+    log(level: "debug" | "info" | "warn" | "error", body: string, attrs?: Record<string, unknown>, unsafeAttrs?: boolean): void;
+    /** Increment a counter by `value` (default 1). Counter is created on first use. */
+    incrementCounter(name: string, value?: number, attrs?: Attributes): void;
+    /** Record a value into a histogram (e.g. latency ms). Created lazily. */
+    recordHistogram(name: string, value: number, attrs?: Attributes): void;
+    /** Convenience: record `Date.now() - start` into a histogram. */
+    measureSince(name: string, start: number, attrs?: Attributes): void;
+    private toAttributes;
+}
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"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"}

package/dist/wrap-db-adapter.d.ts

@@ -0,0 +1,28 @@
+import type { ArcTelemetry } from "./telemetry";
+interface ReadTxLike {
+    find(store: string, options: unknown): Promise<unknown[]>;
+}
+interface ReadWriteTxLike extends ReadTxLike {
+    remove(store: string, id: unknown): Promise<void>;
+    set(store: string, data: unknown): Promise<void>;
+    commit(): Promise<void>;
+}
+interface AdapterLike {
+    readWriteTransaction(stores?: string[]): ReadWriteTxLike;
+    readTransaction(stores?: string[]): ReadTxLike;
+    executeReinitTables(dataStorage: unknown): Promise<void>;
+    destroy?(): Promise<void>;
+}
+/**
+ * Wrap a `DatabaseAdapter`-shaped object so every transaction's operations
+ * emit child spans of the active context. Safe to call with an
+ * already-wrapped adapter (no double-wrap detection — the OTel overhead of
+ * a duplicate span is negligible if it ever happened, and adapter identity
+ * checks would couple us to specific implementations).
+ *
+ * The returned adapter has the SAME structural type as the input; pass it
+ * straight where the original would go. No-op when `telemetry` is disabled.
+ */
+export declare function wrapDbAdapter<A extends AdapterLike>(adapter: A, telemetry: ArcTelemetry | undefined, dbSystem: "postgresql" | "sqlite"): A;
+export {};
+//# sourceMappingURL=wrap-db-adapter.d.ts.map

package/dist/wrap-db-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-db-adapter.d.ts","sourceRoot":"","sources":["../src/wrap-db-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAqBhD,UAAU,UAAU;IAClB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CAC3D;AACD,UAAU,eAAgB,SAAQ,UAAU;IAC1C,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AACD,UAAU,WAAW;IACnB,oBAAoB,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,eAAe,CAAC;IACzD,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC;IAC/C,mBAAmB,CAAC,WAAW,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,WAAW,EACjD,OAAO,EAAE,CAAC,EACV,SAAS,EAAE,YAAY,GAAG,SAAS,EACnC,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAChC,CAAC,CAqFH"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@arcote.tech/arc-otel",
+  "version": "0.7.6",
+  "description": "OpenTelemetry instrumentation primitives for the Arc framework — server + browser SDK init, span helpers, PII-safe attribute sanitization, W3C Trace Context propagation",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./server": {
+      "import": "./dist/init-server.js",
+      "types": "./dist/init-server.d.ts"
+    },
+    "./browser": {
+      "import": "./dist/init-browser.js",
+      "types": "./dist/init-browser.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts ./src/init-server.ts ./src/init-browser.ts --outdir ./dist --target node --format esm --external @opentelemetry/* && bun run build:types",
+    "build:types": "tsc --emitDeclarationOnly --declaration --outDir ./dist",
+    "dev": "bun build ./src/index.ts ./src/init-server.ts ./src/init-browser.ts --outdir ./dist --target node --format esm --watch --external @opentelemetry/*"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api-logs": "^0.57.0",
+    "@opentelemetry/core": "^1.30.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.57.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.57.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.57.0",
+    "@opentelemetry/resources": "^1.30.0",
+    "@opentelemetry/sdk-logs": "^0.57.0",
+    "@opentelemetry/sdk-metrics": "^1.30.0",
+    "@opentelemetry/sdk-trace-base": "^1.30.0",
+    "@opentelemetry/sdk-trace-node": "^1.30.0",
+    "@opentelemetry/sdk-trace-web": "^1.30.0",
+    "@opentelemetry/semantic-conventions": "^1.27.0"
+  },
+  "peerDependencies": {
+    "@arcote.tech/arc": "^0.7.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}