Configuration and environment variables

These configuration options apply to both the TypeScript and Python SDKs. Variable names and programmatic keys are consistent across both.

Pass configuration in code, through environment variables, or as a combination of both. Programmatic values take precedence over environment variables. This pattern lets local development and production deployments share the same initialisation path with minimal branching.

Authentication and identity

Set PREFACTOR_API_URL and PREFACTOR_API_TOKEN to configure the HTTP transport. To identify the agent sending data, use these optional variables:

• PREFACTOR_AGENT_ID — the registered agent’s name or ID (maps to agentId in the SDK config)
• PREFACTOR_AGENT_NAME — an optional display name for the agent
• PREFACTOR_AGENT_IDENTIFIER — the version string for this deployment (maps to agentIdentifier in the SDK config; accepts a semver tag, commit SHA, or any identifier you want to track)

Capture and sampling

• PREFACTOR_SAMPLE_RATE — trace sampling from 0 to 1. Default: 1.0 (all spans recorded).
• PREFACTOR_CAPTURE_INPUTS and PREFACTOR_CAPTURE_OUTPUTS — whether input and output payloads are recorded. Both default to true.
• PREFACTOR_MAX_INPUT_LENGTH and PREFACTOR_MAX_OUTPUT_LENGTH — maximum serialised payload sizes. Default: 10,000 characters.

Logging

PREFACTOR_LOG_LEVEL controls SDK log verbosity: debug, info, warn, or error. Default is info. Unlike other config fields, log level is not part of the main Config object — it is read from the environment directly by the logger.

Retry behaviour

Retry behaviour can be tuned for network conditions through HTTP config fields: maxRetries, initialRetryDelay, maxRetryDelay, and retryMultiplier. You can also set PREFACTOR_RETRY_ON_STATUS_CODES to match specific HTTP status codes. In most applications the default retry profile is sufficient; adjust only when operational data shows a clear need.

Defaults and impact on evidence

By default, PREFACTOR_SAMPLE_RATE is 1.0, both capture flags are true, and payload truncation limits are 10,000 characters. Lowering the sample rate or disabling capture reduces evidence completeness in the web app — useful for high-throughput production workloads, but worth reviewing before a compliance review.

When things go wrong

Symptom	Likely cause	First step
SDK initialises but no spans appear	Missing or invalid PREFACTOR_API_TOKEN	Set PREFACTOR_LOG_LEVEL=debug and check for auth errors in the log output
Unexpected sparse data in the web app	PREFACTOR_SAMPLE_RATE is set below 1.0	Confirm the sample rate in your environment and check Defaults and impact on evidence
SDK silently stops sending	Token suspended or revoked	Check token status in Account › API tokens tab

Set PREFACTOR_LOG_LEVEL=debug as your first debugging step — it surfaces transport errors, auth failures, and dropped spans.