@damngamerz/pi-otel 0.1.0-bootstrap.0

package/dist/telemetry/traces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traces.d.ts","sourceRoot":"","sources":["../../src/telemetry/traces.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAkBzD,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,gBAAgB;IAyBhB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAxBtC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAU1B;IAEF,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,SAAS,CAAe;IAChC,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,SAAS,CAAmB;IACpC,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,yBAAyB,CAAsB;IACvD,OAAO,CAAC,QAAQ,CAAmB;IACnC,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,SAAS,CAAwB;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiC;IAC7D,OAAO,CAAC,uBAAuB,CAAK;gBAEP,SAAS,EAAE,kBAAkB;IAE1D,YAAY,CAAC,mBAAmB,EAAE,MAAM,GAAG,IAAI;IAM/C,UAAU,IAAI,IAAI;IAqBlB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAelC,QAAQ,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAqBzD,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI1C,cAAc,IAAI,IAAI;IAStB,SAAS,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAoDtD,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAkBrD,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAwBtD,UAAU,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI;IAcnC,WAAW,IAAI,IAAI;IAenB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAsDxC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAU/B"}

package/dist/telemetry/traces.js

@@ -0,0 +1,265 @@
+import { SpanKind, SpanStatusCode, context, trace } from "@opentelemetry/api";
+import { safeTelemetryIdentifier } from "../privacy/sanitization.js";
+import { BASE_GEN_AI_ATTRIBUTES, modelAttributes } from "./attributes.js";
+import { extractUsage } from "./usage.js";
+export class TelemetryRuntime {
+    providers;
+    stats = {
+        prompts: 0,
+        turns: 0,
+        toolCalls: 0,
+        toolErrors: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        costUsd: 0,
+        evaluationRuns: 0,
+        evaluationCostUsd: 0,
+    };
+    sessionContext = context.active();
+    sessionId = "ephemeral";
+    sessionStartedAt = 0;
+    agentSpan;
+    agentContext = context.active();
+    lastCompletedAgentContext;
+    turnSpan;
+    turnContext = context.active();
+    activeLlm;
+    activeTools = new Map();
+    toolsInCurrentOperation = 0;
+    constructor(providers) {
+        this.providers = providers;
+    }
+    startSession(anonymizedSessionId) {
+        this.sessionId = anonymizedSessionId;
+        this.sessionContext = context.active();
+        this.sessionStartedAt = performance.now();
+    }
+    startAgent() {
+        this.finishAgent();
+        this.stats.prompts++;
+        this.providers.instruments.promptCount.add(1, BASE_GEN_AI_ATTRIBUTES);
+        this.agentSpan = this.providers.tracer.startSpan("invoke_agent pi", {
+            kind: SpanKind.INTERNAL,
+            attributes: {
+                ...BASE_GEN_AI_ATTRIBUTES,
+                "gen_ai.operation.name": "invoke_agent",
+                "gen_ai.agent.name": "pi",
+                "gen_ai.conversation.id": this.sessionId,
+            },
+        }, this.sessionContext);
+        this.agentContext = trace.setSpan(this.sessionContext, this.agentSpan);
+        this.toolsInCurrentOperation = 0;
+    }
+    startTurn(turnIndex) {
+        this.finishTurn();
+        this.stats.turns++;
+        this.providers.instruments.turnCount.add(1, BASE_GEN_AI_ATTRIBUTES);
+        this.turnSpan = this.providers.tracer.startSpan("pi turn", {
+            kind: SpanKind.INTERNAL,
+            attributes: { "pi.turn.index": turnIndex },
+        }, this.agentContext);
+        this.turnContext = trace.setSpan(this.agentContext, this.turnSpan);
+    }
+    startLlm(providerValue, modelValue) {
+        this.finishLlm(undefined, "retry");
+        const provider = safeTelemetryIdentifier(providerValue);
+        const model = safeTelemetryIdentifier(modelValue, "redacted", 128);
+        const span = this.providers.tracer.startSpan(`chat ${model}`, {
+            kind: SpanKind.CLIENT,
+            attributes: modelAttributes(provider, model),
+        }, this.turnContext);
+        this.activeLlm = {
+            span,
+            startedAt: performance.now(),
+            provider,
+            model,
+            firstTokenSeen: false,
+        };
+    }
+    noteProviderResponse(status) {
+        if (this.activeLlm)
+            this.activeLlm.responseStatus = status;
+    }
+    noteFirstToken() {
+        if (!this.activeLlm || this.activeLlm.firstTokenSeen)
+            return;
+        this.activeLlm.firstTokenSeen = true;
+        this.providers.instruments.timeToFirstToken.record(Math.max(0, (performance.now() - this.activeLlm.startedAt) / 1_000), modelAttributes(this.activeLlm.provider, this.activeLlm.model));
+    }
+    finishLlm(message, errorType) {
+        if (!this.activeLlm)
+            return;
+        const llm = this.activeLlm;
+        this.activeLlm = undefined;
+        const usage = extractUsage(message, llm.provider, llm.model);
+        const provider = safeTelemetryIdentifier(usage.provider);
+        const model = safeTelemetryIdentifier(usage.model, "redacted", 128);
+        const attributes = modelAttributes(provider, model);
+        this.providers.instruments.operationDuration.record(Math.max(0, (performance.now() - llm.startedAt) / 1_000), {
+            ...attributes,
+            ...(errorType ? { "error.type": safeTelemetryIdentifier(errorType) } : {}),
+        });
+        for (const [tokenType, amount] of [
+            ["input", usage.input],
+            ["output", usage.output],
+            ["cache_read", usage.cacheRead],
+            ["cache_write", usage.cacheWrite],
+        ]) {
+            if (amount > 0) {
+                this.providers.instruments.tokenUsage.record(amount, {
+                    ...attributes,
+                    "gen_ai.token.type": tokenType,
+                });
+            }
+        }
+        if (usage.costUsd > 0)
+            this.providers.instruments.costUsd.add(usage.costUsd, attributes);
+        this.stats.inputTokens += usage.input;
+        this.stats.outputTokens += usage.output;
+        this.stats.costUsd += usage.costUsd;
+        llm.span.setAttributes({
+            ...attributes,
+            "gen_ai.usage.input_tokens": usage.input,
+            "gen_ai.usage.output_tokens": usage.output,
+            "pi.usage.cache_read_tokens": usage.cacheRead,
+            "pi.usage.cache_write_tokens": usage.cacheWrite,
+            "pi.cost.usd": usage.costUsd,
+            ...(llm.responseStatus != null ? { "http.response.status_code": llm.responseStatus } : {}),
+        });
+        if (errorType || (llm.responseStatus != null && llm.responseStatus >= 400)) {
+            llm.span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: errorType ?? `HTTP ${llm.responseStatus}`,
+            });
+        }
+        else {
+            llm.span.setStatus({ code: SpanStatusCode.OK });
+        }
+        llm.span.end();
+    }
+    startTool(toolCallId, toolName) {
+        const name = safeTelemetryIdentifier(toolName, "redacted", 64);
+        const attributes = {
+            ...BASE_GEN_AI_ATTRIBUTES,
+            "gen_ai.tool.name": name,
+            "tool.name": name,
+        };
+        this.stats.toolCalls++;
+        this.toolsInCurrentOperation++;
+        this.providers.instruments.toolCalls.add(1, attributes);
+        const span = this.providers.tracer.startSpan(`execute_tool ${name}`, { kind: SpanKind.INTERNAL, attributes }, this.turnContext);
+        this.activeTools.set(toolCallId, { span, startedAt: performance.now(), name });
+    }
+    finishTool(toolCallId, isError) {
+        const tool = this.activeTools.get(toolCallId);
+        if (!tool)
+            return;
+        this.activeTools.delete(toolCallId);
+        const attributes = {
+            ...BASE_GEN_AI_ATTRIBUTES,
+            "gen_ai.tool.name": tool.name,
+            "tool.name": tool.name,
+        };
+        this.providers.instruments.toolDuration.record(Math.max(0, (performance.now() - tool.startedAt) / 1_000), attributes);
+        if (isError) {
+            this.stats.toolErrors++;
+            this.providers.instruments.toolErrors.add(1, attributes);
+            tool.span.setAttribute("error.type", "tool_error");
+            tool.span.setStatus({ code: SpanStatusCode.ERROR, message: "Tool execution failed" });
+        }
+        else {
+            tool.span.setStatus({ code: SpanStatusCode.OK });
+        }
+        tool.span.end();
+    }
+    finishTurn(message) {
+        if (this.activeLlm && message)
+            this.finishLlm(message);
+        this.finishLlm(undefined, "incomplete");
+        for (const [toolCallId, tool] of this.activeTools) {
+            tool.span.setStatus({ code: SpanStatusCode.ERROR, message: "Tool span incomplete" });
+            tool.span.end();
+            this.activeTools.delete(toolCallId);
+        }
+        this.turnSpan?.setStatus({ code: SpanStatusCode.OK });
+        this.turnSpan?.end();
+        this.turnSpan = undefined;
+        this.turnContext = this.agentContext;
+    }
+    finishAgent() {
+        this.finishTurn();
+        if (!this.agentSpan)
+            return;
+        this.providers.instruments.toolCallsPerOperation.record(this.toolsInCurrentOperation, {
+            ...BASE_GEN_AI_ATTRIBUTES,
+            "gen_ai.operation.name": "invoke_agent",
+        });
+        this.lastCompletedAgentContext = this.agentContext;
+        this.agentSpan.setStatus({ code: SpanStatusCode.OK });
+        this.agentSpan.end();
+        this.agentSpan = undefined;
+        this.agentContext = this.sessionContext;
+        this.toolsInCurrentOperation = 0;
+    }
+    recordEvaluation(batch) {
+        const provider = safeTelemetryIdentifier(batch.provider);
+        const model = safeTelemetryIdentifier(batch.model, "redacted", 128);
+        const attributes = modelAttributes(provider, model, "evaluate");
+        this.providers.instruments.operationDuration.record(Math.max(0, batch.durationSeconds), attributes);
+        for (const [tokenType, amount] of [
+            ["input", batch.usage.input],
+            ["output", batch.usage.output],
+            ["cache_read", batch.usage.cacheRead],
+            ["cache_write", batch.usage.cacheWrite],
+        ]) {
+            if (amount > 0) {
+                this.providers.instruments.tokenUsage.record(amount, {
+                    ...attributes,
+                    "gen_ai.token.type": tokenType,
+                });
+            }
+        }
+        if (batch.usage.costUsd > 0) {
+            this.providers.instruments.costUsd.add(batch.usage.costUsd, attributes);
+        }
+        this.stats.evaluationRuns++;
+        this.stats.evaluationCostUsd += batch.usage.costUsd;
+        const span = this.providers.tracer.startSpan(`evaluate ${model}`, {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                ...attributes,
+                "gen_ai.usage.input_tokens": batch.usage.input,
+                "gen_ai.usage.output_tokens": batch.usage.output,
+                "pi.cost.usd": batch.usage.costUsd,
+            },
+        }, this.lastCompletedAgentContext ?? this.sessionContext);
+        for (const result of batch.scores) {
+            if (result.score < 0 || result.score > 1)
+                continue;
+            const evaluationAttributes = {
+                "gen_ai.evaluation.name": safeTelemetryIdentifier(result.name, "redacted", 64),
+                "gen_ai.evaluation.score.label": safeTelemetryIdentifier(result.label, "redacted", 32),
+                "gen_ai.evaluation.evaluator.provider": provider,
+                "gen_ai.evaluation.evaluator.model": model,
+            };
+            this.providers.instruments.evaluationScore.record(result.score, evaluationAttributes);
+            span.addEvent("gen_ai.evaluation.result", {
+                ...evaluationAttributes,
+                "gen_ai.evaluation.score.value": result.score,
+            });
+        }
+        span.setStatus({ code: SpanStatusCode.OK });
+        span.end();
+    }
+    async forceFlush() {
+        await this.providers.forceFlush();
+    }
+    async shutdown() {
+        this.finishAgent();
+        if (this.sessionStartedAt > 0) {
+            this.providers.instruments.sessionDuration.record(Math.max(0, (performance.now() - this.sessionStartedAt) / 1_000), BASE_GEN_AI_ATTRIBUTES);
+        }
+        await this.providers.shutdown();
+    }
+}
+//# sourceMappingURL=traces.js.map

