intentkit-otel 1.0.0

package/README.md

@@ -0,0 +1,93 @@
+# intentkit-otel
+
+OpenTelemetry middleware for IntentKit. Exports function call telemetry as OTLP spans to any compatible backend (DataDog, Grafana Cloud, New Relic, Jaeger, etc.).
+
+## Install
+
+```bash
+npm install intentkit-otel
+```
+
+## Usage
+
+```typescript
+import { IntentRegistry, serve } from 'intentkit';
+import { createOtelMiddleware } from 'intentkit-otel';
+
+const { middleware, shutdown } = createOtelMiddleware({
+  endpoint: 'http://localhost:4318/v1/traces',
+  serviceName: 'my-agent-service',
+});
+
+const registry = new IntentRegistry()
+  .use(middleware)
+  .register(/* your functions */);
+
+await serve({ registry, context });
+
+// On process exit:
+process.on('SIGTERM', async () => {
+  await shutdown();
+  process.exit(0);
+});
+```
+
+## Span Attributes
+
+Every function call produces a span with:
+
+| Attribute | Description |
+|---|---|
+| `intentkit.function.name` | Function name (e.g., `create_task`) |
+| `intentkit.caller.role` | Caller's role (e.g., `admin`) |
+| `intentkit.caller.capabilities` | Comma-separated capabilities |
+| `intentkit.request.id` | Unique request UUID |
+| `intentkit.status` | `success` or `error` |
+| `intentkit.duration_ms` | Execution time in milliseconds |
+| `intentkit.events.count` | Number of events emitted |
+| `intentkit.events.names` | Comma-separated event names |
+
+## Backend Configuration
+
+### DataDog
+
+```typescript
+createOtelMiddleware({
+  endpoint: 'https://trace.agent.datadoghq.com/v1/traces',
+  serviceName: 'my-service',
+  headers: { 'DD-API-KEY': process.env.DD_API_KEY! },
+});
+```
+
+### Grafana Cloud
+
+```typescript
+createOtelMiddleware({
+  endpoint: 'https://otlp-gateway-prod-us-central-0.grafana.net/otlp/v1/traces',
+  serviceName: 'my-service',
+  headers: { Authorization: `Basic ${btoa(`${instanceId}:${apiKey}`)}` },
+});
+```
+
+### New Relic
+
+```typescript
+createOtelMiddleware({
+  endpoint: 'https://otlp.nr-data.net/v1/traces',
+  serviceName: 'my-service',
+  headers: { 'api-key': process.env.NEW_RELIC_LICENSE_KEY! },
+});
+```
+
+### Local (Jaeger)
+
+```typescript
+createOtelMiddleware({
+  endpoint: 'http://localhost:4318/v1/traces',
+  serviceName: 'my-service',
+});
+```
+
+## License
+
+MIT

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export { createOtelMiddleware } from './middleware.js';
+export type { OtelOptions } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,2 @@
+export { createOtelMiddleware } from './middleware.js';
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/src/middleware.d.ts

@@ -0,0 +1,18 @@
+import type { Middleware } from 'intentkit';
+import type { OtelOptions } from './types.js';
+/**
+ * Create an OpenTelemetry tracing middleware for IntentKit.
+ *
+ * Wraps every function call in an OTLP span with attributes for
+ * function name, caller role, capabilities, request ID, duration,
+ * and emitted events. Exports spans to any OTLP-compatible backend
+ * (DataDog, Grafana Cloud, New Relic, Jaeger, etc.).
+ *
+ * @returns middleware to register via `registry.use()` and a shutdown
+ *          function to flush pending spans on process exit.
+ */
+export declare function createOtelMiddleware(options: OtelOptions): {
+    middleware: Middleware;
+    shutdown: () => Promise<void>;
+};
+//# sourceMappingURL=middleware.d.ts.map

package/dist/src/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/middleware.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAqC,MAAM,WAAW,CAAC;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,WAAW,GAAG;IAC1D,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B,CA6FA"}

package/dist/src/middleware.js

