---
title: Configuration and environment variables
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

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](#defaults-and-impact-on-evidence) |
| SDK silently stops sending | Token suspended or revoked | Check token status in [Account › API tokens tab](/admin-ui/account/api-tokens) |

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