package/dist/telemetry/traces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traces.js","sourceRoot":"","sources":["../../src/telemetry/traces.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,KAAK,EAA2B,MAAM,oBAAoB,CAAC;AAEvG,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE1E,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA6B1C,MAAM,OAAO,gBAAgB;IAyBC;IAxBpB,KAAK,GAAiB;QAC9B,OAAO,EAAE,CAAC;QACV,KAAK,EAAE,CAAC;QACR,SAAS,EAAE,CAAC;QACZ,UAAU,EAAE,CAAC;QACb,WAAW,EAAE,CAAC;QACd,YAAY,EAAE,CAAC;QACf,OAAO,EAAE,CAAC;QACV,cAAc,EAAE,CAAC;QACjB,iBAAiB,EAAE,CAAC;KACpB,CAAC;IAEM,cAAc,GAAY,OAAO,CAAC,MAAM,EAAE,CAAC;IAC3C,SAAS,GAAG,WAAW,CAAC;IACxB,gBAAgB,GAAG,CAAC,CAAC;IACrB,SAAS,CAAmB;IAC5B,YAAY,GAAY,OAAO,CAAC,MAAM,EAAE,CAAC;IACzC,yBAAyB,CAAsB;IAC/C,QAAQ,CAAmB;IAC3B,WAAW,GAAY,OAAO,CAAC,MAAM,EAAE,CAAC;IACxC,SAAS,CAAwB;IACxB,WAAW,GAAG,IAAI,GAAG,EAAsB,CAAC;IACrD,uBAAuB,GAAG,CAAC,CAAC;IAEpC,YAA6B,SAA6B;QAA7B,cAAS,GAAT,SAAS,CAAoB;IAAG,CAAC;IAE9D,YAAY,CAAC,mBAA2B;QACvC,IAAI,CAAC,SAAS,GAAG,mBAAmB,CAAC;QACrC,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;QACvC,IAAI,CAAC,gBAAgB,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAC3C,CAAC;IAED,UAAU;QACT,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACrB,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,EAAE,sBAAsB,CAAC,CAAC;QACtE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAC/C,iBAAiB,EACjB;YACC,IAAI,EAAE,QAAQ,CAAC,QAAQ;YACvB,UAAU,EAAE;gBACX,GAAG,sBAAsB;gBACzB,uBAAuB,EAAE,cAAc;gBACvC,mBAAmB,EAAE,IAAI;gBACzB,wBAAwB,EAAE,IAAI,CAAC,SAAS;aACxC;SACD,EACD,IAAI,CAAC,cAAc,CACnB,CAAC;QACF,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACvE,IAAI,CAAC,uBAAuB,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,SAAS,CAAC,SAAiB;QAC1B,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,sBAAsB,CAAC,CAAC;QACpE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAC9C,SAAS,EACT;YACC,IAAI,EAAE,QAAQ,CAAC,QAAQ;YACvB,UAAU,EAAE,EAAE,eAAe,EAAE,SAAS,EAAE;SAC1C,EACD,IAAI,CAAC,YAAY,CACjB,CAAC;QACF,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACpE,CAAC;IAED,QAAQ,CAAC,aAAqB,EAAE,UAAkB;QACjD,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACnC,MAAM,QAAQ,GAAG,uBAAuB,CAAC,aAAa,CAAC,CAAC;QACxD,MAAM,KAAK,GAAG,uBAAuB,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;QACnE,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAC3C,QAAQ,KAAK,EAAE,EACf;YACC,IAAI,EAAE,QAAQ,CAAC,MAAM;YACrB,UAAU,EAAE,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC;SAC5C,EACD,IAAI,CAAC,WAAW,CAChB,CAAC;QACF,IAAI,CAAC,SAAS,GAAG;YAChB,IAAI;YACJ,SAAS,EAAE,WAAW,CAAC,GAAG,EAAE;YAC5B,QAAQ;YACR,KAAK;YACL,cAAc,EAAE,KAAK;SACrB,CAAC;IACH,CAAC;IAED,oBAAoB,CAAC,MAAc;QAClC,IAAI,IAAI,CAAC,SAAS;YAAE,IAAI,CAAC,SAAS,CAAC,cAAc,GAAG,MAAM,CAAC;IAC5D,CAAC;IAED,cAAc;QACb,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,cAAc;YAAE,OAAO;QAC7D,IAAI,CAAC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC;QACrC,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,gBAAgB,CAAC,MAAM,CACjD,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC,EACnE,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAC9D,CAAC;IACH,CAAC;IAED,SAAS,CAAC,OAAiB,EAAE,SAAkB;QAC9C,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,OAAO;QAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC;QAC3B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,EAAE,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;QAC7D,MAAM,QAAQ,GAAG,uBAAuB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACzD,MAAM,KAAK,GAAG,uBAAuB,CAAC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;QACpE,MAAM,UAAU,GAAG,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACpD,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,iBAAiB,CAAC,MAAM,CAClD,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC,EACxD;YACC,GAAG,UAAU;YACb,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,uBAAuB,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1E,CACD,CAAC;QACF,KAAK,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI;YACjC,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC;YACtB,CAAC,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC;YACxB,CAAC,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC;YAC/B,CAAC,aAAa,EAAE,KAAK,CAAC,UAAU,CAAC;SACxB,EAAE,CAAC;YACZ,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;gBAChB,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE;oBACpD,GAAG,UAAU;oBACb,mBAAmB,EAAE,SAAS;iBAC9B,CAAC,CAAC;YACJ,CAAC;QACF,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,GAAG,CAAC;YAAE,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QACzF,IAAI,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,KAAK,CAAC;QACtC,IAAI,CAAC,KAAK,CAAC,YAAY,IAAI,KAAK,CAAC,MAAM,CAAC;QACxC,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC;QACpC,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC;YACtB,GAAG,UAAU;YACb,2BAA2B,EAAE,KAAK,CAAC,KAAK;YACxC,4BAA4B,EAAE,KAAK,CAAC,MAAM;YAC1C,4BAA4B,EAAE,KAAK,CAAC,SAAS;YAC7C,6BAA6B,EAAE,KAAK,CAAC,UAAU;YAC/C,aAAa,EAAE,KAAK,CAAC,OAAO;YAC5B,GAAG,CAAC,GAAG,CAAC,cAAc,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,2BAA2B,EAAE,GAAG,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1F,CAAC,CAAC;QACH,IAAI,SAAS,IAAI,CAAC,GAAG,CAAC,cAAc,IAAI,IAAI,IAAI,GAAG,CAAC,cAAc,IAAI,GAAG,CAAC,EAAE,CAAC;YAC5E,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;gBAClB,IAAI,EAAE,cAAc,CAAC,KAAK;gBAC1B,OAAO,EAAE,SAAS,IAAI,QAAQ,GAAG,CAAC,cAAc,EAAE;aAClD,CAAC,CAAC;QACJ,CAAC;aAAM,CAAC;YACP,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC;QACjD,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;IAChB,CAAC;IAED,SAAS,CAAC,UAAkB,EAAE,QAAgB;QAC7C,MAAM,IAAI,GAAG,uBAAuB,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC;QAC/D,MAAM,UAAU,GAAG;YAClB,GAAG,sBAAsB;YACzB,kBAAkB,EAAE,IAAI;YACxB,WAAW,EAAE,IAAI;SACjB,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QACvB,IAAI,CAAC,uBAAuB,EAAE,CAAC;QAC/B,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;QACxD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAC3C,gBAAgB,IAAI,EAAE,EACtB,EAAE,IAAI,EAAE,QAAQ,CAAC,QAAQ,EAAE,UAAU,EAAE,EACvC,IAAI,CAAC,WAAW,CAChB,CAAC;QACF,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IAChF,CAAC;IAED,UAAU,CAAC,UAAkB,EAAE,OAAgB;QAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI;YAAE,OAAO;QAClB,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACpC,MAAM,UAAU,GAAG;YAClB,GAAG,sBAAsB;YACzB,kBAAkB,EAAE,IAAI,CAAC,IAAI;YAC7B,WAAW,EAAE,IAAI,CAAC,IAAI;SACtB,CAAC;QACF,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,YAAY,CAAC,MAAM,CAC7C,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC,EACzD,UAAU,CACV,CAAC;QACF,IAAI,OAAO,EAAE,CAAC;YACb,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;YACxB,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;YACzD,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;YACnD,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC,CAAC;QACvF,CAAC;aAAM,CAAC;YACP,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC;QAClD,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;IACjB,CAAC;IAED,UAAU,CAAC,OAAiB;QAC3B,IAAI,IAAI,CAAC,SAAS,IAAI,OAAO;YAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACvD,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;QACxC,KAAK,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACnD,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,sBAAsB,EAAE,CAAC,CAAC;YACrF,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACrC,CAAC;QACD,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC;QACtD,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;QAC1B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC;IACtC,CAAC;IAED,WAAW;QACV,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,OAAO;QAC5B,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,qBAAqB,CAAC,MAAM,CAAC,IAAI,CAAC,uBAAuB,EAAE;YACrF,GAAG,sBAAsB;YACzB,uBAAuB,EAAE,cAAc;SACvC,CAAC,CAAC;QACH,IAAI,CAAC,yBAAyB,GAAG,IAAI,CAAC,YAAY,CAAC;QACnD,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC;QACtD,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,cAAc,CAAC;QACxC,IAAI,CAAC,uBAAuB,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,gBAAgB,CAAC,KAAsB;QACtC,MAAM,QAAQ,GAAG,uBAAuB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACzD,MAAM,KAAK,GAAG,uBAAuB,CAAC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;QACpE,MAAM,UAAU,GAAG,eAAe,CAAC,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;QAChE,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,eAAe,CAAC,EAAE,UAAU,CAAC,CAAC;QACpG,KAAK,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI;YACjC,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC;YAC5B,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC;YAC9B,CAAC,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC;YACrC,CAAC,aAAa,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC;SAC9B,EAAE,CAAC;YACZ,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;gBAChB,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE;oBACpD,GAAG,UAAU;oBACb,mBAAmB,EAAE,SAAS;iBAC9B,CAAC,CAAC;YACJ,CAAC;QACF,CAAC;QACD,IAAI,KAAK,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;YAC7B,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QACzE,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,cAAc,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,iBAAiB,IAAI,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC;QACpD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAC3C,YAAY,KAAK,EAAE,EACnB;YACC,IAAI,EAAE,QAAQ,CAAC,MAAM;YACrB,UAAU,EAAE;gBACX,GAAG,UAAU;gBACb,2BAA2B,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK;gBAC9C,4BAA4B,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM;gBAChD,aAAa,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO;aAClC;SACD,EACD,IAAI,CAAC,yBAAyB,IAAI,IAAI,CAAC,cAAc,CACrD,CAAC;QACF,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YACnC,IAAI,MAAM,CAAC,KAAK,GAAG,CAAC,IAAI,MAAM,CAAC,KAAK,GAAG,CAAC;gBAAE,SAAS;YACnD,MAAM,oBAAoB,GAAG;gBAC5B,wBAAwB,EAAE,uBAAuB,CAAC,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,CAAC;gBAC9E,+BAA+B,EAAE,uBAAuB,CAAC,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC;gBACtF,sCAAsC,EAAE,QAAQ;gBAChD,mCAAmC,EAAE,KAAK;aAC1C,CAAC;YACF,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,oBAAoB,CAAC,CAAC;YACtF,IAAI,CAAC,QAAQ,CAAC,0BAA0B,EAAE;gBACzC,GAAG,oBAAoB;gBACvB,+BAA+B,EAAE,MAAM,CAAC,KAAK;aAC7C,CAAC,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC;QAC5C,IAAI,CAAC,GAAG,EAAE,CAAC;IACZ,CAAC;IAED,KAAK,CAAC,UAAU;QACf,MAAM,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,QAAQ;QACb,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,IAAI,CAAC,gBAAgB,GAAG,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,eAAe,CAAC,MAAM,CAChD,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,KAAK,CAAC,EAChE,sBAAsB,CACtB,CAAC;QACH,CAAC;QACD,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC;CACD"}

