opik-otel 2.0.19

package/README.md

@@ -0,0 +1,59 @@
+# Opik OpenTelemetry Integration
+
+[![npm version](https://img.shields.io/npm/v/opik-otel.svg)](https://www.npmjs.com/package/opik-otel)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/comet-ml/opik/blob/main/LICENSE)
+
+Bridge [OpenTelemetry](https://opentelemetry.io/) traces produced by your services into [Opik](https://www.comet.com/docs/opik/) so spans land under the correct Opik trace and parent span.
+
+## Features
+
+- 🔗 **`attachToParent`** — read `opik_trace_id` / `opik_parent_span_id` HTTP headers and stamp the matching attributes on an OpenTelemetry boundary span
+- 🌳 **`OpikSpanProcessor`** — propagate Opik IDs down an entire OTel subtree so descendants of the boundary span are linked to the same Opik trace and chain of parents
+- 🧰 **Header constants & types** — `OPIK_TRACE_ID`, `OPIK_SPAN_ID`, `OPIK_PARENT_SPAN_ID`, `OpikDistributedTraceAttributes`
+
+## Installation
+
+```bash
+# npm
+npm install opik-otel
+
+# yarn
+yarn add opik-otel
+
+# pnpm
+pnpm add opik-otel
+```
+
+### Requirements
+
+- Node.js ≥ 18
+- `@opentelemetry/api` ≥ 1.9
+- `@opentelemetry/sdk-trace-base` ≥ 1.30 (or v2)
+- Opik SDK (`opik` peer dependency)
+
+## Quick Start
+
+```typescript
+import { trace } from "@opentelemetry/api";
+import {
+  BasicTracerProvider,
+  BatchSpanProcessor,
+} from "@opentelemetry/sdk-trace-base";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { attachToParent, OpikSpanProcessor } from "opik-otel";
+
+const provider = new BasicTracerProvider();
+provider.addSpanProcessor(new BatchSpanProcessor(new OTLPTraceExporter()));
+provider.addSpanProcessor(new OpikSpanProcessor());
+provider.register();
+
+const tracer = trace.getTracer("my-service");
+
+// On every incoming request:
+const span = tracer.startSpan("server-span");
+attachToParent(span, request.headers);
+// ... handle the request; descendant spans inherit Opik IDs automatically
+span.end();
+```
+
+See the Opik documentation on [distributed traces with OpenTelemetry](https://www.comet.com/docs/opik/tracing/advanced/log_distributed_traces#distributed-traces-with-a-remote-service-using-opentelemetry) for the full client/server pattern.

package/dist/index.cjs

@@ -0,0 +1 @@
+'use strict';var opik=require('opik'),uuid=require('uuid'),api=require('@opentelemetry/api');var o="opik.trace_id",s="opik.span_id",p="opik.parent_span_id";var u=class{constructor(e,t){this.opikTraceId=e,this.opikParentSpanId=t;}asAttributes(){let e={[o]:this.opikTraceId};return this.opikParentSpanId!==void 0&&(e[p]=this.opikParentSpanId),e}};var I="opik_trace_id",l="opik_parent_span_id",d=r=>typeof r!="string"||!uuid.validate(r)?false:uuid.version(r)===7;function k(r,e){let t=e.toLowerCase();if(typeof r[Symbol.iterator]=="function"){for(let[n,a]of r)if(n.toLowerCase()===t)return a;return}let i=r;for(let[n,a]of Object.entries(i))if(n.toLowerCase()===t)return Array.isArray(a)?a[0]:a}function O(r){var i,n;let e=(i=k(r,I))==null?void 0:i.trim(),t=((n=k(r,l))==null?void 0:n.trim())||void 0;return e?d(e)?(t!==void 0&&!d(t)&&(opik.logger.warn(`Opik distributed trace header '${l}' is not a valid UUIDv7; ignoring parent span id.`),t=void 0),new u(e,t)):(opik.logger.warn(`Opik distributed trace header '${I}' is not a valid UUIDv7; skipping distributed trace processing.`),null):(t!==void 0&&opik.logger.warn(`Opik distributed trace header '${I}' is missing while '${l}' is provided; skipping distributed trace processing.`),null)}function x(r,e){let t=O(e);if(t===null)return  false;let i=t.asAttributes();return i[s]=opik.generateId(),r.setAttributes(i),true}function N(r){var m,A,S;let e=api.trace.getSpan(r);if(e&&"attributes"in e){let b=(m=e.attributes)!=null?m:{},f=b[o],g=b[s];if(f!==void 0||g!==void 0)if(!d(f))opik.logger.warn(`Parent span attribute '${o}' is missing or not a valid UUIDv7: ${JSON.stringify(f)}; ignoring inherited Opik context.`);else if(!d(g))opik.logger.warn(`Parent span attribute '${s}' is missing or not a valid UUIDv7: ${JSON.stringify(g)}; ignoring inherited Opik context.`);else return {traceId:f,parentSpanId:g}}let t=api.propagation.getBaggage(r),i=(A=t==null?void 0:t.getEntry(o))==null?void 0:A.value;if(i===void 0)return;if(!d(i)){opik.logger.warn(`Baggage value for '${o}' is not a valid UUIDv7: ${JSON.stringify(i)}; ignoring.`);return}let n=(S=t==null?void 0:t.getEntry(s))==null?void 0:S.value,a;return n===void 0?a=void 0:d(n)?a=n:(opik.logger.warn(`Baggage value for '${s}' is not a valid UUIDv7: ${JSON.stringify(n)}; attaching to '${o}' without a parent span id.`),a=void 0),{traceId:i,parentSpanId:a}}var P=class{onStart(e,t){let i=N(t);if(i)try{e.setAttribute(o,i.traceId),e.setAttribute(s,opik.generateId()),i.parentSpanId!==void 0&&e.setAttribute(p,i.parentSpanId);}catch(n){opik.logger.debug("OpikSpanProcessor.onStart failed:",n);}}onEnd(){}async forceFlush(){}async shutdown(){}};exports.OPIK_PARENT_SPAN_ID=p;exports.OPIK_SPAN_ID=s;exports.OPIK_TRACE_ID=o;exports.OpikDistributedTraceAttributes=u;exports.OpikSpanProcessor=P;exports.attachToParent=x;exports.extractOpikDistributedTraceAttributes=O;

package/dist/index.d.cts

@@ -0,0 +1,114 @@
+import { Span, Context } from '@opentelemetry/api';
+import { SpanProcessor } from '@opentelemetry/sdk-trace-base';
+
+/**
+ * Represents distributed trace attributes for the OPIK tracing system.
+ *
+ * This class provides a structured way to handle distributed trace attributes,
+ * specifically the trace ID and parent span ID. It exposes a method to convert
+ * those attributes into a plain object suitable for use as OpenTelemetry span
+ * attributes.
+ */
+declare class OpikDistributedTraceAttributes {
+    private readonly opikTraceId;
+    private readonly opikParentSpanId?;
+    /**
+     * @param opikTraceId The unique identifier for the trace.
+     * @param opikParentSpanId The identifier for the parent span in the trace,
+     * or undefined if this is the root span.
+     */
+    constructor(opikTraceId: string, opikParentSpanId?: string);
+    /**
+     * Converts the distributed trace attributes into a plain object suitable
+     * for OpenTelemetry `Span.setAttributes`.
+     */
+    asAttributes(): Record<string, string>;
+}
+
+/**
+ * Minimal structural type for an OpenTelemetry `Span`. Only the
+ * `setAttributes` method is required for distributed-trace propagation, so we
+ * avoid taking a runtime dependency on `@opentelemetry/api`. Any object that
+ * implements this method — including `import("@opentelemetry/api").Span` — is
+ * accepted.
+ */
+interface OpenTelemetrySpanLike {
+    setAttributes(attributes: Record<string, string>): unknown;
+}
+/**
+ * Headers carrying Opik distributed trace context. Accepts both plain
+ * dictionaries and any iterable of `[name, value]` pairs (e.g. the WHATWG
+ * `Headers` object).
+ */
+type HttpHeadersLike = Record<string, string | string[] | undefined> | Iterable<[string, string]>;
+/**
+ * Extracts Opik distributed trace attributes from HTTP headers.
+ *
+ * Reads `opik_trace_id` and the optional `opik_parent_span_id` headers
+ * (case-insensitive). Values are trimmed; if `opik_trace_id` is missing,
+ * empty, whitespace-only, or not a valid UUID the function logs a warning
+ * (when invalid, or when `opik_parent_span_id` was provided without a
+ * `opik_trace_id`) and returns `null`. If `opik_parent_span_id` is present
+ * but not a valid UUID it is dropped with a warning and the trace is still
+ * attached using the valid `opik_trace_id`.
+ */
+declare function extractOpikDistributedTraceAttributes(httpHeaders: HttpHeadersLike): OpikDistributedTraceAttributes | null;
+/**
+ * Attaches an Opik distributed trace parent to the provided OpenTelemetry
+ * span by extracting trace context from HTTP headers and setting the
+ * corresponding span attributes.
+ *
+ * @returns `true` if headers were found and attributes were set, `false`
+ * otherwise.
+ */
+declare function attachToParent(span: OpenTelemetrySpanLike, httpHeaders: HttpHeadersLike): boolean;
+
+/**
+ * OTel `SpanProcessor` that propagates Opik IDs down an attached subtree.
+ *
+ * `attachToParent` only sets `opik.trace_id` / `opik.parent_span_id` /
+ * `opik.span_id` on the *boundary* OTel span. Children created inside that
+ * span inherit OTel context but not those attributes, so without this
+ * processor descendants would be orphaned in a synthetic Opik trace by the
+ * backend.
+ *
+ * On every span start this processor inspects the parent OTel span (and OTel
+ * baggage, for cross-process boundaries). If the parent already carries
+ * `opik.trace_id` + `opik.span_id`, it mints a fresh `opik.span_id` for the
+ * new span and threads the parent's value as `opik.parent_span_id`. The
+ * backend `OpenTelemetryMapper` fast path then uses these UUIDs verbatim.
+ *
+ * Spans whose parent has no Opik attributes (and no baggage) are left
+ * untouched, so today's SHA-256 + Redis path still applies — the processor
+ * only kicks in for attached subtrees originating from `attachToParent`.
+ *
+ * @example
+ * ```ts
+ * import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
+ * import { OpikSpanProcessor } from "opik-otel";
+ *
+ * const provider = new BasicTracerProvider();
+ * provider.addSpanProcessor(new OpikSpanProcessor());
+ * // ... add your exporter processor as well
+ * ```
+ */
+declare class OpikSpanProcessor implements SpanProcessor {
+    onStart(span: Span, parentContext: Context): void;
+    onEnd(): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Canonical OTel attribute keys for Opik distributed tracing.
+ *
+ * These are the attribute names set on OpenTelemetry spans (and read by the
+ * Opik backend's `OpenTelemetryMapper`). They mirror the constants in
+ * `GeneralMappingRules.java` on the backend side and `attributes.py` in the
+ * Python SDK.
+ */
+declare const OPIK_TRACE_ID = "opik.trace_id";
+declare const OPIK_SPAN_ID = "opik.span_id";
+declare const OPIK_PARENT_SPAN_ID = "opik.parent_span_id";
+
+export { type HttpHeadersLike, OPIK_PARENT_SPAN_ID, OPIK_SPAN_ID, OPIK_TRACE_ID, type OpenTelemetrySpanLike, OpikDistributedTraceAttributes, OpikSpanProcessor, attachToParent, extractOpikDistributedTraceAttributes };

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+import { Span, Context } from '@opentelemetry/api';
+import { SpanProcessor } from '@opentelemetry/sdk-trace-base';
+
+/**
+ * Represents distributed trace attributes for the OPIK tracing system.
+ *
+ * This class provides a structured way to handle distributed trace attributes,
+ * specifically the trace ID and parent span ID. It exposes a method to convert
+ * those attributes into a plain object suitable for use as OpenTelemetry span
+ * attributes.
+ */
+declare class OpikDistributedTraceAttributes {
+    private readonly opikTraceId;
+    private readonly opikParentSpanId?;
+    /**
+     * @param opikTraceId The unique identifier for the trace.
+     * @param opikParentSpanId The identifier for the parent span in the trace,
+     * or undefined if this is the root span.
+     */
+    constructor(opikTraceId: string, opikParentSpanId?: string);
+    /**
+     * Converts the distributed trace attributes into a plain object suitable
+     * for OpenTelemetry `Span.setAttributes`.
+     */
+    asAttributes(): Record<string, string>;
+}
+
+/**
+ * Minimal structural type for an OpenTelemetry `Span`. Only the
+ * `setAttributes` method is required for distributed-trace propagation, so we
+ * avoid taking a runtime dependency on `@opentelemetry/api`. Any object that
+ * implements this method — including `import("@opentelemetry/api").Span` — is
+ * accepted.
+ */
+interface OpenTelemetrySpanLike {
+    setAttributes(attributes: Record<string, string>): unknown;
+}
+/**
+ * Headers carrying Opik distributed trace context. Accepts both plain
+ * dictionaries and any iterable of `[name, value]` pairs (e.g. the WHATWG
+ * `Headers` object).
+ */
+type HttpHeadersLike = Record<string, string | string[] | undefined> | Iterable<[string, string]>;
+/**
+ * Extracts Opik distributed trace attributes from HTTP headers.
+ *
+ * Reads `opik_trace_id` and the optional `opik_parent_span_id` headers
+ * (case-insensitive). Values are trimmed; if `opik_trace_id` is missing,
+ * empty, whitespace-only, or not a valid UUID the function logs a warning
+ * (when invalid, or when `opik_parent_span_id` was provided without a
+ * `opik_trace_id`) and returns `null`. If `opik_parent_span_id` is present
+ * but not a valid UUID it is dropped with a warning and the trace is still
+ * attached using the valid `opik_trace_id`.
+ */
+declare function extractOpikDistributedTraceAttributes(httpHeaders: HttpHeadersLike): OpikDistributedTraceAttributes | null;
+/**
+ * Attaches an Opik distributed trace parent to the provided OpenTelemetry
+ * span by extracting trace context from HTTP headers and setting the
+ * corresponding span attributes.
+ *
+ * @returns `true` if headers were found and attributes were set, `false`
+ * otherwise.
+ */
+declare function attachToParent(span: OpenTelemetrySpanLike, httpHeaders: HttpHeadersLike): boolean;
+
+/**
+ * OTel `SpanProcessor` that propagates Opik IDs down an attached subtree.
+ *
+ * `attachToParent` only sets `opik.trace_id` / `opik.parent_span_id` /
+ * `opik.span_id` on the *boundary* OTel span. Children created inside that
+ * span inherit OTel context but not those attributes, so without this
+ * processor descendants would be orphaned in a synthetic Opik trace by the
+ * backend.
+ *
+ * On every span start this processor inspects the parent OTel span (and OTel
+ * baggage, for cross-process boundaries). If the parent already carries
+ * `opik.trace_id` + `opik.span_id`, it mints a fresh `opik.span_id` for the
+ * new span and threads the parent's value as `opik.parent_span_id`. The
+ * backend `OpenTelemetryMapper` fast path then uses these UUIDs verbatim.
+ *
+ * Spans whose parent has no Opik attributes (and no baggage) are left
+ * untouched, so today's SHA-256 + Redis path still applies — the processor
+ * only kicks in for attached subtrees originating from `attachToParent`.
+ *
+ * @example
+ * ```ts
+ * import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
+ * import { OpikSpanProcessor } from "opik-otel";
+ *
+ * const provider = new BasicTracerProvider();
+ * provider.addSpanProcessor(new OpikSpanProcessor());
+ * // ... add your exporter processor as well
+ * ```
+ */
+declare class OpikSpanProcessor implements SpanProcessor {
+    onStart(span: Span, parentContext: Context): void;
+    onEnd(): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Canonical OTel attribute keys for Opik distributed tracing.
+ *
+ * These are the attribute names set on OpenTelemetry spans (and read by the
+ * Opik backend's `OpenTelemetryMapper`). They mirror the constants in
+ * `GeneralMappingRules.java` on the backend side and `attributes.py` in the
+ * Python SDK.
+ */
+declare const OPIK_TRACE_ID = "opik.trace_id";
+declare const OPIK_SPAN_ID = "opik.span_id";
+declare const OPIK_PARENT_SPAN_ID = "opik.parent_span_id";
+
+export { type HttpHeadersLike, OPIK_PARENT_SPAN_ID, OPIK_SPAN_ID, OPIK_TRACE_ID, type OpenTelemetrySpanLike, OpikDistributedTraceAttributes, OpikSpanProcessor, attachToParent, extractOpikDistributedTraceAttributes };

package/dist/index.js

@@ -0,0 +1 @@
+import {logger,generateId}from'opik';import {validate,version}from'uuid';import {trace,propagation}from'@opentelemetry/api';var o="opik.trace_id",s="opik.span_id",p="opik.parent_span_id";var u=class{constructor(e,t){this.opikTraceId=e,this.opikParentSpanId=t;}asAttributes(){let e={[o]:this.opikTraceId};return this.opikParentSpanId!==void 0&&(e[p]=this.opikParentSpanId),e}};var I="opik_trace_id",l="opik_parent_span_id",d=r=>typeof r!="string"||!validate(r)?false:version(r)===7;function k(r,e){let t=e.toLowerCase();if(typeof r[Symbol.iterator]=="function"){for(let[n,a]of r)if(n.toLowerCase()===t)return a;return}let i=r;for(let[n,a]of Object.entries(i))if(n.toLowerCase()===t)return Array.isArray(a)?a[0]:a}function O(r){var i,n;let e=(i=k(r,I))==null?void 0:i.trim(),t=((n=k(r,l))==null?void 0:n.trim())||void 0;return e?d(e)?(t!==void 0&&!d(t)&&(logger.warn(`Opik distributed trace header '${l}' is not a valid UUIDv7; ignoring parent span id.`),t=void 0),new u(e,t)):(logger.warn(`Opik distributed trace header '${I}' is not a valid UUIDv7; skipping distributed trace processing.`),null):(t!==void 0&&logger.warn(`Opik distributed trace header '${I}' is missing while '${l}' is provided; skipping distributed trace processing.`),null)}function x(r,e){let t=O(e);if(t===null)return  false;let i=t.asAttributes();return i[s]=generateId(),r.setAttributes(i),true}function N(r){var m,A,S;let e=trace.getSpan(r);if(e&&"attributes"in e){let b=(m=e.attributes)!=null?m:{},f=b[o],g=b[s];if(f!==void 0||g!==void 0)if(!d(f))logger.warn(`Parent span attribute '${o}' is missing or not a valid UUIDv7: ${JSON.stringify(f)}; ignoring inherited Opik context.`);else if(!d(g))logger.warn(`Parent span attribute '${s}' is missing or not a valid UUIDv7: ${JSON.stringify(g)}; ignoring inherited Opik context.`);else return {traceId:f,parentSpanId:g}}let t=propagation.getBaggage(r),i=(A=t==null?void 0:t.getEntry(o))==null?void 0:A.value;if(i===void 0)return;if(!d(i)){logger.warn(`Baggage value for '${o}' is not a valid UUIDv7: ${JSON.stringify(i)}; ignoring.`);return}let n=(S=t==null?void 0:t.getEntry(s))==null?void 0:S.value,a;return n===void 0?a=void 0:d(n)?a=n:(logger.warn(`Baggage value for '${s}' is not a valid UUIDv7: ${JSON.stringify(n)}; attaching to '${o}' without a parent span id.`),a=void 0),{traceId:i,parentSpanId:a}}var P=class{onStart(e,t){let i=N(t);if(i)try{e.setAttribute(o,i.traceId),e.setAttribute(s,generateId()),i.parentSpanId!==void 0&&e.setAttribute(p,i.parentSpanId);}catch(n){logger.debug("OpikSpanProcessor.onStart failed:",n);}}onEnd(){}async forceFlush(){}async shutdown(){}};export{p as OPIK_PARENT_SPAN_ID,s as OPIK_SPAN_ID,o as OPIK_TRACE_ID,u as OpikDistributedTraceAttributes,P as OpikSpanProcessor,x as attachToParent,O as extractOpikDistributedTraceAttributes};

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "opik-otel",
+  "description": "Opik TypeScript and JavaScript SDK integration with OpenTelemetry",
+  "version": "2.0.19",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/comet-ml/opik.git",
+    "directory": "sdks/typescript/src/opik/integrations/opik-otel"
+  },
+  "homepage": "https://www.comet.com/docs/opik/",
+  "author": {
+    "name": "Comet",
+    "email": "support@comet.com",
+    "url": "https://github.com/comet-ml"
+  },
+  "bugs": {
+    "url": "https://github.com/comet-ml/opik/issues",
+    "email": "support@comet.com"
+  },
+  "license": "Apache-2.0",
+  "keywords": [
+    "opik",
+    "opentelemetry",
+    "otel",
+    "tracing",
+    "distributed-tracing",
+    "sdk",
+    "javascript",
+    "javascript-sdk",
+    "typescript",
+    "typescript-sdk",
+    "comet"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsup",
+    "watch": "tsup --watch",
+    "lint": "eslint '**/*.{ts,tsx}'",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write 'src/**/*.{ts,tsx,js,jsx,json,md}'",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-base": "^1.30.0 || ^2.0.0",
+    "opik": "^2.0.15"
+  },
+  "dependencies": {
+    "uuid": "^11.0.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.20.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-base": "^2.7.0",
+    "@types/uuid": "^10.0.0",
+    "eslint": "^9.34.0",
+    "globals": "^15.14.0",
+    "prettier": "^3.6.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.42.0",
+    "vitest": "^3.0.5"
+  }
+}