@criterionx/opentelemetry 0.3.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Tomas Maritano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,197 @@
+import { Decision, RunOptions, ProfileRegistry, Result, Engine } from '@criterionx/core';
+import { Tracer, Meter } from '@opentelemetry/api';
+
+/**
+ * Options for creating a traced engine
+ */
+interface TracedEngineOptions {
+    /** OpenTelemetry Tracer instance */
+    tracer?: Tracer;
+    /** OpenTelemetry Meter instance for metrics */
+    meter?: Meter;
+    /** Include input data in span attributes (careful with PII) */
+    recordInput?: boolean;
+    /** Include output data in span attributes */
+    recordOutput?: boolean;
+    /** Include profile data in span attributes */
+    recordProfile?: boolean;
+    /** Custom span name prefix (default: "criterion") */
+    spanNamePrefix?: string;
+}
+/**
+ * Span attributes added to decision evaluation spans
+ */
+interface DecisionSpanAttributes {
+    "criterion.decision.id": string;
+    "criterion.decision.version": string;
+    "criterion.status": string;
+    "criterion.matched_rule"?: string;
+    "criterion.rules_evaluated": number;
+    "criterion.profile_id"?: string;
+    "criterion.input"?: string;
+    "criterion.output"?: string;
+    "criterion.profile"?: string;
+    "criterion.error"?: string;
+}
+/**
+ * Metric names used by the instrumentation
+ */
+declare const METRIC_NAMES: {
+    /** Counter for decision evaluations */
+    readonly EVALUATIONS: "criterion.evaluations";
+    /** Histogram for evaluation duration */
+    readonly DURATION: "criterion.duration";
+    /** Counter for matched rules */
+    readonly RULES_MATCHED: "criterion.rules.matched";
+    /** Counter for errors */
+    readonly ERRORS: "criterion.errors";
+};
+/**
+ * Metric label names
+ */
+declare const METRIC_LABELS: {
+    readonly DECISION_ID: "decision_id";
+    readonly DECISION_VERSION: "decision_version";
+    readonly STATUS: "status";
+    readonly RULE_ID: "rule_id";
+    readonly ERROR_TYPE: "error_type";
+};
+/**
+ * Interface for a traced engine that wraps the base Engine
+ */
+interface TracedEngine {
+    /** Run a decision with tracing */
+    run<TInput, TOutput, TProfile>(decision: Decision<TInput, TOutput, TProfile>, context: TInput, options: RunOptions<TProfile>, registry?: ProfileRegistry<TProfile>): Result<TOutput>;
+    /** Get the underlying engine */
+    getEngine(): Engine;
+}
+
+/**
+ * OpenTelemetry tracing for Criterion decision engine
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { trace } from "@opentelemetry/api";
+ * import { createTracedEngine } from "@criterionx/opentelemetry";
+ *
+ * const tracedEngine = createTracedEngine({
+ *   tracer: trace.getTracer("my-app"),
+ * });
+ *
+ * const result = tracedEngine.run(decision, input, { profile });
+ * // Automatically creates a span with decision metadata
+ * ```
+ */
+
+/**
+ * Create a traced engine that wraps decision evaluation with OpenTelemetry spans
+ *
+ * @example With custom options
+ * ```typescript
+ * const tracedEngine = createTracedEngine({
+ *   tracer: trace.getTracer("my-service", "1.0.0"),
+ *   recordInput: true,  // Include input in span (careful with PII)
+ *   recordOutput: true, // Include output in span
+ *   spanNamePrefix: "decisions",
+ * });
+ * ```
+ */
+declare function createTracedEngine(options?: TracedEngineOptions): TracedEngine;
+/**
+ * Wrap an existing engine with tracing capabilities
+ *
+ * @example
+ * ```typescript
+ * import { Engine } from "@criterionx/core";
+ * import { wrapEngine } from "@criterionx/opentelemetry";
+ *
+ * const engine = new Engine();
+ * const tracedEngine = wrapEngine(engine, {
+ *   tracer: myTracer,
+ * });
+ * ```
+ */
+declare function wrapEngine(engine: Engine, options?: TracedEngineOptions): TracedEngine;
+
+/**
+ * OpenTelemetry metrics for Criterion decision engine
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { metrics } from "@opentelemetry/api";
+ * import { createMetricsRecorder, recordEvaluation } from "@criterionx/opentelemetry";
+ *
+ * const recorder = createMetricsRecorder({
+ *   meter: metrics.getMeter("my-app"),
+ * });
+ *
+ * // After running a decision
+ * recorder.recordEvaluation(decision, result, durationMs);
+ * ```
+ */
+
+/**
+ * Options for creating a metrics recorder
+ */
+interface MetricsRecorderOptions {
+    /** OpenTelemetry Meter instance */
+    meter?: Meter;
+    /** Metric name prefix (default: "criterion") */
+    prefix?: string;
+}
+/**
+ * Metrics recorder for decision evaluations
+ */
+interface MetricsRecorder {
+    /** Record a decision evaluation */
+    recordEvaluation<TOutput>(decision: Decision<unknown, TOutput, unknown>, result: Result<TOutput>, durationMs: number): void;
+}
+/**
+ * Create a metrics recorder for decision evaluations
+ *
+ * Records:
+ * - `criterion.evaluations` (counter): Total evaluations by decision_id, status
+ * - `criterion.duration` (histogram): Evaluation duration in milliseconds
+ * - `criterion.rules.matched` (counter): Rule matches by decision_id, rule_id
+ * - `criterion.errors` (counter): Errors by decision_id, error_type
+ *
+ * @example
+ * ```typescript
+ * import { metrics } from "@opentelemetry/api";
+ * import { createMetricsRecorder } from "@criterionx/opentelemetry";
+ *
+ * const recorder = createMetricsRecorder({
+ *   meter: metrics.getMeter("my-service"),
+ * });
+ *
+ * // Use with engine
+ * const start = performance.now();
+ * const result = engine.run(decision, input, { profile });
+ * const duration = performance.now() - start;
+ *
+ * recorder.recordEvaluation(decision, result, duration);
+ * ```
+ */
+declare function createMetricsRecorder(options?: MetricsRecorderOptions): MetricsRecorder;
+/**
+ * Create a metered engine that automatically records metrics
+ *
+ * Combines the base engine with automatic metrics recording.
+ *
+ * @example
+ * ```typescript
+ * import { createMeteredEngine } from "@criterionx/opentelemetry";
+ *
+ * const engine = createMeteredEngine({
+ *   meter: metrics.getMeter("my-service"),
+ * });
+ *
+ * // Metrics are automatically recorded
+ * const result = engine.run(decision, input, { profile });
+ * ```
+ */
+declare function createMeteredEngine(options?: MetricsRecorderOptions): {
+    run<TInput, TOutput, TProfile>(decision: Decision<TInput, TOutput, TProfile>, context: TInput, runOptions: RunOptions<TProfile>, registry?: ProfileRegistry<TProfile>): Result<TOutput>;
+};
+
+export { type DecisionSpanAttributes, METRIC_LABELS, METRIC_NAMES, type MetricsRecorder, type MetricsRecorderOptions, type TracedEngine, type TracedEngineOptions, createMeteredEngine, createMetricsRecorder, createTracedEngine, wrapEngine };