package/dist/telemetry/usage.d.ts

@@ -0,0 +1,11 @@
+export interface ModelUsage {
+    provider: string;
+    model: string;
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    costUsd: number;
+}
+export declare function extractUsage(message: unknown, fallbackProvider?: string, fallbackModel?: string): ModelUsage;
+//# sourceMappingURL=usage.d.ts.map

package/dist/telemetry/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/telemetry/usage.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,YAAY,CAC3B,OAAO,EAAE,OAAO,EAChB,gBAAgB,SAAY,EAC5B,aAAa,SAAY,GACvB,UAAU,CAgCZ"}

package/dist/telemetry/usage.js

@@ -0,0 +1,25 @@
+import { finiteNumber, safeDimension } from "../privacy/sanitization.js";
+export function extractUsage(message, fallbackProvider = "unknown", fallbackModel = "unknown") {
+    if (!message || typeof message !== "object") {
+        return {
+            provider: fallbackProvider,
+            model: fallbackModel,
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            costUsd: 0,
+        };
+    }
+    const candidate = message;
+    return {
+        provider: safeDimension(candidate.provider, fallbackProvider),
+        model: safeDimension(candidate.model, fallbackModel),
+        input: finiteNumber(candidate.usage?.input),
+        output: finiteNumber(candidate.usage?.output),
+        cacheRead: finiteNumber(candidate.usage?.cacheRead),
+        cacheWrite: finiteNumber(candidate.usage?.cacheWrite),
+        costUsd: finiteNumber(candidate.usage?.cost?.total),
+    };
+}
+//# sourceMappingURL=usage.js.map

