@juspay/neurolink 13.4.10 → 13.5.1

package/dist/services/server/ai/observability/otlpSetup.js

@@ -1,3 +1,5 @@
+import { Agent as HttpAgent } from "node:http";
+import { Agent as HttpsAgent } from "node:https";
 import { metrics } from "@opentelemetry/api";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
@@ -5,14 +7,57 @@ import { MeterProvider, PeriodicExportingMetricReader, } from "@opentelemetry/sd
 import { BatchSpanProcessor, } from "@opentelemetry/sdk-trace-base";
 import { OTEL_LOG_PREFIX } from "../../../../constants/telemetry.js";
 import { logger } from "../../../../utils/logger.js";
+// The exporters retry a 429, 502, 503 or 504 after a backoff and hand the retried
+// request the time that was left before the backoff, not after it, so a retry
+// into a collector that never answers outlives the flush budget by the backoff.
+const CUT_AGAIN_MS = 100;
+/**
+ * @description Tracks the connections the OTLP exporters open, so a flush or shutdown that has run out of its budget can close them instead of leaving a request in flight that holds the process open.
+ * @returns {OtlpConnections} The agent factory to give the exporters and the function that closes what they opened.
+ */
+export function createOtlpConnections() {
+    const agents = new Set();
+    const destroyAll = () => {
+        for (const agent of agents) {
+            agent.destroy();
+        }
+    };
+    return {
+        agentFor: (protocol) => {
+            const agent = protocol === "https:"
+                ? new HttpsAgent({ keepAlive: true })
+                : new HttpAgent({ keepAlive: true });
+            agents.add(agent);
+            return agent;
+        },
+        cut: () => {
+            destroyAll();
+            setTimeout(destroyAll, CUT_AGAIN_MS).unref();
+        },
+    };
+}
+// The request timeout also bounds how long an exit flush can hold the process
+// when the collector cannot be reached; the OTLP timeout variables still win.
+function requestTimeout(signal, budgetMs) {
+    return process.env.OTEL_EXPORTER_OTLP_TIMEOUT ||
+        process.env[`OTEL_EXPORTER_OTLP_${signal}_TIMEOUT`]
+        ? undefined
+        : budgetMs;
+}
 /**
  * @description Builds a batching span processor that ships spans to an OTLP/HTTP endpoint.
  * @param endpoint {string} - OTLP base URL; `/v1/traces` is appended.
+ * @param budgetMs {number | undefined} - Request timeout in milliseconds, used unless `OTEL_EXPORTER_OTLP_TIMEOUT` or `OTEL_EXPORTER_OTLP_TRACES_TIMEOUT` is set; the exporter's default when omitted.
+ * @param connections {OtlpConnections | undefined} - Tracks the connections the exporter opens so they can be closed when a flush runs out of its budget.
  * @returns {SpanProcessor | null} The processor, or `null` (after a warning) when the exporter cannot be created.
  */
