Environment Variables

tif1 can be configured using environment variables or a .tif1rc configuration file. Environment variables take precedence over file-based configuration.

Core Configuration

TIF1_CACHE_DIR

Location for the SQLite cache database.

export TIF1_CACHE_DIR="/path/to/cache"

Default: Windows %LOCALAPPDATA%/Temp/tif1; macOS ~/Library/Caches/tif1; Linux/other POSIX ~/.cache/tif1 when ~/.cache exists, otherwise ~/.tif1.

TIF1_CACHE_ENABLED

Enable or disable caching globally.

export TIF1_CACHE_ENABLED=false

Default: true

TIF1_LIB

Default DataFrame lib to use.

export TIF1_LIB=polars

Default: pandasOptions: pandas, polars

Network Configuration

TIF1_CDNS

Configure multiple CDN sources for data fetching with automatic fallback.

export TIF1_CDNS='["https://cdn.jsdelivr.net/gh/TracingInsights", "https://huggingface.co/buckets/tracinginsights", "https://cdn.staticdelivr.com/gh/TracingInsights"]'

Default: jsDelivr (primary), Hugging Face buckets (fallback), StaticDelivr (last resort)The system tries CDNs in order and automatically falls back on failures.

TIF1_CDN_USE_MINIFICATION

Enable JSON minification for reduced file sizes.

export TIF1_CDN_USE_MINIFICATION=true

Default: falseWhen enabled, tif1 requests .min.json files which are 20-40% smaller.

TIF1_CDN_BASE_URL

Legacy single CDN configuration (deprecated: use TIF1_CDNS instead).

export TIF1_CDN_BASE_URL="https://cdn.jsdelivr.net/gh/TracingInsights"

Change this variable only for a privately hosted data mirror. Never use raw.githubusercontent.com because of rate limits.Use TIF1_CDNS for multi-CDN support with automatic fallback.

TIF1_REQUEST_TIMEOUT

Timeout for HTTP requests in seconds.

export TIF1_REQUEST_TIMEOUT=30

Default: 10 seconds

TIF1_MAX_RETRIES

Maximum number of retries for failed requests.

export TIF1_MAX_RETRIES=5

Default: 3

TIF1_RETRY_BACKOFF

Backoff multiplier for exponential retry delays.

export TIF1_RETRY_BACKOFF=2.0

Default: 1.5Formula: delay = base_delay * (backoff ^ attempt)

Circuit Breaker

TIF1_CIRCUIT_BREAKER_THRESHOLD

Number of consecutive failures before opening the circuit.

export TIF1_CIRCUIT_BREAKER_THRESHOLD=10

Default: 5

TIF1_CIRCUIT_BREAKER_TIMEOUT

Time in seconds before tif1 tries to close an open circuit.

export TIF1_CIRCUIT_BREAKER_TIMEOUT=120

Default: 60 seconds

Logging

TIF1_LOG_LEVEL

Set the logging verbosity.

export TIF1_LOG_LEVEL=DEBUG

Default: INFOOptions: DEBUG, INFO, WARNING, ERROR, CRITICAL

TIF1_LOG_FILE

Write logs to a file instead of stdout.

export TIF1_LOG_FILE="/var/log/tif1.log"

Default: None (logs to stdout)

Performance Tuning

TIF1_ASYNC_WORKERS

Number of concurrent workers for async operations.

export TIF1_ASYNC_WORKERS=20

Default: 10Higher values give more parallelism and more memory usage.

TIF1_MEMORY_CACHE_SIZE

Size of the in-memory LRU cache (number of items).

export TIF1_MEMORY_CACHE_SIZE=200

Default: 100

TIF1_HTTP2_ENABLED

Enable HTTP/2 for network requests.

export TIF1_HTTP2_ENABLED=true

Default: trueDisable this option only when connection problems occur.

Data Processing

TIF1_USE_CATEGORICAL

Convert string columns to categorical types for memory savings.

export TIF1_USE_CATEGORICAL=true

Default: trueThis option can reduce memory usage by 30-50%.

TIF1_TELEMETRY_FREQUENCY

Telemetry sampling frequency in Hz.

export TIF1_TELEMETRY_FREQUENCY=4

Default: 4 HzHigher values give more data points and larger files.

Configuration File

Instead of environment variables, create a .tif1rc file in the home directory or the project root.

Example .tif1rc

[cache]
enabled = true
directory = <platform-specific default>
memory_size = 100

[network]
cdns = ["https://cdn.jsdelivr.net/gh/TracingInsights", "https://huggingface.co/buckets/tracinginsights", "https://cdn.staticdelivr.com/gh/TracingInsights"]
cdn_use_minification = false
request_timeout = 10
max_retries = 3
retry_backoff = 1.5
http2_enabled = true

