@kortyx/telemetry
v0.17.9
Published
Kortyx Studio telemetry HTTP adapter.
Readme
@kortyx/telemetry
@kortyx/telemetry is the optional HTTP telemetry adapter for Kortyx Studio.
It is separate from the framework entry package, so applications that do not
send Studio telemetry do not include its HTTP transport.
import { createAgent } from "kortyx";
import { createKortyxTelemetryAdapter } from "@kortyx/telemetry";
const telemetry = createKortyxTelemetryAdapter({
apiKey: process.env.KORTYX_TELEMETRY_API_KEY!,
environment:
process.env.KORTYX_TELEMETRY_ENVIRONMENT ?? "development",
service: {
name: process.env.KORTYX_TELEMETRY_SERVICE_NAME ?? "support-agent",
},
});
const agent = createAgent({
// ...workflow configuration
telemetry,
});The endpoint defaults to https://api.kortyx.io for Kortyx Cloud. Cloud users
only need their project write key, environment, and service configuration.
For local or self-hosted Studio, pass its telemetry API base URL explicitly:
const telemetry = createKortyxTelemetryAdapter({
endpoint: process.env.KORTYX_TELEMETRY_API_URL!,
apiKey: process.env.KORTYX_TELEMETRY_API_KEY!,
environment: "development",
service: { name: "support-agent" },
});Environment variables are read by your application; the adapter uses the options
you pass. An omitted or undefined endpoint selects Cloud. Keep all connection
configuration server-side. Upgrade @kortyx/telemetry before removing an endpoint
from an existing configuration that used a version requiring it.
@kortyx/otel is a separate optional adapter for OpenTelemetry. Applications
choose the adapter appropriate to their telemetry destination; kortyx itself
does not provide an HTTP telemetry transport.
Privacy
Prompt, input, and output content is excluded by default. Enable only the content sides your application is allowed to export:
createKortyxTelemetryAdapter({
// ...connection and service options
captureContent: { input: true, output: false },
});Telemetry metadata, tags, operation names, prompt identity (name, version,
type, source), and trusted userId/tenantId trace attributes remain
available without enabling content capture.
Delivery and lifecycle signals
Delivery is best-effort and at-least-once while the process remains alive. The
adapter batches events, retries transient failures, and exposes flush() for
controlled shutdown. Ordinary events have no durable outbox; applications that
need durable event delivery must own that outbox themselves. Complete diagnostics
have a separate opt-in upload queue and optional Node spool. Telemetry failures never fail a
workflow execution.
interrupt.expired is intentionally API-derived from the durable expiresAt
included with interrupt.created. The SDK does not use an unreliable local TTL
timer.
Interrupt events always retain non-sensitive structure: kind,
interactionMode, optionCount, schemaId, and schemaVersion.
interactionMode distinguishes static-options, dynamic-picker, and
freeform requests, so a client-resolved picker is not mistaken for a choice
with zero options. Questions and static option labels follow output-content
capture; a submitted human response follows input-content capture. Option
values and resume capability tokens are never included in interrupt telemetry.
run.cancelled records aborted active executions. Custom HTTP routes must forward
request.signal; createChatRouteHandler forwards it automatically. Cancelling a
toSSE response body also cancels its active execution source.
Complete error diagnostics
createKortyxTelemetryAdapter captures complete diagnostics by default. Upgrade
the API/Studio and run migrations before upgrading the SDK; rerun OSS bootstrap
with the stored keys to grant diagnostic access to the Studio reader.
Set diagnostics: { enabled: false } to retain bounded error events without
capturing or uploading complete diagnostic artifacts.
Native capture retains large messages/stacks, causes, aggregate members, custom
fields, and private provider response evidence with credential redaction. Run
errors link to one diagnostic; native upload parts do not become timeline events.
Studio and kortyx studio diagnostics get|download retrieve complete content
without application chunk reconstruction. Capture and delivery limits are explicit,
and flushDiagnostics(timeoutMs) reports pending and dropped delivery. See the
deployment and usage guide for limits,
permissions, spool/retention operations, privacy policy, and rollout instructions.