package/dist/telemetry/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/telemetry/usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAYzE,MAAM,UAAU,YAAY,CAC3B,OAAgB,EAChB,gBAAgB,GAAG,SAAS,EAC5B,aAAa,GAAG,SAAS;IAEzB,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC7C,OAAO;YACN,QAAQ,EAAE,gBAAgB;YAC1B,KAAK,EAAE,aAAa;YACpB,KAAK,EAAE,CAAC;YACR,MAAM,EAAE,CAAC;YACT,SAAS,EAAE,CAAC;YACZ,UAAU,EAAE,CAAC;YACb,OAAO,EAAE,CAAC;SACV,CAAC;IACH,CAAC;IACD,MAAM,SAAS,GAAG,OAUjB,CAAC;IACF,OAAO;QACN,QAAQ,EAAE,aAAa,CAAC,SAAS,CAAC,QAAQ,EAAE,gBAAgB,CAAC;QAC7D,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,KAAK,EAAE,aAAa,CAAC;QACpD,KAAK,EAAE,YAAY,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC;QAC3C,MAAM,EAAE,YAAY,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC;QAC7C,SAAS,EAAE,YAAY,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC;QACnD,UAAU,EAAE,YAAY,CAAC,SAAS,CAAC,KAAK,EAAE,UAAU,CAAC;QACrD,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC;KACnD,CAAC;AACH,CAAC"}