[circuit_breaker]
threshold = 5
timeout = 60

[lib]
default = pandas
use_categorical = true

[logging]
level = INFO
file =

[performance]
async_workers = 10
telemetry_frequency = 4

Programmatic Configuration

Configure tif1 directly in code as an alternative.

import tif1

# Get the config singleton
config = tif1.get_config()

# Update settings
config.cache_enabled = False
config.lib = "polars"
config.log_level = "DEBUG"

# Configure multiple CDNs
config.cdns = [
    "https://cdn.jsdelivr.net/gh/TracingInsights",
    "https://huggingface.co/buckets/tracinginsights",
    "https://cdn.staticdelivr.com/gh/TracingInsights"
]
config.cdn_use_minification = True

# Or use the Config class directly
from tif1 import Config

Config.CACHE_DIR = "/custom/cache/path"
Config.MAX_RETRIES = 5

Priority Order

Configuration is resolved in this order (highest to lowest priority):

Programmatic configuration in code
Environment variables
.tif1rc in current directory
.tif1rc in home directory
Default values

Validation

Invalid configuration values raise a ConfigError at startup.

import tif1

try:
    config = tif1.get_config()
except tif1.ConfigError as e:
    print(f"Configuration error: {e}")

Best Practices

Use .tif1rc for Projects

Commit .tif1rc to version control for team consistency.

Use ENV for Deployment

Use environment variables in production for flexibility.

Keep Defaults

Override only the values that must change.

Document Changes

Add a comment for each changed default value.

Get Started

Guides

Concepts

Reference

Environment Variables

Core Configuration

TIF1_CACHE_DIR

TIF1_CACHE_ENABLED

TIF1_LIB

Network Configuration

TIF1_CDNS

TIF1_CDN_USE_MINIFICATION

TIF1_CDN_BASE_URL

TIF1_REQUEST_TIMEOUT

TIF1_MAX_RETRIES

TIF1_RETRY_BACKOFF

Circuit Breaker

TIF1_CIRCUIT_BREAKER_THRESHOLD

TIF1_CIRCUIT_BREAKER_TIMEOUT

Logging

TIF1_LOG_LEVEL

TIF1_LOG_FILE

Performance Tuning

TIF1_ASYNC_WORKERS

TIF1_MEMORY_CACHE_SIZE

TIF1_HTTP2_ENABLED

Data Processing

TIF1_USE_CATEGORICAL

TIF1_TELEMETRY_FREQUENCY

Configuration File

Example .tif1rc

Programmatic Configuration

Priority Order

Validation

Best Practices

Use .tif1rc for Projects

Use ENV for Deployment

Keep Defaults

Document Changes

​Core Configuration

​TIF1_CACHE_DIR

​TIF1_CACHE_ENABLED

​TIF1_LIB

​Network Configuration

​TIF1_CDNS

​TIF1_CDN_USE_MINIFICATION

​TIF1_CDN_BASE_URL

​TIF1_REQUEST_TIMEOUT

​TIF1_MAX_RETRIES

​TIF1_RETRY_BACKOFF

​Circuit Breaker

​TIF1_CIRCUIT_BREAKER_THRESHOLD

​TIF1_CIRCUIT_BREAKER_TIMEOUT

​Logging

​TIF1_LOG_LEVEL

​TIF1_LOG_FILE

​Performance Tuning

​TIF1_ASYNC_WORKERS

​TIF1_MEMORY_CACHE_SIZE

​TIF1_HTTP2_ENABLED

​Data Processing

​TIF1_USE_CATEGORICAL

​TIF1_TELEMETRY_FREQUENCY

​Configuration File

​Example .tif1rc

​Programmatic Configuration

​Priority Order

​Validation

​Best Practices

Use .tif1rc for Projects

Use ENV for Deployment

Keep Defaults

Document Changes

Core Configuration

TIF1_CACHE_DIR

TIF1_CACHE_ENABLED

TIF1_LIB

Network Configuration

TIF1_CDNS

TIF1_CDN_USE_MINIFICATION

TIF1_CDN_BASE_URL

TIF1_REQUEST_TIMEOUT

TIF1_MAX_RETRIES

TIF1_RETRY_BACKOFF

Circuit Breaker

TIF1_CIRCUIT_BREAKER_THRESHOLD

TIF1_CIRCUIT_BREAKER_TIMEOUT

Logging

TIF1_LOG_LEVEL

TIF1_LOG_FILE

Performance Tuning

TIF1_ASYNC_WORKERS

TIF1_MEMORY_CACHE_SIZE

TIF1_HTTP2_ENABLED

Data Processing

TIF1_USE_CATEGORICAL

TIF1_TELEMETRY_FREQUENCY

Configuration File

Example .tif1rc

Programmatic Configuration

Priority Order

Validation

Best Practices