@@ -0,0 +1,87 @@
+import { trace, SpanStatusCode } from '@opentelemetry/api';
+import { BasicTracerProvider, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { Resource } from '@opentelemetry/resources';
+/**
+ * Create an OpenTelemetry tracing middleware for IntentKit.
+ *
+ * Wraps every function call in an OTLP span with attributes for
+ * function name, caller role, capabilities, request ID, duration,
+ * and emitted events. Exports spans to any OTLP-compatible backend
+ * (DataDog, Grafana Cloud, New Relic, Jaeger, etc.).
+ *
+ * @returns middleware to register via `registry.use()` and a shutdown
+ *          function to flush pending spans on process exit.
+ */
+export function createOtelMiddleware(options) {
+    // --- Setup exporter + provider ---
+    const exporter = new OTLPTraceExporter({
+        url: options.endpoint,
+        headers: options.headers,
+    });
+    const resourceAttributes = {
+        'service.name': options.serviceName,
+        ...options.attributes,
+    };
+    const provider = new BasicTracerProvider({
+        resource: new Resource(resourceAttributes),
+    });
+    provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
+    provider.register();
+    const tracer = trace.getTracer('intentkit', '1.0.0');
+    // --- Build middleware ---
+    const middleware = {
+        name: 'intentkit-otel',
+        execute: async (fn, input, ctx, next) => {
+            const span = tracer.startSpan(fn.name);
+            // Set base attributes
+            span.setAttribute('intentkit.function.name', fn.name);
+            span.setAttribute('intentkit.caller.role', ctx.caller.role);
+            span.setAttribute('intentkit.caller.capabilities', ctx.caller.capabilities.join(','));
+            span.setAttribute('intentkit.request.id', ctx.requestId);
+            // Intercept ctx.emit to track emitted events
+            const emittedEvents = [];
+            const originalEmit = ctx.emit;
+            ctx.emit = (eventName, data) => {
+                emittedEvents.push(eventName);
+                return originalEmit.call(ctx, eventName, data);
+            };
+            const startTime = Date.now();
+            try {
+                const result = await next();
+                // Success attributes
+                span.setAttribute('intentkit.status', 'success');
+                span.setAttribute('intentkit.duration_ms', Date.now() - startTime);
+                span.setAttribute('intentkit.events.count', emittedEvents.length);
+                span.setAttribute('intentkit.events.names', emittedEvents.join(','));
+                span.setStatus({ code: SpanStatusCode.OK });
+                span.end();
+                // Restore original emit
+                ctx.emit = originalEmit;
+                return result;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                // Error attributes
+                span.setAttribute('intentkit.status', 'error');
+                span.setAttribute('intentkit.duration_ms', Date.now() - startTime);
+                span.setAttribute('intentkit.events.count', emittedEvents.length);
+                span.setAttribute('intentkit.events.names', emittedEvents.join(','));
+                span.setStatus({ code: SpanStatusCode.ERROR, message });
+                if (error instanceof Error) {
+                    span.recordException(error);
+                }
+                span.end();
+                // Restore original emit
+                ctx.emit = originalEmit;
+                throw error;
+            }
+        },
+    };
+    // --- Shutdown flushes pending spans ---
+    const shutdown = async () => {
+        await provider.shutdown();
+    };
+    return { middleware, shutdown };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/src/middleware.js.map

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

package/dist/src/types.d.ts

@@ -0,0 +1,13 @@
+export interface OtelOptions {
+    /** OTLP endpoint URL (e.g., http://localhost:4318/v1/traces) */
+    endpoint: string;
+    /** Service name for span attributes */
+    serviceName: string;
+    /** Additional resource attributes */
+    attributes?: Record<string, string>;
+    /** Export protocol (default: 'http') */
+    protocol?: 'http';
+    /** Headers to send with OTLP requests (e.g., for auth) */
+    headers?: Record<string, string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC"}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "intentkit-otel",
+  "version": "1.0.0",
+  "description": "OpenTelemetry middleware for IntentKit — export telemetry to DataDog, Grafana, New Relic",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  },
+  "files": ["dist", "src", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "intentkit": "^1.0.0"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-base": "^1.30.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.57.0"
+  },
+  "devDependencies": {
+    "intentkit": "^1.0.0",
+    "typescript": "^5.8.2"
+  },
+  "engines": { "node": ">=22.0.0" },
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/mosoahmed/intentkit" },
+  "keywords": ["intentkit", "mcp", "opentelemetry", "otel", "telemetry", "tracing", "ai-agent"]
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { createOtelMiddleware } from './middleware.js';
+export type { OtelOptions } from './types.js';

package/src/middleware.ts

@@ -0,0 +1,115 @@
+import { trace, SpanStatusCode, type Tracer } from '@opentelemetry/api';
+import { BasicTracerProvider, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { Resource } from '@opentelemetry/resources';
+import type { Middleware, IntentContext, RegisteredFunction } from 'intentkit';
+import type { OtelOptions } from './types.js';
+
+/**
+ * Create an OpenTelemetry tracing middleware for IntentKit.
+ *
+ * Wraps every function call in an OTLP span with attributes for
+ * function name, caller role, capabilities, request ID, duration,
+ * and emitted events. Exports spans to any OTLP-compatible backend
+ * (DataDog, Grafana Cloud, New Relic, Jaeger, etc.).
+ *
+ * @returns middleware to register via `registry.use()` and a shutdown
+ *          function to flush pending spans on process exit.
+ */
+export function createOtelMiddleware(options: OtelOptions): {
+  middleware: Middleware;
+  shutdown: () => Promise<void>;
+} {
+  // --- Setup exporter + provider ---
+  const exporter = new OTLPTraceExporter({
+    url: options.endpoint,
+    headers: options.headers,
+  });
+
+  const resourceAttributes: Record<string, string> = {
+    'service.name': options.serviceName,
+    ...options.attributes,
+  };
+
+  const provider = new BasicTracerProvider({
+    resource: new Resource(resourceAttributes),
+  });
+
+  provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
+  provider.register();
+
+  const tracer: Tracer = trace.getTracer('intentkit', '1.0.0');
+
+  // --- Build middleware ---
+  const middleware: Middleware = {
+    name: 'intentkit-otel',
+    execute: async (
+      fn: RegisteredFunction,
+      input: unknown,
+      ctx: IntentContext,
+      next: () => Promise<unknown>,
+    ): Promise<unknown> => {
+      const span = tracer.startSpan(fn.name);
+
+      // Set base attributes
+      span.setAttribute('intentkit.function.name', fn.name);
+      span.setAttribute('intentkit.caller.role', ctx.caller.role);
+      span.setAttribute('intentkit.caller.capabilities', ctx.caller.capabilities.join(','));
+      span.setAttribute('intentkit.request.id', ctx.requestId);
+
+      // Intercept ctx.emit to track emitted events
+      const emittedEvents: string[] = [];
+      const originalEmit = ctx.emit;
+      ctx.emit = (eventName: string, data: Record<string, unknown>) => {
+        emittedEvents.push(eventName);
+        return originalEmit.call(ctx, eventName, data);
+      };
+
+      const startTime = Date.now();
+
+      try {
+        const result = await next();
+
+        // Success attributes
+        span.setAttribute('intentkit.status', 'success');
+        span.setAttribute('intentkit.duration_ms', Date.now() - startTime);
+        span.setAttribute('intentkit.events.count', emittedEvents.length);
+        span.setAttribute('intentkit.events.names', emittedEvents.join(','));
+        span.setStatus({ code: SpanStatusCode.OK });
+        span.end();
+
+        // Restore original emit
+        ctx.emit = originalEmit;
+
+        return result;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+
+        // Error attributes
+        span.setAttribute('intentkit.status', 'error');
+        span.setAttribute('intentkit.duration_ms', Date.now() - startTime);
+        span.setAttribute('intentkit.events.count', emittedEvents.length);
+        span.setAttribute('intentkit.events.names', emittedEvents.join(','));
+        span.setStatus({ code: SpanStatusCode.ERROR, message });
+
+        if (error instanceof Error) {
+          span.recordException(error);
+        }
+
+        span.end();
+
+        // Restore original emit
+        ctx.emit = originalEmit;
+
+        throw error;
+      }
+    },
+  };
+
+  // --- Shutdown flushes pending spans ---
+  const shutdown = async (): Promise<void> => {
+    await provider.shutdown();
+  };
+
+  return { middleware, shutdown };
+}

package/src/types.ts

@@ -0,0 +1,12 @@
+export interface OtelOptions {
+  /** OTLP endpoint URL (e.g., http://localhost:4318/v1/traces) */
+  endpoint: string;
+  /** Service name for span attributes */
+  serviceName: string;
+  /** Additional resource attributes */
+  attributes?: Record<string, string>;
+  /** Export protocol (default: 'http') */
+  protocol?: 'http';
+  /** Headers to send with OTLP requests (e.g., for auth) */
+  headers?: Record<string, string>;
+}