package/dist/index.js

@@ -0,0 +1,234 @@
+// src/tracing.ts
+import {
+  trace,
+  SpanKind,
+  SpanStatusCode
+} from "@opentelemetry/api";
+import { Engine } from "@criterionx/core";
+var DEFAULT_SPAN_PREFIX = "criterion";
+function createTracedEngine(options = {}) {
+  const {
+    tracer = trace.getTracer("@criterionx/opentelemetry"),
+    recordInput = false,
+    recordOutput = false,
+    recordProfile = false,
+    spanNamePrefix = DEFAULT_SPAN_PREFIX
+  } = options;
+  const engine = new Engine();
+  return {
+    run(decision, context, runOptions, registry) {
+      const spanName = `${spanNamePrefix}.${decision.id}`;
+      return tracer.startActiveSpan(spanName, { kind: SpanKind.INTERNAL }, (span) => {
+        const startTime = performance.now();
+        try {
+          span.setAttribute("criterion.decision.id", decision.id);
+          span.setAttribute("criterion.decision.version", decision.version);
+          if (recordInput) {
+            span.setAttribute("criterion.input", JSON.stringify(context));
+          }
+          if (typeof runOptions.profile === "string") {
+            span.setAttribute("criterion.profile_id", runOptions.profile);
+          } else if (recordProfile) {
+            span.setAttribute("criterion.profile", JSON.stringify(runOptions.profile));
+          }
+          const result = engine.run(decision, context, runOptions, registry);
+          span.setAttribute("criterion.status", result.status);
+          span.setAttribute("criterion.rules_evaluated", result.meta.evaluatedRules.length);
+          if (result.status === "OK" && result.meta.matchedRule) {
+            span.setAttribute("criterion.matched_rule", result.meta.matchedRule);
+          }
+          if (result.meta.profileId) {
+            span.setAttribute("criterion.profile_id", result.meta.profileId);
+          }
+          if (recordOutput && result.data) {
+            span.setAttribute("criterion.output", JSON.stringify(result.data));
+          }
+          if (result.status === "OK") {
+            span.setStatus({ code: SpanStatusCode.OK });
+          } else {
+            span.setStatus({
+              code: SpanStatusCode.ERROR,
+              message: result.meta.explanation
+            });
+            span.setAttribute("criterion.error", result.meta.explanation);
+          }
+          const duration = performance.now() - startTime;
+          span.setAttribute("criterion.duration_ms", duration);
+          return result;
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          span.recordException(err);
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: err.message
+          });
+          span.setAttribute("criterion.error", err.message);
+          throw error;
+        } finally {
+          span.end();
+        }
+      });
+    },
+    getEngine() {
+      return engine;
+    }
+  };
+}
+function wrapEngine(engine, options = {}) {
+  const {
+    tracer = trace.getTracer("@criterionx/opentelemetry"),
+    recordInput = false,
+    recordOutput = false,
+    recordProfile = false,
+    spanNamePrefix = DEFAULT_SPAN_PREFIX
+  } = options;
+  return {
+    run(decision, context, runOptions, registry) {
+      const spanName = `${spanNamePrefix}.${decision.id}`;
+      return tracer.startActiveSpan(spanName, { kind: SpanKind.INTERNAL }, (span) => {
+        const startTime = performance.now();
+        try {
+          span.setAttribute("criterion.decision.id", decision.id);
+          span.setAttribute("criterion.decision.version", decision.version);
+          if (recordInput) {
+            span.setAttribute("criterion.input", JSON.stringify(context));
+          }
+          if (typeof runOptions.profile === "string") {
+            span.setAttribute("criterion.profile_id", runOptions.profile);
+          } else if (recordProfile) {
+            span.setAttribute("criterion.profile", JSON.stringify(runOptions.profile));
+          }
+          const result = engine.run(decision, context, runOptions, registry);
+          span.setAttribute("criterion.status", result.status);
+          span.setAttribute("criterion.rules_evaluated", result.meta.evaluatedRules.length);
+          if (result.status === "OK" && result.meta.matchedRule) {
+            span.setAttribute("criterion.matched_rule", result.meta.matchedRule);
+          }
+          if (result.meta.profileId) {
+            span.setAttribute("criterion.profile_id", result.meta.profileId);
+          }
+          if (recordOutput && result.data) {
+            span.setAttribute("criterion.output", JSON.stringify(result.data));
+          }
+          if (result.status === "OK") {
+            span.setStatus({ code: SpanStatusCode.OK });
+          } else {
+            span.setStatus({
+              code: SpanStatusCode.ERROR,
+              message: result.meta.explanation
+            });
+            span.setAttribute("criterion.error", result.meta.explanation);
+          }
+          const duration = performance.now() - startTime;
+          span.setAttribute("criterion.duration_ms", duration);
+          return result;
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          span.recordException(err);
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: err.message
+          });
+          span.setAttribute("criterion.error", err.message);
+          throw error;
+        } finally {
+          span.end();
+        }
+      });
+    },
+    getEngine() {
+      return engine;
+    }
+  };
+}
+
+// src/metrics.ts
+import { metrics } from "@opentelemetry/api";
+import { Engine as Engine2 } from "@criterionx/core";
+
+// src/types.ts
+var METRIC_NAMES = {
+  /** Counter for decision evaluations */
+  EVALUATIONS: "criterion.evaluations",
+  /** Histogram for evaluation duration */
+  DURATION: "criterion.duration",
+  /** Counter for matched rules */
+  RULES_MATCHED: "criterion.rules.matched",
+  /** Counter for errors */
+  ERRORS: "criterion.errors"
+};
+var METRIC_LABELS = {
+  DECISION_ID: "decision_id",
+  DECISION_VERSION: "decision_version",
+  STATUS: "status",
+  RULE_ID: "rule_id",
+  ERROR_TYPE: "error_type"
+};
+
+// src/metrics.ts
+function createMetricsRecorder(options = {}) {
+  const {
+    meter = metrics.getMeter("@criterionx/opentelemetry"),
+    prefix = "criterion"
+  } = options;
+  const evaluationsCounter = meter.createCounter(`${prefix}.evaluations`, {
+    description: "Total number of decision evaluations",
+    unit: "1"
+  });
+  const durationHistogram = meter.createHistogram(`${prefix}.duration`, {
+    description: "Decision evaluation duration",
+    unit: "ms"
+  });
+  const rulesMatchedCounter = meter.createCounter(`${prefix}.rules.matched`, {
+    description: "Number of rule matches by rule ID",
+    unit: "1"
+  });
+  const errorsCounter = meter.createCounter(`${prefix}.errors`, {
+    description: "Number of evaluation errors",
+    unit: "1"
+  });
+  return {
+    recordEvaluation(decision, result, durationMs) {
+      const labels = {
+        [METRIC_LABELS.DECISION_ID]: decision.id,
+        [METRIC_LABELS.DECISION_VERSION]: decision.version,
+        [METRIC_LABELS.STATUS]: result.status
+      };
+      evaluationsCounter.add(1, labels);
+      durationHistogram.record(durationMs, labels);
+      if (result.status === "OK" && result.meta.matchedRule) {
+        rulesMatchedCounter.add(1, {
+          [METRIC_LABELS.DECISION_ID]: decision.id,
+          [METRIC_LABELS.RULE_ID]: result.meta.matchedRule
+        });
+      }
+      if (result.status !== "OK") {
+        errorsCounter.add(1, {
+          [METRIC_LABELS.DECISION_ID]: decision.id,
+          [METRIC_LABELS.ERROR_TYPE]: result.status
+        });
+      }
+    }
+  };
+}
+function createMeteredEngine(options = {}) {
+  const engine = new Engine2();
+  const recorder = createMetricsRecorder(options);
+  return {
+    run(decision, context, runOptions, registry) {
+      const start = performance.now();
+      const result = engine.run(decision, context, runOptions, registry);
+      const duration = performance.now() - start;
+      recorder.recordEvaluation(decision, result, duration);
+      return result;
+    }
+  };
+}
+export {
+  METRIC_LABELS,
+  METRIC_NAMES,
+  createMeteredEngine,
+  createMetricsRecorder,
+  createTracedEngine,
+  wrapEngine
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@criterionx/opentelemetry",
+  "version": "0.3.5",
+  "description": "OpenTelemetry instrumentation for Criterion decision engine",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@criterionx/core": "0.3.5"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-base": "^1.29.0",
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.0",
+    "zod": "^3.23.0"
+  },
+  "keywords": [
+    "criterion",
+    "opentelemetry",
+    "tracing",
+    "metrics",
+    "observability",
+    "instrumentation"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tomymaritano/criterionx.git",
+    "directory": "packages/opentelemetry"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}