-export function createOtlpSpanProcessor(endpoint) {
+export function createOtlpSpanProcessor(endpoint, budgetMs, connections) {
     try {
-        return new BatchSpanProcessor(new OTLPTraceExporter({ url: `${endpoint}/v1/traces` }), {
+        return new BatchSpanProcessor(new OTLPTraceExporter({
+            url: `${endpoint}/v1/traces`,
+            timeoutMillis: requestTimeout("TRACES", budgetMs),
+            ...(connections && { httpAgentOptions: connections.agentFor }),
+        }), {
             maxQueueSize: 2048,
             maxExportBatchSize: 512,
             scheduledDelayMillis: 1000,
@@ -31,15 +76,21 @@ export function createOtlpSpanProcessor(endpoint) {
  * @description Builds a meter provider that exports metrics to an OTLP/HTTP endpoint and registers it as the global meter provider.
  * @param endpoint {string} - OTLP base URL; `/v1/metrics` is appended.
  * @param resource {Resource} - Resource describing the service.
+ * @param budgetMs {number | undefined} - Request timeout in milliseconds, used unless `OTEL_EXPORTER_OTLP_TIMEOUT` or `OTEL_EXPORTER_OTLP_METRICS_TIMEOUT` is set; the exporter's default when omitted.
+ * @param connections {OtlpConnections | undefined} - Tracks the connections the exporter opens so they can be closed when a flush runs out of its budget.
  * @returns {MeterProvider | null} The provider, or `null` (after a warning) when it cannot be created.
  */
-export function createOtlpMeterProvider(endpoint, resource) {
+export function createOtlpMeterProvider(endpoint, resource, budgetMs, connections) {
     try {
         const provider = new MeterProvider({
             resource,
             readers: [
                 new PeriodicExportingMetricReader({
-                    exporter: new OTLPMetricExporter({ url: `${endpoint}/v1/metrics` }),
+                    exporter: new OTLPMetricExporter({
+                        url: `${endpoint}/v1/metrics`,
+                        timeoutMillis: requestTimeout("METRICS", budgetMs),
+                        ...(connections && { httpAgentOptions: connections.agentFor }),
+                    }),
                     exportIntervalMillis: 15000,
                     exportTimeoutMillis: 10000,
                 }),

package/dist/telemetry/aiMetrics.d.ts

@@ -0,0 +1,56 @@
+import type { MetricConnectionType } from "../types/index.js";
+/**
+ * @description Counts one AI request with its duration, tokens and, when known, cost, labelled by provider and model.
+ * @param provider {string} - Provider that served the request.
+ * @param model {string} - Model that served the request.
+ * @param tokens {number} - Total tokens used.
+ * @param durationMs {number} - Request duration in milliseconds.
+ * @param cost {number | undefined} - Cost in USD; omitted or non-positive values add nothing to the cost counter.
+ * @returns {void} Nothing.
+ */
+export declare function recordAIRequest(provider: string, model: string, tokens: number, durationMs: number, cost?: number): void;
+/**
+ * @description Counts one AI provider error, labelled by provider, error name and a bounded `message`: the HTTP status the error carries (`HTTP 429`), or `unspecified`, never the message text.
+ * @param provider {string} - Provider that failed.
+ * @param error {Error} - The failure.
+ * @returns {void} Nothing.
+ */
+export declare function recordAIError(provider: string, error: Error): void;
+/**
+ * @description Counts one MCP tool call, labelled by tool, outcome and a duration bucket (`fast`, `medium`, `slow`, `very_slow`).
+ * @param toolName {string} - Name of the tool.
+ * @param durationMs {number} - Call duration in milliseconds.
+ * @param success {boolean} - `false` for a thrown error and for a resolved MCP error result.
+ * @returns {void} Nothing.
+ */
+export declare function recordMCPToolCall(toolName: string, durationMs: number, success: boolean): void;
+/**
+ * @description Counts one opened connection, labelled by its type.
+ * @param type {MetricConnectionType} - `websocket`, `sse` or `http`.
+ * @returns {void} Nothing.
+ */
+export declare function recordConnection(type: MetricConnectionType): void;
+/**
+ * @description Records one server response time, labelled by endpoint, method and a status bucket (`excellent`, `good`, `acceptable`, `poor`).
+ * @param endpoint {string} - Route that answered.
+ * @param method {string} - HTTP method.
+ * @param durationMs {number} - Response time in milliseconds.
+ * @returns {void} Nothing.
+ */
+export declare function recordResponseTime(endpoint: string, method: string, durationMs: number): void;
+/**
+ * @description Adds to a counter named `custom_<name>`, created on first use.
+ * @param name {string} - Metric name without the `custom_` prefix.
+ * @param value {number} - Amount to add.
+ * @param labels {Record<string, string> | undefined} - Series labels.
+ * @returns {void} Nothing.
+ */
+export declare function recordCustomMetric(name: string, value: number, labels?: Record<string, string>): void;
+/**
+ * @description Records into a histogram named `custom_<name>_histogram`, created on first use.
+ * @param name {string} - Metric name without the `custom_` prefix and `_histogram` suffix.
+ * @param value {number} - Value to record.
+ * @param labels {Record<string, string> | undefined} - Series labels.
+ * @returns {void} Nothing.
+ */
+export declare function recordCustomHistogram(name: string, value: number, labels?: Record<string, string>): void;

package/dist/telemetry/aiMetrics.js

@@ -0,0 +1,229 @@
+import { createNoopMeter, metrics, } from "@opentelemetry/api";
+import { logger } from "../utils/logger.js";
+import { startTelemetry } from "./telemetryStarter.js";
+const METER_NAME = "neurolink-ai";
+let boundProvider;
+let instruments;
+// The API hands out its shared no-op meter until some MeterProvider, the
+// host's or NeuroLink's own, is registered.
+function isMetricsEnabled(meter) {
+    return (process.env.NEUROLINK_TELEMETRY_ENABLED === "true" ||
+        Boolean(process.env.OTEL_EXPORTER_OTLP_ENDPOINT) ||
+        meter !== createNoopMeter());
+}
+function createInstruments(meter) {
+    return {
+        meter,
+        requests: meter.createCounter("ai_requests_total", {
+            description: "Total number of AI requests",
+        }),
+        duration: meter.createHistogram("ai_request_duration_ms", {
+            description: "AI request duration in milliseconds",
+        }),
+        tokens: meter.createCounter("ai_tokens_used_total", {
+            description: "Total number of AI tokens used",
+        }),
+        cost: meter.createCounter("ai_cost_usd_total", {
+            description: "Total accumulated AI cost in USD",
+        }),
+        providerErrors: meter.createCounter("ai_provider_errors_total", {
+            description: "Total number of AI provider errors",
+        }),
+        mcpToolCalls: meter.createCounter("mcp_tool_calls_total", {
+            description: "Total number of MCP tool calls",
+        }),
+        connections: meter.createCounter("connections_total", {
+            description: "Total number of connections",
+        }),
+        responseTime: meter.createHistogram("response_time_ms", {
+            description: "Response time in milliseconds",
+        }),
+        custom: new Map(),
+    };
+}
+/**
+ * The API hands out a no-op meter until a MeterProvider is registered and
+ * never upgrades it, so instruments are bound to the provider that was
+ * registered when they were created and rebuilt when it changes.
+ */
+function currentInstruments() {
+    const provider = metrics.getMeterProvider();
+    if (!instruments || provider !== boundProvider) {
+        boundProvider = provider;
+        instruments = createInstruments(provider.getMeter(METER_NAME));
+    }
+    return instruments;
+}
+/**
+ * Metrics must never break the call they describe, and are recorded only when
+ * a collector, a registered MeterProvider or `NEUROLINK_TELEMETRY_ENABLED=true`
+ * asks for them.
+ */
+function record(write) {
+    try {
+        startTelemetry();
+        const current = currentInstruments();
+        if (isMetricsEnabled(current.meter)) {
+            write(current);
+        }
+    }
+    catch (error) {
+        logger.debug("[Telemetry] Recording a metric failed", {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+function durationBucket(durationMs) {
+    if (durationMs < 100) {
+        return "fast";
+    }
+    if (durationMs < 500) {
+        return "medium";
+    }
+    if (durationMs < 1000) {
+        return "slow";
+    }
+    return "very_slow";
+}
+function statusBucket(durationMs) {
+    if (durationMs < 200) {
+        return "excellent";
+    }
+    if (durationMs < 500) {
+        return "good";
+    }
+    if (durationMs < 1000) {
+        return "acceptable";
+    }
+    return "poor";
+}
+/**
+ * @description Counts one AI request with its duration, tokens and, when known, cost, labelled by provider and model.
+ * @param provider {string} - Provider that served the request.
+ * @param model {string} - Model that served the request.
+ * @param tokens {number} - Total tokens used.
+ * @param durationMs {number} - Request duration in milliseconds.
+ * @param cost {number | undefined} - Cost in USD; omitted or non-positive values add nothing to the cost counter.
+ * @returns {void} Nothing.
+ */
+export function recordAIRequest(provider, model, tokens, durationMs, cost) {
+    record((current) => {
+        const labels = { provider, model };
+        current.requests.add(1, labels);
+        current.duration.record(durationMs, labels);
+        current.tokens.add(tokens, labels);
+        if (cost !== undefined && Number.isFinite(cost) && cost > 0) {
+            current.cost.add(cost, labels);
+        }
+    });
+}
+/**
+ * The `message` label from a bounded set: the HTTP status the error carries,
+ * never its text, which is unbounded cardinality and can carry a credential.
+ */
+function errorMessageLabel(error) {
+    const status = Reflect.get(error, "status") ?? Reflect.get(error, "statusCode");
+    return typeof status === "number" &&
+        Number.isInteger(status) &&
+        status >= 100 &&
+        status <= 599
+        ? `HTTP ${status}`
+        : "unspecified";
+}
+/**
+ * @description Counts one AI provider error, labelled by provider, error name and a bounded `message`: the HTTP status the error carries (`HTTP 429`), or `unspecified`, never the message text.
+ * @param provider {string} - Provider that failed.
+ * @param error {Error} - The failure.
+ * @returns {void} Nothing.
+ */
+export function recordAIError(provider, error) {
+    record((current) => {
+        current.providerErrors.add(1, {
+            provider,
+            error: error.name,
+            message: errorMessageLabel(error),
+        });
+    });
+}
+/**
+ * @description Counts one MCP tool call, labelled by tool, outcome and a duration bucket (`fast`, `medium`, `slow`, `very_slow`).
+ * @param toolName {string} - Name of the tool.
+ * @param durationMs {number} - Call duration in milliseconds.
+ * @param success {boolean} - `false` for a thrown error and for a resolved MCP error result.
+ * @returns {void} Nothing.
+ */
+export function recordMCPToolCall(toolName, durationMs, success) {
+    record((current) => {
+        current.mcpToolCalls.add(1, {
+            tool: toolName,
+            success: success.toString(),
+            duration_bucket: durationBucket(durationMs),
+        });
+    });
+}
+/**
+ * @description Counts one opened connection, labelled by its type.
+ * @param type {MetricConnectionType} - `websocket`, `sse` or `http`.
+ * @returns {void} Nothing.
+ */
+export function recordConnection(type) {
+    record((current) => {
+        current.connections.add(1, { connection_type: type });
+    });
+}
+/**
+ * @description Records one server response time, labelled by endpoint, method and a status bucket (`excellent`, `good`, `acceptable`, `poor`).
+ * @param endpoint {string} - Route that answered.
+ * @param method {string} - HTTP method.
+ * @param durationMs {number} - Response time in milliseconds.
+ * @returns {void} Nothing.
+ */
+export function recordResponseTime(endpoint, method, durationMs) {
+    record((current) => {
+        current.responseTime.record(durationMs, {
+            endpoint,
+            method,
+            status_bucket: statusBucket(durationMs),
+        });
+    });
+}
+/**
+ * @description Adds to a counter named `custom_<name>`, created on first use.
+ * @param name {string} - Metric name without the `custom_` prefix.
+ * @param value {number} - Amount to add.
+ * @param labels {Record<string, string> | undefined} - Series labels.
+ * @returns {void} Nothing.
+ */
+export function recordCustomMetric(name, value, labels) {
+    record((current) => {
+        const key = `custom_${name}`;
+        const existing = current.custom.get(key);
+        const counter = existing && "add" in existing
+            ? existing
+            : current.meter.createCounter(key, {
+                description: `Custom metric: ${name}`,
+            });
+        current.custom.set(key, counter);
+        counter.add(value, labels ?? {});
+    });
+}
+/**
+ * @description Records into a histogram named `custom_<name>_histogram`, created on first use.
+ * @param name {string} - Metric name without the `custom_` prefix and `_histogram` suffix.
+ * @param value {number} - Value to record.
+ * @param labels {Record<string, string> | undefined} - Series labels.
+ * @returns {void} Nothing.
+ */
+export function recordCustomHistogram(name, value, labels) {
+    record((current) => {
+        const key = `custom_${name}_histogram`;
+        const existing = current.custom.get(key);
+        const histogram = existing && "record" in existing
+            ? existing
+            : current.meter.createHistogram(key, {
+                description: `Custom histogram: ${name}`,
+            });
+        current.custom.set(key, histogram);
+        histogram.record(value, labels ?? {});
+    });
+}

package/dist/telemetry/attributes.d.ts

@@ -25,6 +25,7 @@ export declare const ATTR: {
     readonly NL_COST: "cost";
     readonly NL_STRUCTURED_OUTPUT: "structured_output";
     readonly NL_HAS_FALLBACK: "has_fallback";
+    readonly NL_INTERNAL: "langfuse.internal";
     readonly MCP_SERVER_ID: "mcp.server_id";
     readonly MCP_TOOL_NAME: "mcp.tool_name";
     readonly MCP_TIMEOUT_MS: "mcp.timeout_ms";
@@ -114,7 +115,29 @@ export declare const SPAN_ATTRIBUTE_MAX_CHARS = 40000;
  */
 export declare function spanAttributeMaxChars(): number;
 /**
- * @description Returns a copy of a value with credentials masked: values under keys such as `access_token`, `password`, `authorization` or `set-cookie`, bearer tokens, and `name=value` credentials inside text. Purely numeric values after a credential-looking name (e.g. `max_tokens: 4096`) are left alone.
+ * @description Tells whether span inputs (prompts, messages and tool arguments) are recorded. `NEUROLINK_RECORD_INPUTS=false`, in any casing and with or without surrounding spaces, turns it off; any other value, or none, leaves it on, except inside `withoutSpanContent`. Read on every call, so a change applies to the next span.
+ * @returns {boolean} `false` when the operator opted out of recording inputs.
+ */
+export declare function recordsSpanInputs(): boolean;
+/**
+ * @description Runs `fn` with span content withheld: an observation recorded while it runs, or while anything it starts runs, keeps its model, usage, cost, level and timings but no input or output. The proxy uses it for a model call made on a client's behalf, whose content it records only when bodies are opted in.
+ * @param fn {() => T} - Work whose observations carry no content.
+ * @returns {T} Whatever `fn` returns.
+ */
+export declare function withoutSpanContent<T>(fn: () => T): T;
+/**
+ * @description Tells whether span input and output may be recorded here, i.e. the caller is not inside `withoutSpanContent`.
+ * @returns {boolean} `false` while content is withheld.
+ */
+export declare function recordsSpanContent(): boolean;
+/**
+ * @description Tells whether a string is an attribute that `spanContentAttribute` or `spanModelRequestAttribute` returned recently, so it is already redacted and capped.
+ * @param value {string} - Candidate attribute value.
+ * @returns {boolean} `true` when the string came out of one of those functions.
+ */
+export declare function isFinishedAttribute(value: string): boolean;
+/**
+ * @description Returns a copy of a value with credentials masked: values under keys such as `access_token`, `password`, `authorization` or `set-cookie`, the value of a `{ name, value }` or `{ key, value }` entry whose name is such a key, bearer tokens, and `name=value` credentials inside text and inside object keys. Purely numeric values after a credential-looking name (e.g. `max_tokens: 4096`) are left alone, and so is an entry whose name ends in `tokens`, `policy`, `type`, `algorithm`, `count` or `limit` (a setting, not a credential).
  * @param value {JsonValue | object} - Content to redact; objects and arrays are walked recursively.
  * @returns {JsonValue | object} A redacted copy, serializing exactly as the input when nothing in it is sensitive.
  * @throws {Error} When the value cannot be walked; tracing callers use `spanContentAttribute`, which turns that into an omitted value.

package/dist/telemetry/attributes.js

@@ -1,4 +1,5 @@
-import { MIN_STRING_BUDGET_CHARS, REDACTED_VALUE, TRUNCATION_NOTE_ALLOWANCE_CHARS, } from "../constants/telemetry.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { INTERNAL_SPAN_ATTRIBUTE, MAX_REDACTED_ATTRIBUTES, MIN_STRING_BUDGET_CHARS, REDACTED_VALUE, TRUNCATION_NOTE_ALLOWANCE_CHARS, } from "../constants/telemetry.js";
 import { messageRole } from "./chatMessages.js";
 import { binaryPlaceholder, declaredMimeType, describeDataUrls, isBinaryKey, redactSecretAssignments, redactSensitiveEntry, } from "./spanSanitizer.js";
 import { capStrings, stringify } from "./spanSerialization.js";
@@ -29,6 +30,7 @@ export const ATTR = {
     NL_COST: "cost",
     NL_STRUCTURED_OUTPUT: "structured_output",
     NL_HAS_FALLBACK: "has_fallback",
+    NL_INTERNAL: INTERNAL_SPAN_ATTRIBUTE,
     MCP_SERVER_ID: "mcp.server_id",
     MCP_TOOL_NAME: "mcp.tool_name",
     MCP_TIMEOUT_MS: "mcp.timeout_ms",
@@ -133,6 +135,57 @@ export function spanAttributeMaxChars() {
     }
     return Math.max(SPAN_ATTRIBUTE_MIN_CHARS, configured);
 }
+/**
+ * @description Tells whether span inputs (prompts, messages and tool arguments) are recorded. `NEUROLINK_RECORD_INPUTS=false`, in any casing and with or without surrounding spaces, turns it off; any other value, or none, leaves it on, except inside `withoutSpanContent`. Read on every call, so a change applies to the next span.
+ * @returns {boolean} `false` when the operator opted out of recording inputs.
+ */
+export function recordsSpanInputs() {
+    return (recordsSpanContent() &&
+        process.env.NEUROLINK_RECORD_INPUTS?.trim().toLowerCase() !== "false");
+}
+const contentWithheld = new AsyncLocalStorage();
+/**
+ * @description Runs `fn` with span content withheld: an observation recorded while it runs, or while anything it starts runs, keeps its model, usage, cost, level and timings but no input or output. The proxy uses it for a model call made on a client's behalf, whose content it records only when bodies are opted in.
+ * @param fn {() => T} - Work whose observations carry no content.
+ * @returns {T} Whatever `fn` returns.
+ */
+export function withoutSpanContent(fn) {
+    return contentWithheld.run(true, fn);
+}
+/**
+ * @description Tells whether span input and output may be recorded here, i.e. the caller is not inside `withoutSpanContent`.
+ * @returns {boolean} `false` while content is withheld.
+ */
+export function recordsSpanContent() {
+    return contentWithheld.getStore() !== true;
+}
+// Strings this module returned as finished attributes. A caller that builds an
+// attribute with `spanContentAttribute` or `spanModelRequestAttribute` and
+// hands it to `observe` would otherwise have it redacted again, and a second
+// pass over serialized JSON reads an escaped newline as part of a credential's
+// value. Redacting a string that already came out of redaction cannot reveal
+// anything new, so recognizing it is safe; a string that was evicted is simply
+// redacted again, as before.
+const finishedAttributes = new Set();
+function finished(attribute) {
+    finishedAttributes.delete(attribute);
+    finishedAttributes.add(attribute);
+    if (finishedAttributes.size > MAX_REDACTED_ATTRIBUTES) {
+        const oldest = finishedAttributes.values().next().value;
+        if (oldest !== undefined) {
+            finishedAttributes.delete(oldest);
+        }
+    }
+    return attribute;
+}
+/**
+ * @description Tells whether a string is an attribute that `spanContentAttribute` or `spanModelRequestAttribute` returned recently, so it is already redacted and capped.
+ * @param value {string} - Candidate attribute value.
+ * @returns {boolean} `true` when the string came out of one of those functions.
+ */
+export function isFinishedAttribute(value) {
+    return finishedAttributes.has(value);
+}
 /** Opening of the system prompt a model-request attribute always keeps. */
 const SYSTEM_PROMPT_FLOOR_CHARS = 2_000;
 /** Room the current question always gets in a model-request attribute. */
@@ -174,6 +227,29 @@ function redactText(text) {
     });
     return redacted;
 }
+// A name that says how many, how long or what kind of thing rather than
+// holding the credential (`max_tokens`, `password_policy`, `credential_type`).
+const MEASUREMENT_ENTRY_NAME = /(?:^|_)tokens$|_(?:policy|type|algorithm|count|limit)$/;
+const NUMERIC_TEXT = /^\s*\d+(?:\.\d+)?\s*$/;
+function snakeCased(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/[\s.-]+/g, "_")
+        .toLowerCase();
+}
+// Headers, environment variables and form fields are often lists of
+// `{ name, value }` or `{ key, value }` entries; when the name is a credential
+// the value is one, exactly as if it were stored under that key. A setting
+// that merely mentions a credential, or a purely numeric value, is not one.
+function credentialEntryName(node) {
+    const name = "name" in node ? node.name : "key" in node ? node.key : undefined;
+    if (typeof name !== "string" || !("value" in node) || !isSensitiveKey(name)) {
+        return undefined;
+    }
+    const isSetting = MEASUREMENT_ENTRY_NAME.test(snakeCased(name)) ||
+        (typeof node.value === "string" && NUMERIC_TEXT.test(node.value));
+    return isSetting ? undefined : name;
+}
 function redactNode(value, ancestors) {
     if (typeof value === "string") {
         return redactText(describeDataUrls(value));
@@ -198,17 +274,26 @@ function redactNode(value, ancestors) {
         // No prototype, so a key named __proto__ is data rather than an assignment.
         const redacted = Object.create(null);
         const mimeType = declaredMimeType(value);
+        const entryName = credentialEntryName(value);
         for (const [key, entry] of Object.entries(value)) {
-            if (isSensitiveKey(key) &&
+            // A key can carry a credential too, such as a URL with an api_key
+            // parameter used as a map key.
+            const safeKey = redactText(key);
+            const sensitiveName = key === "value" && entryName !== undefined
+                ? entryName
+                : isSensitiveKey(key)
+                    ? key
+                    : undefined;
+            if (sensitiveName !== undefined &&
                 (typeof entry === "string" ||
                     (typeof entry === "object" && entry !== null))) {
-                redacted[key] = redactSensitiveEntry(key, entry);
+                redacted[safeKey] = redactSensitiveEntry(sensitiveName, entry);
                 continue;
             }
             const placeholder = isBinaryKey(key)
                 ? binaryPlaceholder(entry, mimeType)
                 : undefined;
-            redacted[key] = placeholder ?? redactNode(entry, ancestors);
+            redacted[safeKey] = placeholder ?? redactNode(entry, ancestors);
         }
         return redacted;
     }
@@ -217,7 +302,7 @@ function redactNode(value, ancestors) {
     }
 }
 /**
- * @description Returns a copy of a value with credentials masked: values under keys such as `access_token`, `password`, `authorization` or `set-cookie`, bearer tokens, and `name=value` credentials inside text. Purely numeric values after a credential-looking name (e.g. `max_tokens: 4096`) are left alone.
+ * @description Returns a copy of a value with credentials masked: values under keys such as `access_token`, `password`, `authorization` or `set-cookie`, the value of a `{ name, value }` or `{ key, value }` entry whose name is such a key, bearer tokens, and `name=value` credentials inside text and inside object keys. Purely numeric values after a credential-looking name (e.g. `max_tokens: 4096`) are left alone, and so is an entry whose name ends in `tokens`, `policy`, `type`, `algorithm`, `count` or `limit` (a setting, not a credential).
  * @param value {JsonValue | object} - Content to redact; objects and arrays are walked recursively.
  * @returns {JsonValue | object} A redacted copy, serializing exactly as the input when nothing in it is sensitive.
  * @throws {Error} When the value cannot be walked; tracing callers use `spanContentAttribute`, which turns that into an omitted value.
@@ -246,7 +331,7 @@ function redactSafely(value) {
 export function spanContentAttribute(value, maxChars = spanAttributeMaxChars()) {
     const redacted = redactSafely(value);
     if (redacted === null || typeof redacted !== "object") {
-        return spanJsonAttribute(redacted, maxChars);
+        return finished(spanJsonAttribute(redacted, maxChars));
     }
     let serialized = stringify(redacted);
     let budget = Math.floor(maxChars / 4);
@@ -254,7 +339,7 @@ export function spanContentAttribute(value, maxChars = spanAttributeMaxChars())
         serialized = stringify(capStrings(redacted, budget));
         budget = Math.floor(budget / 4);
     }
-    return spanJsonAttribute(serialized, maxChars);
+    return finished(spanJsonAttribute(serialized, maxChars));
 }
 /**
  * Serialize an arbitrary value for a span attribute, hard-capped at
@@ -491,9 +576,9 @@ export function spanModelRequestAttribute(rawRequest, maxChars = spanAttributeMa
         ...(prompt !== undefined ? [{ role: "user", content: prompt }] : []),
     ];
     try {
-        return JSON.stringify(conversation);
+        return finished(JSON.stringify(conversation));
     }
     catch {
-        return spanJsonAttribute(conversation, maxChars);
+        return finished(spanJsonAttribute(conversation, maxChars));
     }
 }

package/dist/telemetry/chatMessages.d.ts

@@ -5,6 +5,12 @@ import type { AssistantOutput } from "../types/index.js";
  * @returns {string} The message role, or `user` when it declares none.
  */
 export declare function messageRole<T>(message: T): string;
+/**
+ * @description Removes the arguments of every tool call in assistant messages and keeps each call's name and id: OpenAI `tool_calls` and `function_call` items, Anthropic `tool_use` blocks, AI SDK `tool-call` parts and Gemini `functionCall` parts.
+ * @param messages {object[]} - Messages from `assistantMessages`.
+ * @returns {object[]} Copies of the messages without tool-call arguments.
+ */
+export declare function withoutToolArguments(messages: object[]): object[];
 /**
  * @description Shapes a model response as an assistant message array that Langfuse renders as a conversation.
  * @param output {AssistantOutput | undefined} - A text string, a reply with `text`, `reasoning` and `toolCalls`, a message array, or provider content parts.

package/dist/telemetry/chatMessages.js

@@ -32,6 +32,43 @@ export function messageRole(message) {
         ? message.role
         : "user";
 }
+const TOOL_CALL_TYPES = new Set([
+    "function",
+    "function_call",
+    "tool_use",
+    "server_tool_use",
+    "tool-call",
+]);
+const TOOL_ARGUMENT_KEYS = new Set(["arguments", "args", "input"]);
+function stripToolArguments(value, isCall = false) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => stripToolArguments(entry));
+    }
+    if (typeof value !== "object" || value === null) {
+        return value;
+    }
+    const call = isCall ||
+        ("type" in value &&
+            typeof value.type === "string" &&
+            TOOL_CALL_TYPES.has(value.type));
+    return Object.fromEntries(Object.entries(value)
+        .filter(([key]) => !(call && TOOL_ARGUMENT_KEYS.has(key)))
+        .map(([key, entry]) => [
+        key,
+        stripToolArguments(entry, key === "function" || key === "functionCall"),
+    ]));
+}
+/**
+ * @description Removes the arguments of every tool call in assistant messages and keeps each call's name and id: OpenAI `tool_calls` and `function_call` items, Anthropic `tool_use` blocks, AI SDK `tool-call` parts and Gemini `functionCall` parts.
+ * @param messages {object[]} - Messages from `assistantMessages`.
+ * @returns {object[]} Copies of the messages without tool-call arguments.
+ */
+export function withoutToolArguments(messages) {
+    return messages.map((message) => Object.fromEntries(Object.entries(message).map(([key, value]) => [
+        key,
+        stripToolArguments(value),
+    ])));
+}
 /**
  * @description Shapes a model response as an assistant message array that Langfuse renders as a conversation.
  * @param output {AssistantOutput | undefined} - A text string, a reply with `text`, `reasoning` and `toolCalls`, a message array, or provider content parts.

package/dist/telemetry/index.d.ts

@@ -1,6 +1,6 @@
 export { tracers } from "./tracers.js";
 export { withSpan, withClientSpan, withStreamSpan, withClientStreamSpan, StepSpans, withStepSpan, } from "./withSpan.js";
-export { ATTR, SPAN_ATTRIBUTE_MAX_CHARS, redactSpanContent, spanAttributeMaxChars, spanContentAttribute, spanJsonAttribute, spanModelRequestAttribute, } from "./attributes.js";
+export { ATTR, SPAN_ATTRIBUTE_MAX_CHARS, recordsSpanInputs, redactSpanContent, spanAttributeMaxChars, spanContentAttribute, spanJsonAttribute, spanModelRequestAttribute, } from "./attributes.js";
 export { assistantMessages } from "./chatMessages.js";
 export { observationLevel, observe, observeGeneration, observeTrace, usageDetails, } from "./observation.js";
 export { generationName, stepSpanName, toolSpanName, } from "./observationNames.js";

package/dist/telemetry/index.js

@@ -1,6 +1,6 @@
 export { tracers } from "./tracers.js";
 export { withSpan, withClientSpan, withStreamSpan, withClientStreamSpan, StepSpans, withStepSpan, } from "./withSpan.js";
-export { ATTR, SPAN_ATTRIBUTE_MAX_CHARS, redactSpanContent, spanAttributeMaxChars, spanContentAttribute, spanJsonAttribute, spanModelRequestAttribute, } from "./attributes.js";
+export { ATTR, SPAN_ATTRIBUTE_MAX_CHARS, recordsSpanInputs, redactSpanContent, spanAttributeMaxChars, spanContentAttribute, spanJsonAttribute, spanModelRequestAttribute, } from "./attributes.js";
 export { assistantMessages } from "./chatMessages.js";
 export { observationLevel, observe, observeGeneration, observeTrace, usageDetails, } from "./observation.js";
 export { generationName, stepSpanName, toolSpanName, } from "./observationNames.js";