package/docs/configuration.md

@@ -0,0 +1,61 @@
+# Configuration
+
+Configuration is read from `~/.pi/agent/settings.json` and, for trusted projects, `.pi/settings.json`. Project values override global values; environment variables override both.
+
+```jsonc
+{
+  "piOtel": {
+    "enabled": true,
+    "endpoint": "http://127.0.0.1:4318",
+    "allowRemoteEndpoint": false,
+    "headers": {},
+    "serviceName": "pi",
+    "signals": {
+      "traces": true,
+      "metrics": true
+    },
+    "evaluation": {
+      "mode": "off",
+      "sampleRate": 0.1,
+      "provider": "openai-codex",
+      "model": "gpt-5.4-mini",
+      "maxCharsPerField": 12000,
+      "blockLikelySecrets": true
+    }
+  }
+}
+```
+
+## Evaluation modes
+
+| Mode | Behavior |
+|---|---|
+| `off` | Default. No conversation content is sent to an evaluator. |
+| `manual` | `/otel-eval-last` evaluates the latest exchange. |
+| `sample` | Deterministically evaluates `sampleRate` of settled exchanges. Manual evaluation remains available. |
+| `always` | Evaluates every settled exchange. Manual evaluation remains available. |
+
+`sample` decisions are stable for the same exchange, so retries do not change selection.
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `PI_OTEL_ENABLED` | Enable or disable the extension |
+| `PI_OTEL_ENDPOINT` | OTLP base URL |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Standard OTLP base URL fallback |
+| `OTEL_EXPORTER_OTLP_HEADERS` | Comma-separated `key=value` headers |
+| `OTEL_SERVICE_NAME` | OTel service name |
+| `PI_OTEL_ALLOW_REMOTE_ENDPOINT` | Permit non-loopback OTLP endpoints |
+| `PI_OTEL_TRACES` | Enable traces |
+| `PI_OTEL_METRICS` | Enable metrics |
+| `PI_OTEL_EVALUATION_MODE` | `off`, `manual`, `sample`, or `always` |
+| `PI_OTEL_EVALUATION_SAMPLE_RATE` | Number from `0` to `1` |
+| `PI_OTEL_EVALUATION_PROVIDER` | Pi judge provider |
+| `PI_OTEL_EVALUATION_MODEL` | Pi judge model ID |
+| `PI_OTEL_EVALUATION_MAX_CHARS` | Per-field limit from `256` to `100000` |
+| `PI_OTEL_EVALUATION_BLOCK_SECRETS` | Enable likely-secret blocking |
+
+## Remote collectors
+
+Remote endpoints are rejected unless `allowRemoteEndpoint` is explicitly enabled, and non-loopback endpoints must use HTTPS. Use OTLP headers for remote credentials; credentials embedded in endpoint URLs are always rejected. Malformed or incorrectly typed `piOtel` settings are rejected rather than coerced.

