@introspection-sdk/introspection-pi 0.7.0 → 0.7.2

package/dist/metrics.js

@@ -0,0 +1,64 @@
+/**
+ * GenAI client metric instruments per the OTel GenAI semconv metrics doc.
+ *
+ * Instruments are created lazily per `Meter` and cached, so repeated
+ * `instrumentStream` / `instrumentAgent` calls sharing a meter reuse the
+ * same histograms. Bucket boundaries follow the spec's
+ * ExplicitBucketBoundaries advice where one is defined.
+ */
+/** Spec advice for `gen_ai.client.token.usage`. */
+const TOKEN_BUCKETS = [
+    1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304,
+    16777216, 67108864,
+];
+/** Spec advice for the client duration / chunk-timing histograms. */
+const DURATION_BUCKETS = [
+    0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48,
+    40.96, 81.92,
+];
+/** Spec advice for in-process agent invocation durations. */
+const AGENT_DURATION_BUCKETS = [
+    0.1, 0.2, 0.4, 0.8, 1.6, 3.2, 6.4, 12.8, 25.6, 51.2, 102.4, 204.8, 409.6,
+];
+const metricsByMeter = new WeakMap();
+/** Get (or create) the GenAI instruments for a meter. */
+export function genAiMetrics(meter) {
+    const cached = metricsByMeter.get(meter);
+    if (cached)
+        return cached;
+    const metrics = {
+        tokenUsage: meter.createHistogram("gen_ai.client.token.usage", {
+            description: "Number of input and output tokens used.",
+            unit: "{token}",
+            advice: { explicitBucketBoundaries: TOKEN_BUCKETS },
+        }),
+        operationDuration: meter.createHistogram("gen_ai.client.operation.duration", {
+            description: "GenAI operation duration.",
+            unit: "s",
+            advice: { explicitBucketBoundaries: DURATION_BUCKETS },
+        }),
+        timeToFirstChunk: meter.createHistogram("gen_ai.client.operation.time_to_first_chunk", {
+            description: "Time to receive the first chunk of the response stream, measured from request issuance.",
+            unit: "s",
+            advice: { explicitBucketBoundaries: DURATION_BUCKETS },
+        }),
+        timePerOutputChunk: meter.createHistogram("gen_ai.client.operation.time_per_output_chunk", {
+            description: "Time per output chunk, recorded for each chunk received after the first one.",
+            unit: "s",
+            advice: { explicitBucketBoundaries: DURATION_BUCKETS },
+        }),
+        executeToolDuration: meter.createHistogram("gen_ai.execute_tool.duration", {
+            description: "The duration of a single tool execution.",
+            unit: "s",
+            advice: { explicitBucketBoundaries: DURATION_BUCKETS },
+        }),
+        invokeAgentDuration: meter.createHistogram("gen_ai.invoke_agent.duration", {
+            description: "The end-to-end duration of a single in-process agent invocation.",
+            unit: "s",
+            advice: { explicitBucketBoundaries: AGENT_DURATION_BUCKETS },
+        }),
+    };
+    metricsByMeter.set(meter, metrics);
+    return metrics;
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,mDAAmD;AACnD,MAAM,aAAa,GAAG;IACpB,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;IACrE,QAAQ,EAAE,QAAQ;CACnB,CAAC;AAEF,qEAAqE;AACrE,MAAM,gBAAgB,GAAG;IACvB,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK;IACxE,KAAK,EAAE,KAAK;CACb,CAAC;AAEF,6DAA6D;AAC7D,MAAM,sBAAsB,GAAG;IAC7B,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;CACzE,CAAC;AAiBF,MAAM,cAAc,GAAG,IAAI,OAAO,EAAuB,CAAC;AAE1D,yDAAyD;AACzD,MAAM,UAAU,YAAY,CAAC,KAAY;IACvC,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACzC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,OAAO,GAAiB;QAC5B,UAAU,EAAE,KAAK,CAAC,eAAe,CAAC,2BAA2B,EAAE;YAC7D,WAAW,EAAE,yCAAyC;YACtD,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,EAAE,wBAAwB,EAAE,aAAa,EAAE;SACpD,CAAC;QACF,iBAAiB,EAAE,KAAK,CAAC,eAAe,CACtC,kCAAkC,EAClC;YACE,WAAW,EAAE,2BAA2B;YACxC,IAAI,EAAE,GAAG;YACT,MAAM,EAAE,EAAE,wBAAwB,EAAE,gBAAgB,EAAE;SACvD,CACF;QACD,gBAAgB,EAAE,KAAK,CAAC,eAAe,CACrC,6CAA6C,EAC7C;YACE,WAAW,EACT,yFAAyF;YAC3F,IAAI,EAAE,GAAG;YACT,MAAM,EAAE,EAAE,wBAAwB,EAAE,gBAAgB,EAAE;SACvD,CACF;QACD,kBAAkB,EAAE,KAAK,CAAC,eAAe,CACvC,+CAA+C,EAC/C;YACE,WAAW,EACT,8EAA8E;YAChF,IAAI,EAAE,GAAG;YACT,MAAM,EAAE,EAAE,wBAAwB,EAAE,gBAAgB,EAAE;SACvD,CACF;QACD,mBAAmB,EAAE,KAAK,CAAC,eAAe,CAAC,8BAA8B,EAAE;YACzE,WAAW,EAAE,0CAA0C;YACvD,IAAI,EAAE,GAAG;YACT,MAAM,EAAE,EAAE,wBAAwB,EAAE,gBAAgB,EAAE;SACvD,CAAC;QACF,mBAAmB,EAAE,KAAK,CAAC,eAAe,CAAC,8BAA8B,EAAE;YACzE,WAAW,EACT,kEAAkE;YACpE,IAAI,EAAE,GAAG;YACT,MAAM,EAAE,EAAE,wBAAwB,EAAE,sBAAsB,EAAE;SAC7D,CAAC;KACH,CAAC;IAEF,cAAc,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@introspection-sdk/introspection-pi",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "license": "Apache-2.0",
   "description": "Introspection observability extension for the Pi Agent SDK — OTEL GenAI semantic-convention spans for chat completions and tool execution",
   "type": "module",
@@ -17,7 +17,7 @@
   ],
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
-    "@introspection-sdk/types": "0.7.0"
+    "@introspection-sdk/types": "0.7.2"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.75.0",
@@ -32,8 +32,8 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.80.2",
-    "@earendil-works/pi-ai": "^0.80.2",
+    "@earendil-works/pi-agent-core": "^0.80.3",
+    "@earendil-works/pi-ai": "^0.80.3",
     "@types/node": "^22.20.0",
     "eslint": "^9.39.4",
     "typescript": "5.9.3",