@juspay/neurolink 12.58.1 → 13.0.0

package/dist/services/server/ai/observability/langfuseSetup.d.ts

@@ -0,0 +1,14 @@
+import { LangfuseExporter } from "../../../../observability/exporters/langfuseExporter.js";
+import type { ObservabilityConfig } from "../../../../types/index.js";
+/**
+ * @description Decides whether Langfuse export is on: off when `config.langfuse` is `false`, on when it is an options object or both Langfuse keys are in the environment.
+ * @param config {ObservabilityConfig | undefined} - Observability options.
+ * @returns {boolean} `true` when a Langfuse exporter should be created.
+ */
+export declare function isLangfuseEnabled(config?: ObservabilityConfig): boolean;
+/**
+ * @description Builds and starts a Langfuse exporter from config, falling back to the `LANGFUSE_*` environment variables.
+ * @param config {ObservabilityConfig | undefined} - Observability options; `langfuse` may carry keys, base URL, environment, release, mask and batching.
+ * @returns {LangfuseExporter | null} The exporter, or `null` (after a warning) when the public or secret key is missing.
+ */
+export declare function createLangfuseExporter(config?: ObservabilityConfig): LangfuseExporter | null;

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

@@ -0,0 +1,55 @@
+import { OTEL_LOG_PREFIX } from "../../../../constants/telemetry.js";
+import { LangfuseExporter } from "../../../../observability/exporters/langfuseExporter.js";
+import { logger } from "../../../../utils/logger.js";
+async function initializeQuietly(exporter) {
+    try {
+        await exporter.initialize();
+    }
+    catch (error) {
+        logger.warn(`${OTEL_LOG_PREFIX} Langfuse exporter failed to initialize`, {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * @description Decides whether Langfuse export is on: off when `config.langfuse` is `false`, on when it is an options object or both Langfuse keys are in the environment.
+ * @param config {ObservabilityConfig | undefined} - Observability options.
+ * @returns {boolean} `true` when a Langfuse exporter should be created.
+ */
+export function isLangfuseEnabled(config) {
+    const langfuse = config?.langfuse;
+    if (langfuse === false) {
+        return false;
+    }
+    return (typeof langfuse === "object" ||
+        Boolean(process.env.LANGFUSE_PUBLIC_KEY && process.env.LANGFUSE_SECRET_KEY));
+}
+/**
+ * @description Builds and starts a Langfuse exporter from config, falling back to the `LANGFUSE_*` environment variables.
+ * @param config {ObservabilityConfig | undefined} - Observability options; `langfuse` may carry keys, base URL, environment, release, mask and batching.
+ * @returns {LangfuseExporter | null} The exporter, or `null` (after a warning) when the public or secret key is missing.
+ */
+export function createLangfuseExporter(config) {
+    const options = typeof config?.langfuse === "object" ? config.langfuse : {};
+    const publicKey = options.publicKey ?? process.env.LANGFUSE_PUBLIC_KEY;
+    const secretKey = options.secretKey ?? process.env.LANGFUSE_SECRET_KEY;
+    if (!publicKey || !secretKey) {
+        logger.warn(`${OTEL_LOG_PREFIX} Langfuse is enabled but publicKey and secretKey are not both set in config or LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY; not exporting to Langfuse`);
+        return null;
+    }
+    const exporter = new LangfuseExporter({
+        enabled: true,
+        publicKey,
+        secretKey,
+        baseUrl: options.baseUrl ?? process.env.LANGFUSE_BASE_URL,
+        environment: options.environment,
+        release: options.release,
+        mask: options.mask,
+        maxBufferSize: options.exportMode === "immediate" ? 1 : options.flushAt,
+        flushIntervalMs: options.flushInterval === undefined
+            ? undefined
+            : options.flushInterval * 1000,
+    });
+    void initializeQuietly(exporter);
+    return exporter;
+}

package/dist/services/server/ai/observability/otlpSetup.d.ts

@@ -0,0 +1,16 @@
+import type { Resource } from "@opentelemetry/resources";
+import { MeterProvider } from "@opentelemetry/sdk-metrics";
+import { type SpanProcessor } from "@opentelemetry/sdk-trace-base";
+/**
+ * @description Builds a batching span processor that ships spans to an OTLP/HTTP endpoint.
+ * @param endpoint {string} - OTLP base URL; `/v1/traces` is appended.
+ * @returns {SpanProcessor | null} The processor, or `null` (after a warning) when the exporter cannot be created.
+ */
+export declare function createOtlpSpanProcessor(endpoint: string): SpanProcessor | null;
+/**
+ * @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.
+ * @returns {MeterProvider | null} The provider, or `null` (after a warning) when it cannot be created.
+ */
+export declare function createOtlpMeterProvider(endpoint: string, resource: Resource): MeterProvider | null;

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

@@ -0,0 +1,58 @@
+import { metrics } from "@opentelemetry/api";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { MeterProvider, PeriodicExportingMetricReader, } from "@opentelemetry/sdk-metrics";
+import { BatchSpanProcessor, } from "@opentelemetry/sdk-trace-base";
+import { OTEL_LOG_PREFIX } from "../../../../constants/telemetry.js";
+import { logger } from "../../../../utils/logger.js";
+/**
+ * @description Builds a batching span processor that ships spans to an OTLP/HTTP endpoint.
+ * @param endpoint {string} - OTLP base URL; `/v1/traces` is appended.
+ * @returns {SpanProcessor | null} The processor, or `null` (after a warning) when the exporter cannot be created.
+ */
+export function createOtlpSpanProcessor(endpoint) {
+    try {
+        return new BatchSpanProcessor(new OTLPTraceExporter({ url: `${endpoint}/v1/traces` }), {
+            maxQueueSize: 2048,
+            maxExportBatchSize: 512,
+            scheduledDelayMillis: 1000,
+            exportTimeoutMillis: 30000,
+        });
+    }
+    catch (error) {
+        logger.warn(`${OTEL_LOG_PREFIX} Failed to create OTLP trace exporter`, {
+            error: error instanceof Error ? error.message : String(error),
+            endpoint,
+        });
+        return null;
+    }
+}
+/**
+ * @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.
+ * @returns {MeterProvider | null} The provider, or `null` (after a warning) when it cannot be created.
+ */
+export function createOtlpMeterProvider(endpoint, resource) {
+    try {
+        const provider = new MeterProvider({
+            resource,
+            readers: [
+                new PeriodicExportingMetricReader({
+                    exporter: new OTLPMetricExporter({ url: `${endpoint}/v1/metrics` }),
+                    exportIntervalMillis: 15000,
+                    exportTimeoutMillis: 10000,
+                }),
+            ],
+        });
+        metrics.setGlobalMeterProvider(provider);
+        return provider;
+    }
+    catch (error) {
+        logger.warn(`${OTEL_LOG_PREFIX} Failed to create OTLP metric exporter`, {
+            error: error instanceof Error ? error.message : String(error),
+            endpoint,
+        });
+        return null;
+    }
+}

package/dist/session/globalSessionState.js

@@ -1,6 +1,5 @@
 import { nanoid } from "nanoid";
 import { NeuroLink } from "../neurolink.js";
-import { buildObservabilityConfigFromEnv } from "../utils/observabilityHelpers.js";
 /**
  * Build mcp.outputLimits config from environment variables.
  * Reads NEUROLINK_MCP_OUTPUT_STRATEGY and NEUROLINK_MCP_MAX_OUTPUT_BYTES.
@@ -54,11 +53,6 @@ export class GlobalSessionManager {
                 maxTurnsPerSession: config.maxTurnsPerSession,
             };
         }
-        // Add observability config from environment variables (CLI usage)
-        const observabilityConfig = buildObservabilityConfigFromEnv();
-        if (observabilityConfig) {
-            neurolinkOptions.observability = observabilityConfig;
-        }
         // Add MCP output limits from environment variables (CLI usage)
         const mcpOutputLimits = buildMcpOutputLimitsFromEnv();
         if (mcpOutputLimits) {
@@ -187,13 +181,8 @@ export class GlobalSessionManager {
         if (session) {
             return session.neurolinkInstance;
         }
-        // Create new NeuroLink with observability config from environment (CLI usage)
-        const observabilityConfig = buildObservabilityConfigFromEnv();
         const mcpOutputLimits = buildMcpOutputLimitsFromEnv();
         const options = {};
-        if (observabilityConfig) {
-            options.observability = observabilityConfig;
-        }
         if (mcpOutputLimits) {
             options.mcp = { outputLimits: mcpOutputLimits };
         }

package/dist/telemetry/attributes.d.ts

@@ -3,6 +3,7 @@ export declare const ATTR: {
     readonly GEN_AI_SYSTEM: "gen_ai.system";
     readonly GEN_AI_MODEL: "gen_ai.request.model";
     readonly GEN_AI_OPERATION: "gen_ai.operation.name";
+    readonly GEN_AI_OBSERVATION: "gen_ai.observation.type";
     readonly GEN_AI_INPUT_TOKENS: "gen_ai.usage.input_tokens";
     readonly GEN_AI_OUTPUT_TOKENS: "gen_ai.usage.output_tokens";
     readonly GEN_AI_FINISH_REASON: "gen_ai.response.finish_reason";
@@ -10,20 +11,20 @@ export declare const ATTR: {
     readonly GEN_AI_TOOL_NAME: "gen_ai.tool.name";
     readonly GEN_AI_TEMPERATURE: "gen_ai.request.temperature";
     readonly GEN_AI_MAX_TOKENS: "gen_ai.request.max_tokens";
-    readonly NL_PROVIDER: "neurolink.provider";
-    readonly NL_MODEL: "neurolink.model";
-    readonly NL_STREAM_MODE: "neurolink.stream_mode";
-    readonly NL_TOOL_COUNT: "neurolink.tool_count";
-    readonly NL_MESSAGE_COUNT: "neurolink.message_count";
-    readonly NL_HAS_TOOLS: "neurolink.has_tools";
-    readonly NL_INPUT_LENGTH: "neurolink.input_length";
-    readonly NL_OUTPUT_LENGTH: "neurolink.output_length";
-    readonly NL_REQUEST_ID: "neurolink.request_id";
-    readonly NL_PATH: "neurolink.path";
-    readonly NL_HAS_MEMORY: "neurolink.has_conversation_memory";
-    readonly NL_COST: "neurolink.cost";
-    readonly NL_STRUCTURED_OUTPUT: "neurolink.structured_output";
-    readonly NL_HAS_FALLBACK: "neurolink.has_fallback";
+    readonly NL_PROVIDER: "sdk.provider";
+    readonly NL_MODEL: "sdk.model";
+    readonly NL_STREAM_MODE: "stream_mode";
+    readonly NL_TOOL_COUNT: "tool_count";
+    readonly NL_MESSAGE_COUNT: "message_count";
+    readonly NL_HAS_TOOLS: "has_tools";
+    readonly NL_INPUT_LENGTH: "input_length";
+    readonly NL_OUTPUT_LENGTH: "output_length";
+    readonly NL_REQUEST_ID: "request_id";
+    readonly NL_PATH: "path";
+    readonly NL_HAS_MEMORY: "has_conversation_memory";
+    readonly NL_COST: "cost";
+    readonly NL_STRUCTURED_OUTPUT: "structured_output";
+    readonly NL_HAS_FALLBACK: "has_fallback";
     readonly MCP_SERVER_ID: "mcp.server_id";
     readonly MCP_TOOL_NAME: "mcp.tool_name";
     readonly MCP_TIMEOUT_MS: "mcp.timeout_ms";
@@ -104,30 +105,6 @@ export declare const ATTR: {
     readonly AR_DESCRIPTION: "autoresearch.description";
     readonly AR_ERROR_CODE: "autoresearch.error_code";
 };
-/**
- * Langfuse observation/trace attribute names recognised by `@langfuse/otel`'s
- * LangfuseSpanProcessor (already registered on the global TracerProvider). They
- * let native (non-AI-SDK) provider paths emit spans that render as proper
- * generation / tool observations — the same data the Vercel AI SDK's
- * `experimental_telemetry` produced before providers moved to native SDKs.
- */
-export declare const LANGFUSE_ATTR: {
-    readonly TRACE_NAME: "langfuse.trace.name";
-    readonly TRACE_INPUT: "langfuse.trace.input";
-    readonly TRACE_OUTPUT: "langfuse.trace.output";
-    readonly TRACE_TAGS: "langfuse.trace.tags";
-    readonly TRACE_METADATA: "langfuse.trace.metadata";
-    readonly OBSERVATION_TYPE: "langfuse.observation.type";
-    readonly OBSERVATION_INPUT: "langfuse.observation.input";
-    readonly OBSERVATION_OUTPUT: "langfuse.observation.output";
-    readonly OBSERVATION_METADATA: "langfuse.observation.metadata";
-    readonly OBSERVATION_MODEL_NAME: "langfuse.observation.model.name";
-    readonly OBSERVATION_MODEL_PARAMETERS: "langfuse.observation.model.parameters";
-    readonly OBSERVATION_USAGE_DETAILS: "langfuse.observation.usage_details";
-    readonly OBSERVATION_LEVEL: "langfuse.observation.level";
-    readonly OBSERVATION_STATUS_MESSAGE: "langfuse.observation.status_message";
-    readonly OBSERVATION_COMPLETION_START_TIME: "langfuse.observation.completion_start_time";
-};
 /** Default ceiling for serialized span attribute values. */
 export declare const SPAN_ATTRIBUTE_MAX_CHARS = 40000;
 /**
@@ -137,12 +114,10 @@ export declare const SPAN_ATTRIBUTE_MAX_CHARS = 40000;
  */
 export declare function spanAttributeMaxChars(): number;
 /**
- * Returns a copy of `value` with credentials masked: values under keys such as
- * `access_token`, `password`, `authorization` or `set-cookie`, bearer tokens
- * and `name=value` credentials inside text. Content with nothing sensitive in
- * it serializes exactly as it did before. Throws only if the value cannot be
- * walked; callers on the tracing path use `spanContentAttribute`, which turns
- * that into an omitted value instead of a leak or a failed turn.
+ * @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.
+ * @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.
  */
 export declare function redactSpanContent(value: unknown): unknown;
 /**
@@ -150,8 +125,10 @@ export declare function redactSpanContent(value: unknown): unknown;
  * (arguments, results, answers), with credentials masked first. Use the plain
  * form for metadata such as usage counts and server ids.
  *
- * A structured value over the cap is shortened by trimming its longest
- * strings, so the attribute stays valid JSON instead of ending mid-token.
+ * A structured value over the cap is shortened by cutting every string to a
+ * per-string budget in one walk, tightening the budget only if the result
+ * still does not fit, so the attribute stays valid JSON instead of ending
+ * mid-token.
  */
 export declare function spanContentAttribute(value: unknown, maxChars?: number): string;
 /**