SDK Diagnostics

The Python, JavaScript, Java, Rust, C++ and Dart SDKs report their own failures back to KugelAudio so we can see problems that never reach our servers: a connection that could not be established, a stream that stopped halfway through, a retry that ran out.

This is a small, fixed set of fields about the SDK's own operation. It is not application monitoring, and it never contains your content.

What is collected

A failed speech-to-text upload reports the operation transcribe.

Successful calls produce no report of their own; they only increase the success count.

What is never collected

The set of fields above is an allowlist enforced in code: a field that is not on it is dropped before anything is sent, and dropped again when we receive it.

Reports are sent with your API key, so we associate them with the organization that key belongs to. The SDK itself never includes an account identifier.

Cancelling a request (a barge-in in a voice agent, for example) is not a failure. It is counted so we can calculate accurate failure rates, and produces no report of its own.

Defaults

Diagnostics are enabled by default when you use the hosted KugelAudio API, and disabled by default when you point the SDK at your own endpoint, so self-hosted deployments report nothing unless you ask them to.

Reports go to the same KugelAudio API host you already call, authenticated with the same API key. There is no separate endpoint and no third-party collector, so nothing new has to be allowed through a firewall or egress proxy.

Reporting happens in the background on a bounded queue. It never blocks synthesis, closing a client waits at most one second for pending reports, and a failure to deliver a report is silently discarded rather than surfaced to your code. The SDK never writes telemetry messages to your logs or console.

If your process exits without closing the client, pending reports are still sent on the way out, again waiting at most one second and only when something is pending. In Node.js this covers a normal exit but not process.exit() or a crash, so call client.close() first if you exit explicitly. The Rust and Dart SDKs send pending reports only from client.close(), so call it before your program exits.

Turning it off

client = KugelAudio(api_key="...", telemetry=False)

const client = new KugelAudio({ apiKey: '...', telemetry: false });

KugelAudio client = new KugelAudio(
    KugelAudioOptions.builder("...").telemetry(false).build());

let client = KugelAudio::builder("...").telemetry(false).build()?;

kugelaudio::ClientOptions options;
options.api_key = "...";
options.telemetry = false;
kugelaudio::Client client{options};

final client = KugelAudio(apiKey: '...', telemetry: false);

Or set an environment variable, which overrides the code setting in both directions:

export KUGELAUDIO_TELEMETRY=0    # off
export KUGELAUDIO_TELEMETRY=1    # on

Flutter apps and web builds usually have no process environment to set: the Dart SDK also reads the setting at compile time from --dart-define=KUGELAUDIO_TELEMETRY=0.