package/docs/evaluation.md

@@ -0,0 +1,38 @@
+# Response evaluation
+
+The optional remote judge evaluates four dimensions:
+
+- `task_success`
+- `instruction_following`
+- `relevance`
+- `correctness`
+
+Scores are validated numbers from `0` to `1`. Labels are restricted to `poor`, `fair`, `good`, and `excellent`. Invalid judge output is rejected rather than recorded.
+
+## Correlation
+
+Evaluation spans inherit the evaluated agent trace context. This makes the quality score visible beside the original Pi request, LLM calls, and tool activity without adding trace IDs to metric labels.
+
+## Manual evaluation
+
+Enable manual mode:
+
+```json
+{
+  "piOtel": {
+    "evaluation": {
+      "mode": "manual"
+    }
+  }
+}
+```
+
+Then run:
+
+```text
+/otel-eval-last
+```
+
+## Cost
+
+Judge requests consume additional provider tokens. Judge token usage, latency, and cost are recorded under `gen_ai.operation.name=evaluate`. Use `manual` or `sample` mode when cost must be bounded.

package/docs/metrics.md

@@ -0,0 +1,27 @@
+# Metrics
+
+## GenAI metrics
+
+| Metric | Type | Unit |
+|---|---|---|
+| `gen_ai.client.operation.duration` | Histogram | seconds |
+| `gen_ai.client.token.usage` | Histogram | tokens |
+| `gen_ai.client.tool_calls_per_operation` | Histogram | calls |
+| `gen_ai.client.tool.calls` | Counter | calls |
+| `gen_ai.evaluation.score` | Histogram | ratio |
+
+## Pi metrics
+
+| Metric | Type | Unit |
+|---|---|---|
+| `pi.agent.prompts` | Counter | prompts |
+| `pi.agent.turns` | Counter | turns |
+| `pi.agent.tool.duration` | Histogram | seconds |
+| `pi.agent.tool.errors` | Counter | errors |
+| `pi.agent.session.duration` | Histogram | seconds |
+| `pi.agent.time_to_first_token` | Histogram | seconds |
+| `pi.agent.cost` | Counter | USD |
+
+Metric labels are intentionally low-cardinality. Session IDs, trace IDs, prompts, paths, and numeric evaluation values are not used as labels.
+
+Evaluation results are represented both as score histograms and as `gen_ai.evaluation.result` events on a correlated evaluation span.

