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 agent’s Prefactor ID (a ULID). 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)

Token scope and identity

Which identity fields you need depends on the token:

• Account-scoped token — requires the agent ID (PREFACTOR_AGENT_ID / agentId). Environment identity usually comes from the deployment or token path you use at runtime; the SDKs do not document a separate environment env var here.
• Deployment-scoped token — may omit the agent ID; agent and environment identity are carried by the token.
• If you set PREFACTOR_AGENT_ID, it must be the platform agent ID (ULID), not a display name. Use PREFACTOR_AGENT_NAME for a human-readable label.

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 Agent › Deployments tab for deployment tokens, or Account › API tokens tab for account tokens

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