JavaScript and TypeScript SDK (softprobe-js)
API reference for the @softprobe/* npm packages (version 0.1.18, Node.js 20 or newer).
| Package | Purpose | Source |
|---|---|---|
@softprobe/tracing | Core OpenTelemetry tracer, observations, generations, OpenAI wrapper, and scores | softprobe-js/packages/tracing |
@softprobe/web-record | Browser rrweb DOM recording, same-origin HTTP tracing, and JSON body capture | softprobe-js/packages/web-record |
@softprobe/vercel-ai-sdk | Vercel AI SDK telemetry integration and HTTP context propagation | softprobe-js/packages/vercel-ai-sdk |
@softprobe/langchain | LangChain and LangGraph auto-instrumentation and CallbackHandler | softprobe-js/packages/langchain |
@softprobe/opencode-plugin | OpenCode coding-agent plugin | softprobe-js/packages/opencode-plugin |
@softprobe/tracing
Install the core package:
npm install @softprobe/tracingSoftprobeClient
SoftprobeClient configures an OpenTelemetry NodeTracerProvider, exports OTLP HTTP/protobuf spans with automatic retries, and sends scores to the Softprobe API.
SoftprobeClient.fromEnv(overrides?)
Builds a client from standard OpenTelemetry and Softprobe environment variables, merged with optional overrides (Partial<SoftprobeClientOptions>). Throws MissingSoftprobeCredentialsError if no Ingestion Key is found in overrides.ingestionKey, INGESTION_KEY, OTEL_EXPORTER_OTLP_TRACES_HEADERS, or OTEL_EXPORTER_OTLP_HEADERS.
import { SoftprobeClient } from "@softprobe/tracing";
const client = SoftprobeClient.fromEnv({ serviceName: "my-agent" });new SoftprobeClient(options)
Creates a client from an explicit SoftprobeClientOptions object.
| Option | Type | Default | Description |
|---|---|---|---|
ingestionKey | string | Required | Agent Ingestion Key (spk_...) |
baseUrl | string | https://explorer.softprobe.ai/api/thelake | Score API base URL. Does not change the OTLP trace endpoint. |
otlp | OtlpExportOptions | {} | { endpoint?, tracesEndpoint?, protocol?, headers? } |
otlpEndpoint | string | Production traces URL | Legacy alias for otlp.tracesEndpoint |
resourceAttributes | Record<string, ResourceAttributeValue> | {} | Additional OpenTelemetry resource attributes |
serviceName | string | "softprobe-app" | Sets OpenTelemetry service.name |
serviceVersion | string | undefined | Sets OpenTelemetry service.version |
environment | string | undefined | Sets deployment.environment.name |
release | string | undefined | Default release tag on observations |
sessionId | string | undefined | Default gen_ai.conversation.id and session.id |
userId | string | undefined | Default user.id |
tags | string[] | undefined | Default tags on observations |
redactKeys | string[] | defaultRedactKeys() | Keys replaced with [REDACTED] in captured payloads |
timeoutMs | number | 10000 | HTTP timeout in milliseconds |
headers | Record<string, string> | {} | Additional headers merged into OTLP and score requests |
useSimpleProcessor | boolean | false | Use SimpleSpanProcessor instead of BatchSpanProcessor |
retryExport | boolean | true | Wrap the OTLP exporter in RetryingSpanExporter |
OtlpExportOptions:
| Field | Type | Description |
|---|---|---|
tracesEndpoint | string | Full OTLP HTTP traces URL, used as written |
endpoint | string | Generic OTLP base URL. The SDK appends /v1/traces. |
protocol | "http/protobuf" | Softprobe exporters support http/protobuf |
headers | Record<string, string> | Additional OTLP request headers (not sent to the score API) |
Observation and generation methods
startObservation(options: StartObservationOptions): ObservationstartGeneration(options: StartGenerationOptions): GenerationstartAgent(options)(setsasType: "agent")startTool(options: StartToolOptions)(setsasType: "tool"and tool attributes such astoolName,toolCallId,kind,status,index,mcpServer,mcpTool)startChain(options),startRetriever(options),startEvaluator(options),startEmbedding(options),startGuardrail(options),startEvent(options)withObservation(options, fn)andwithGeneration(options, fn)runfninside the active span context, record any thrown error, and end the span automatically.
StartObservationOptions supports name, asType ("span" | "event" | "generation" | "agent" | "tool" | "chain" | "retriever" | "evaluator" | "embedding" | "guardrail"), attributes, input, output, sessionId, userId, release, tags, metadata, version, traceName, parent, parentSpanContext ({ traceId, spanId }), root (detach from ambient OpenTelemetry context), and startTime.
StartGenerationOptions adds model, modelParameters ({ temperature?, maxTokens? }), provider, operationName, usage ({ inputTokens?, outputTokens?, totalTokens? }), cost ({ input?, output?, total? }), completionStartTime, prompt, promptEvent, completionEvent, and inferenceDetails.
Context, scores, and lifecycle
withAttributes(attributes, fn)propagatessessionId,userId,tags,metadata,version,release, andtraceNameacross async calls viaAsyncLocalStorage.createScore(options: CreateScoreOptions): Promise<void>sends a score (scoreId,name,dataType,source,traceId?,spanId?,sessionId?,numericValue?,stringValue?,booleanValue?,comment?,configId?,authorId?,metadata?) tobaseUrl.forceFlush(): Promise<void>(aliasflush()) flushes pending spans.shutdown(): Promise<void>flushes and closes theNodeTracerProvider.
Observation and Generation
- Properties:
spanId,traceId,otelSpan. update(options)updatesattributes,input,output,statusMessage, orendTime.Generation.updatealso acceptsmodel,responseModel,modelParameters,provider,usage,cost,completionStartTime,responseId,finishReasons,prompt,promptEvent,completionEvent, andinferenceDetails.setAttributes(attributes),addEvent(name, attributes?),addContentEvent(name, content),recordException(error), andend(options?).
observeOpenAI(client, config)
Wraps an OpenAI JS client instance (client.chat.completions.create) to emit generation spans automatically.
import OpenAI from "openai";
import { SoftprobeClient, observeOpenAI } from "@softprobe/tracing";
const sp = SoftprobeClient.fromEnv({ serviceName: "openai-app" });
const openai = observeOpenAI(new OpenAI(), {
softprobeClient: sp,
sessionId: "sess-1",
});ObserveOpenAIConfig: softprobeClient (required), generationName, sessionId, userId, tags, release. Individual create() calls can also pass name, sessionId, userId, metadata, tags, and release.
Utility exports
withAttributes(attributes, fn)andgetPropagatedAttributes()defaultRedactKeys()andredactValue(value, redactKeys, placeholder?)normalizeToolDefinitions(tools),normalizeToolCalls(toolCalls),recordToolDefinitions(obs, tools),recordToolCalls(obs, toolCalls),toolResultEventPayload(...),accumulateToolCallDeltas(...),finalizeToolCallDeltas(...)resolveSoftprobeConfigFromEnv(env?),resolveSoftprobeConfigFromObject(obj),deriveOtlpEndpoint(base)
@softprobe/web-record
Browser SDK that records rrweb DOM events, traces fetch and XMLHttpRequest calls with W3C traceparent propagation, and captures redacted JSON bodies.
npm install @softprobe/web-recordRecordSdk.init(options)
Initializes browser capture once and returns a WebRecordController.
import { RecordSdk } from "@softprobe/web-record";
const recorder = RecordSdk.init({
ingestionKey: "spk_REPLACE_WITH_INGESTION_KEY",
serviceName: "my-web",
otlp: {
tracesEndpoint: "https://explorer.softprobe.ai/api/thelake/v1/traces",
protocol: "http/protobuf",
},
resourceAttributes: {
"deployment.environment.name": "production",
},
});You can also load the UMD bundle in HTML <head> with either data-softprobe-options (full JSON options) or data-ingestion-key:
<script
src="https://unpkg.com/@softprobe/web-record/dist/browser.js"
data-softprobe-options='{"ingestionKey":"spk_REPLACE_WITH_INGESTION_KEY","serviceName":"my-web"}'
defer
></script>WebRecordInitOptions
| Option | Type | Default | Description |
|---|---|---|---|
ingestionKey | string | Required | Ingest-only key (spk_...). Never place user passwords, cookies, or account tokens in browser code. |
serviceName | string | "softprobe-web" | OpenTelemetry service.name for browser spans |
otlp | OtlpExportOptions | Production traces URL | Set otlp.tracesEndpoint (full URL) or otlp.endpoint (base URL) and protocol: "http/protobuf" |
resourceAttributes | ResourceAttributes | {} | Extra resource attributes such as deployment.environment.name |
environment | string | undefined | Shorthand for deployment.environment.name |
sessionId | string | Auto-detected | Explicit session ID. When omitted, adopts IDs from sessionStorage, /sessions/:id URLs, or /sessions JSON responses. |
userId | string | undefined | End-user identifier on spans |
apiOrigins | string[] | window.location.origin | Exact HTTP(S) origins to trace and inject traceparent headers into |
httpBodyCapture | boolean | HttpBodyCaptureOptions | true | Captures same-origin JSON request and response bodies on a softprobe.http.body.capture child span. Pass false to disable. |
interval | number | 5000 | rrweb flush interval in milliseconds (minimum 5000) |
manual | boolean | false | When true, do not start rrweb until recorder.record() is called |
maskAllInputs | boolean | true | Mask all HTML <input> values in DOM recordings |
maskTextSelector | string | undefined | CSS selector for visible text masked by rrweb |
blockSelector | string | undefined | CSS selector for DOM regions excluded from rrweb |
tags | Tags | {} | Browser metadata tags (userId, clientId, email, phoneNo, or custom string keys) |
softDisable | boolean | true | Disable quietly when credentials are incomplete instead of throwing |
onUploadStatus | (status) => void | undefined | Callback receiving `"idle" |
HttpBodyCaptureOptions and HttpBodyCaptureRoute
| Field | Type | Default | Description |
|---|---|---|---|
maxBodyBytes | number | 65536 | Bodies larger than this byte limit are omitted |
routes | HttpBodyCaptureRoute[] | undefined | Optional route allowlist. Omit to capture JSON bodies on all traced apiOrigins. |
Each HttpBodyCaptureRoute accepts:
method(string): HTTP method such as"POST".path(string): Relative path ("/agent/api/sessions/*/messages", wildcard*segments supported) or full HTTP(S) URL without query string or fragment.origin(string, optional): Exact origin for cross-origin relative paths.redactJsonPaths(string[], optional): JSONPath expressions such as["$.paymentDetails.cardNumber"]. Built-in redaction already replacescardNumber,cvv,cvc,password, andsecretanywhere in JSON with[REDACTED].
WebRecordController
RecordSdk.init() returns a WebRecordController with:
enabled(boolean) andsessionId(string) anduploadStatus(RecordingUploadStatus)record(opts?: { tags?: Tags }): RecordingHandle | nullstop(): voidsetTags(tags: Tags, override?: boolean): voidsetSessionId(sessionId: string): void | Promise<void>flush(): Promise<boolean>
@softprobe/vercel-ai-sdk
Integrates Vercel AI SDK generateText, streamText, and tool calls with Softprobe and propagates W3C traceparent and session IDs across Node.js HTTP requests.
npm install @softprobe/vercel-ai-sdk @softprobe/tracinginitVercelAiTelemetry(options?)
Creates a SoftprobeVercelAiSdkIntegration, installs incoming/outgoing HTTP context propagation, and registers the integration with the ai package (registerTelemetry).
import { initVercelAiTelemetry } from "@softprobe/vercel-ai-sdk";
const telemetry = initVercelAiTelemetry({
ingestionKey: "spk_REPLACE_WITH_INGESTION_KEY",
serviceName: "travel-agent",
});SoftprobeVercelAiSdkIntegrationOptions
| Option | Type | Default | Description |
|---|---|---|---|
ingestionKey | string | INGESTION_KEY or OTLP header | Agent Ingestion Key (spk_...) |
serviceName | string | OTEL_SERVICE_NAME or "softprobe-app" | OpenTelemetry service.name for the AI server |
otlp | OtlpExportOptions | Env OTLP vars or production URL | Trace exporter endpoint, protocol, and headers |
resourceAttributes | ResourceAttributes | Env OTEL_RESOURCE_ATTRIBUTES | Additional OpenTelemetry resource attributes |
environment | string | SOFTPROBE_ENVIRONMENT | Sets deployment.environment.name |
baseUrl | string | SOFTPROBE_BASE_URL | Optional score API base URL |
tracer | Tracer | Created from SoftprobeClient | Bring-your-own OpenTelemetry Tracer |
useSimpleProcessor | boolean | false | Flush spans synchronously when each span ends |
Other exports
SoftprobeVercelAiSdkIntegration: Class withforceFlush(),shutdown(),executeTool(),executeLanguageModelCall(), and AI SDK lifecycle hooks (onStart,onStepStart,onLanguageModelCallStart,onLanguageModelCallEnd,onToolExecutionStart,onToolExecutionEnd,onEnd,onAbort,onError).SoftprobeVercelAiSpanProcessor: OpenTelemetrySpanProcessorthat normalizes Vercel AI spans (ai.*) into Softprobeagent,generation,tool,embedding, andretrieverobservations.installIncomingHttpContextPropagation(options?): Patches Nodehttp,https, andfetchto extract incomingtraceparent,baggage, and session headers (x-softprobe-session-id,x-session-id,x-conversation-id,x-thread-id,x-chat-id) and forwardtraceparenton outgoing downstream calls (skipping OTLP collector URLs).createSoftprobeObservationAttributes(params): Builds Softprobe observation attributes for custom AI SDK telemetry delegates.
@softprobe/langchain
LangChain and LangGraph tracing for TypeScript and Node.js. See the LangChain install guide for setup steps.
npm install @softprobe/langchain @softprobe/tracing @langchain/coreImporting @softprobe/langchain calls autoInstrumentFromEnv() automatically when OTLP credentials are present, unless SOFTPROBE_LANGCHAIN is 0, false, off, or no.
Exports
instrument(params?: CallbackHandlerParams): CallbackHandler: Registers a LangChain configure hook so all runs in the async context are traced.uninstrument(): void: Clears the active LangChain hook handler.isInstrumented(): booleanandgetHandler(): CallbackHandler | null.autoInstrumentFromEnv(params?, env?): CallbackHandler | null.CallbackHandler: Extends@langchain/core/callbacks/baseBaseCallbackHandler.- Constructor
CallbackHandlerParams:softprobeClient?,sessionId?,userId?,tags?,metadata?,version?,parentSpanContext?. handler.flush(): Promise<void>flushes pending spans.handler.lastTraceIdexposes the most recent trace ID.
- Constructor
@softprobe/opencode-plugin
OpenCode plugin that sends coding-agent turns, model generations, tool calls, and sub-agent tasks to Softprobe. See the OpenCode install guide for opencode.json and opencode-softprobe.json configuration.
Environment variables
All Node.js packages (@softprobe/tracing, @softprobe/vercel-ai-sdk, @softprobe/langchain, @softprobe/opencode-plugin) share these environment variables:
| Variable | Description | Default |
|---|---|---|
INGESTION_KEY | Bearer token for OTLP trace export and score API | Parsed from Authorization header if omitted |
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | Full OTLP HTTP traces URL, used as written | https://explorer.softprobe.ai/api/thelake/v1/traces |
OTEL_EXPORTER_OTLP_ENDPOINT | Base OTLP URL; /v1/traces is appended | None |
OTEL_EXPORTER_OTLP_TRACES_HEADERS | Comma-separated key=value headers (for example Authorization=Bearer spk_...) | Overrides OTEL_EXPORTER_OTLP_HEADERS |
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL | OTLP protocol (http/protobuf) | http/protobuf |
OTEL_SERVICE_NAME | OpenTelemetry service.name (SOFTPROBE_SERVICE_NAME also accepted) | "softprobe-app" |
OTEL_RESOURCE_ATTRIBUTES | Comma-separated resource attributes (for example deployment.environment.name=staging) | None |
SOFTPROBE_BASE_URL | REST API base for createScore only. Does not change trace routing. | https://explorer.softprobe.ai/api/thelake |
SOFTPROBE_ENVIRONMENT | Sets deployment.environment.name | None |
SOFTPROBE_SESSION_ID | Fallback session ID when no run or request session ID is present | None |
SOFTPROBE_USER_ID | Fallback user ID | None |
SOFTPROBE_LANGCHAIN | Set to 0, false, off, or no to disable @softprobe/langchain auto-instrumentation | Enabled when credentials exist |