package/docs/operations.md

@@ -0,0 +1,41 @@
+# Operations
+
+## Commands
+
+- `/otel-status` — endpoint health, evaluation mode, and current-session counters
+- `/otel-flush` — force-flush trace and metric buffers
+- `/otel-eval-last` — evaluate the latest exchange when evaluation is enabled
+
+## Local backend
+
+Use the pinned Compose stack under `examples/grafana-lgtm/`.
+
+```bash
+cd examples/grafana-lgtm
+docker compose up -d
+docker compose ps
+```
+
+The example binds OTLP and Grafana ports to `127.0.0.1` only.
+
+## Disable
+
+Set this in Pi settings:
+
+```json
+{
+  "piOtel": {
+    "enabled": false
+  }
+}
+```
+
+Or set `PI_OTEL_ENABLED=0`.
+
+## Uninstall
+
+```bash
+pi remove npm:@damngamerz/pi-otel
+```
+
+The package does not install or manage Docker services, systemd units, credentials, or data directories.

package/docs/privacy.md

@@ -0,0 +1,38 @@
+# Privacy model
+
+## Baseline telemetry
+
+Baseline traces and metrics include only:
+
+- provider and model names
+- token and cache-token counts
+- request, turn, tool, and session durations
+- tool names and error status
+- cost reported by Pi
+- anonymized session identifiers
+
+Provider, model, tool, error, and evaluation identifiers must match a bounded identifier syntax. Values containing path separators—including hierarchical model IDs—or resembling identity data, secrets, or free-form content are exported as `redacted`.
+
+They exclude:
+
+- prompts and responses
+- thinking or reasoning text
+- provider payloads
+- tool arguments and results
+- shell commands
+- file paths and cwd
+- usernames, hostnames, and email addresses
+
+## Remote evaluation
+
+Remote evaluation is disabled by default. When enabled, the latest user request and assistant text are sent to the configured Pi model. Tool results, thinking blocks, images, provider payloads, and system prompts are not included.
+
+Safeguards:
+
+- likely credentials and private keys cause a hard skip by default
+- each text field is capped before transmission
+- duplicate exchanges are evaluated once
+- judge prompts and explanations are not exported through OTel
+- only bounded scores, score labels, judge model, usage, latency, and cost are recorded
+
+Secret detection is defense in depth, not a guarantee. Do not enable remote evaluation for conversations that may contain sensitive data unless the configured provider and organizational policy permit it.

package/examples/grafana-lgtm/LICENSE

@@ -0,0 +1,6 @@
+SPDX-License-Identifier: Apache-2.0
+
+The dashboard.json file is adapted from https://github.com/NikiforovAll/pi-otel,
+Copyright 2026 Oleksii Nikiforov, and remains subject to the Apache License 2.0.
+
+See ../../NOTICE and ../../LICENSES/Apache-2.0.txt.

package/examples/grafana-lgtm/README.md

@@ -0,0 +1,47 @@
+# Local Grafana LGTM example
+
+This optional Compose stack provides Grafana, Tempo, Prometheus, Loki, and an OpenTelemetry Collector on loopback-only ports.
+
+## Start
+
+```bash
+docker compose up -d
+```
+
+Open <http://127.0.0.1:33000/d/damngamerz-pi-otel/atdamngamerz-pi-otel>.
+
+Default endpoints:
+
+- OTLP gRPC: `127.0.0.1:4317`
+- OTLP HTTP: `http://127.0.0.1:4318`
+- Grafana: `http://127.0.0.1:33000`
+
+Override host ports when necessary:
+
+```bash
+GRAFANA_PORT=34000 OTLP_HTTP_PORT=14318 docker compose up -d
+```
+
+The image is pinned by version and digest, Linux capabilities are dropped, and all host bindings use `127.0.0.1`.
+
+## Start after reboot
+
+The example uses `restart: unless-stopped`. Ensure Docker itself is enabled at boot:
+
+```bash
+systemctl is-enabled docker
+```
+
+Use `restart: always` if the container must restart after reboot even when it was manually stopped previously.
+
+## Stop and remove
+
+```bash
+docker compose down
+```
+
+Telemetry is ephemeral and is removed with the container.
+
+## Dashboard attribution
+
+The dashboard is adapted from [`NikiforovAll/pi-otel`](https://github.com/NikiforovAll/pi-otel), Copyright 2026 Oleksii Nikiforov, under Apache-2.0. See the repository `NOTICE` and `LICENSES/Apache-2.0.txt` files.

package/examples/grafana-lgtm/compose.yaml

@@ -0,0 +1,16 @@
+services:
+  lgtm:
+    image: grafana/otel-lgtm:0.29.1@sha256:b4da8bf6b1b44f6f683883869619eb9781465c642ce5f2d70591fb27094ddb1c
+    container_name: damngamerz-pi-otel-lgtm
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:${OTLP_GRPC_PORT:-4317}:4317"
+      - "127.0.0.1:${OTLP_HTTP_PORT:-4318}:4318"
+      - "127.0.0.1:${GRAFANA_PORT:-33000}:3000"
+    volumes:
+      - ./dashboard.json:/dashboards/damngamerz-pi-otel.json:ro
+      - ./provisioning.yaml:/otel-lgtm/grafana/conf/provisioning/dashboards/damngamerz-pi-otel.yaml:ro
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL