System Architecture Overview
The tif1 architecture follows three core principles:- Performance First: Every component is optimized for speed, from HTTP/2 multiplexing to orjson parsing to categorical data types.
- Resilience: Multi-tier caching, circuit breakers, and retry logic ensure reliability even under adverse network conditions.
- Transparency: Logging and monitoring show what happens at each stage.
High-Level Architecture Diagram
A session with no cached data skips the cache reads (ultra_cold_start, on by default). It also fetches each payload with a single attempt per CDN (ultra_cold_skip_retries). The fetched payloads still go to the cache, so the next load is warm.
Component Responsibilities
Session Object (core.py)
- Entry point for all data access
- Manages lazy loading of laps, telemetry, weather, and race control data
- Coordinates between cache layers and CDN fetching
- Handles backend selection (pandas vs polars)
cache.py)
- In-memory
LRUCachebuilt oncollections.OrderedDict - Stores raw JSON bytes plus a parsed-object front tier (not DataFrames)
- DataFrames live in the per-session
SessionMemoand the backend lap LRU (get_backend_lap_cache) - Default capacity: 1024 JSON payloads (
TIF1_MEMORY_CACHE_MAX_ITEMS) and 2048 telemetry payloads (TIF1_MEMORY_TELEMETRY_CACHE_MAX_ITEMS) - Eviction policy: Least Recently Used (LRU)
- Lifetime: Process duration only
cache.py)
- Disk-based cache using SQLite database
- Location: OS-dependent tif1 cache directory (configurable via
TIF1_CACHE_DIR); see the platform defaults in the configuration reference - Stores JSON payloads (compressed when 4096 bytes or larger) and pickled laps and telemetry frames
- Tables:
cache,telemetry_cache,laps_frames,laps_frames_pl,telemetry_frames,telemetry_frames_pl,missing_payloads - No expiry: entries persist until
clear()orinvalidate() - Only negative “missing on every CDN” verdicts expire, after 7 days
- Thread-safe: one shared connection guarded by a lock, WAL journal mode
cdn.py)
- Manages multiple CDN sources with automatic fallback
- Primary: jsDelivr CDN (
cdn.jsdelivr.net/gh/TracingInsights/{year}@main) - Fallback: Hugging Face buckets (
huggingface.co/buckets/tracinginsights/{year}/resolve) - Backup: StaticDelivr CDN (
cdn.staticdelivr.com/gh/TracingInsights/{year}/main) - Tracks failure counts per CDN source
- Automatically disables failing sources after 3 consecutive failures
- A 404 from one CDN falls through to the next, because mirrors can be stale
- A 403 from one CDN also falls through. jsDelivr answers 403 (“Package size exceeded the configured limit of 50 MB”) for a file its edge has not cached yet
- A 403 or 404 says nothing about the health of the mirror, so it does not count towards disabling it
- tif1 raises
DataNotFoundErrorwhen every CDN refuses the file with a 4xx error other than 408 or 429 (404 and 403 included) - A 408 or 429 means “try again later”, so it keeps the retryable
NetworkError. tif1 does not record it as a missing payload - Requests for files missing everywhere never burn the retry/backoff budget
- 5xx and transport errors keep the retryable
NetworkError - Handles URL encoding and path construction
- Never uses
raw.githubusercontent.comfor session data (strict rate limits) - The only raw GitHub request is
schedule_{year}.jsonof a live season inevents.py, cached forschedule_ttl_hours
async_fetch.py)
- Parallel HTTP requests using
niquests(HTTP/2 support) - Connection pooling and keep-alive
- Retries a payload with exponential backoff when every CDN fails
- Timeout management (default: 30s per request)
- Concurrency cap:
max_concurrent_requests(default 22)
retry.py)
- Prevents cascading failures during network issues
- States:
"closed"(normal),"open"(failing),"half-open"(testing recovery) - Failure threshold: 5 consecutive failures
- Recovery timeout: 60 seconds
- Automatic state transitions
orjson)
- High-performance JSON parsing (3x to 7x faster than stdlib
jsonon tif1 payloads) - Direct bytes-to-Python object conversion
validation.py)
- Pydantic-based validation of JSON structure (off by default; turn it on with the
validate_data,validate_lap_times, andvalidate_telemetryconfig keys) - Ensures data integrity before DataFrame construction
- Type coercion and default value handling
- Detailed error messages for debugging
core.py / core_utils)
- Converts the columnar JSON payloads (one list per field) to pandas/polars DataFrames
- Renames the short upstream keys (
time,s1,sesT,wAT, …) to FastF1 names - Example:
s1becomesSector1Time, andwATbecomesAirTemp - Column order follows FastF1, plus the tif1 columns at the end
- pandas laps keep a
RangeIndex(noLapNumberindex)
core.py)
- Adds the computed
LapTimeSecondscolumn (float seconds on both backends) - Keeps the per-lap weather fields of the payload as
WeatherTime,AirTemp, …,WindSpeed - Takes
Stint,IsPersonalBest, andDriverNumberfrom the payload as delivered - Takes
DriverandTeamfromdrivers.json; the payload keysdrvandteamstay as extra columns
core_utils/helpers.py)
- Applies the dtype contract of each backend (see Column types by backend)
- pandas: converts time columns to
timedelta64[ns]andDriver,Team,Compound,TrackStatustocategory - polars: converts time columns to
Duration("ns"),LapStartDatetoDatetime("ns"), and keeps text columns asString - Replaces sentinel strings such as
"None"with missing values; numeric columns stay 64-bit (nofloat32downcast)
Complete Data Loading Pipeline
The data loading pipeline consists of eight distinct stages. Each stage has specific responsibilities and performance characteristics. These details help with code optimization and troubleshooting.Stage 1: Request Initiation
When code accesses data through a Session object, tif1 initiates the loading pipeline. This stage involves property access, lazy evaluation, and request routing.- Property access runs the
Session.lapsproperty - Session checks if data is already loaded (
self._laps is not None) - If not loaded, the property checks the process-wide backend lap LRU under the key
f"{year}_{gp}_{session}_laps" - On a miss, the property runs
Session.laps_async()(public, for async code) withasyncio.run() laps_async()checks the SQLite laps frame tier, then loadsdrivers.json,f"{year}/{gp}/{session}/session_laptimes.json"and the requestedweather.json/rcm.jsonin one concurrent wave through the cache layer
- A repeated
session.lapsaccess returns the stored frame in about 1 µs - No network I/O at this stage
Stage 2: Multi-Tier Cache Lookup
The JSON payloads have a two-tier cache: memory and SQLite. The built DataFrames have their own tiers: the per-session memo, the process-wide backend lap LRU (100 sessions per backend), and the SQLite frame tables. This section explains the payload tiers first.Tier 1: Memory LRU Cache (L1 Cache)
The memory cache is the fastest tier, holding raw JSON payloads and their parsed objects in RAM. Technical Specifications:- Implementation:
LRUCachebuilt oncollections.OrderedDict(cache.py) - Storage: In-process memory (heap)
- Data format: orjson bytes, plus a parsed-dict front tier that skips re-parsing on repeat hits
- DataFrames: held only by the per-session
SessionMemo, the backend lap LRU, and the SQLite frame tier - Capacity: 1024 JSON payloads (
TIF1_MEMORY_CACHE_MAX_ITEMS), 2048 telemetry payloads (TIF1_MEMORY_TELEMETRY_CACHE_MAX_ITEMS) - Eviction: Least Recently Used (LRU) algorithm, maintained through writes only
- Access time: about 3 µs for a parsed hit (measured on a 343 KB payload)
- Thread safety:
LRUCache.settakes a lock; hot-path reads are lock-free - Persistence: None (cleared on process exit)
Tier 2: SQLite Persistent Cache (L2 Cache)
The SQLite cache provides persistent storage that survives process restarts. Technical Specifications:- Implementation:
sqlite3with one shared connection (check_same_thread=False) - Storage: Disk-based database file (
cache.sqlite) - Location: OS-dependent tif1 cache directory (configurable via
TIF1_CACHE_DIR); see the platform defaults in the configuration reference - Data format: Compressed JSON (zstd level 1; legacy zlib rows stay readable). Python 3.14+ uses the standard-library
compression.zstdbinding, 3.11-3.13 use thezstandardpackage; both write identical frames - Capacity: Unlimited (constrained by disk space)
- Access time: about 2 ms to read, decompress, and parse a 343 KB payload (measured)
- Thread safety: every SQLite call runs under
Cache._sqlite_lock - Write batching: writes commit every
cache_commit_interval(default 100) operations - Pragmas:
journal_mode=WAL,synchronous=NORMAL, 64 MB page cache - Persistence: Permanent (until
clear()orinvalidate(); nothing expires)
PRAGMA user_version stores the schema version of the telemetry frame tables. When it is older than the library expects, tif1 drops those tables once and rebuilds the frames from the payload tier.
Compression Strategy:
cache.clear() or cache.invalidate(scope) removes it.
The only time-to-live applies to the negative tier. When every CDN refuses a file in the
async batch path (laps and telemetry), tif1 records the key in missing_payloads. Later
batch lookups skip the network for that key until the verdict is older than
TIF1_MISSING_PAYLOADS_TTL_DAYS (default 7.0). A successful write for the same key drops
the verdict immediately.
tif1.get_cache() returns the tif1.cache.Cache instance. tif1.Cache is the separate
FastF1-compatibility helper in fastf1_compat.py.
Cache Lookup Flow
session_laptimes.json of a race (Intel Core i9-13900HX, Python 3.14):
Cache Warming Strategies:
Stage 3: CDN Fetching with Fallback Strategy
When both cache tiers miss, tif1 fetches data from the CDN. The fetch uses a multi-source strategy with automatic fallback.CDN Architecture
Primary Source: jsDelivr CDN- URL Pattern:
https://cdn.jsdelivr.net/gh/TracingInsights/{year}@main/{path} - Serves the TracingInsights GitHub data repos from a global CDN
- URL Pattern:
https://huggingface.co/buckets/tracinginsights/{year}/resolve/{path} - Mirrors the TracingInsights GitHub data repos with the same layout (no branch segment)
- Used when jsDelivr fails, returns 403 or 404, or is unavailable
- URL Pattern:
https://cdn.staticdelivr.com/gh/TracingInsights/{year}/main/{path} - Used when both jsDelivr and Hugging Face fail or are unavailable
- Never used for session payloads due to strict rate limits
- The one exception is the live event schedule. For the current season,
events.pyfetchestheOehrly/f1schedule/master/schedule_{year}.json, where calendar changes land first - That one small file is cached for
schedule_ttl_hours(default 6) - When all three sources fail, tif1 raises
NetworkErrorinstead of trying it. When every source refused the file with a 4xx other than 408 or 429, it raisesDataNotFoundError
URL Construction
Fallback Logic
Circuit Breaker Pattern
tif1 implements a circuit breaker to prevent cascading failures during network issues. Circuit Breaker States:-
"closed"(Normal Operation)- All requests pass through
- Failures are counted
- Threshold: 5 consecutive failures (
circuit_breaker_threshold)
-
"open"(Failing)- Requests fail immediately, without a network call
- Prevents overload of the failing service
- Duration: 60 seconds (
circuit_breaker_timeout)
-
"half-open"(Testing Recovery)- Requests are allowed through again
- Success → transition to
"closed" - Failure → transition back to
"open"
drivers.json, weather.json, rcm.json) records each failed request. Any success resets the count.
A missing, refused (403 or 404), or malformed payload is an answer from a healthy server. It does not count as a failure on either path.
When the breaker is open, the synchronous path raises CircuitBreakerOpenError and the async batch path raises NetworkError.
The block below is a simplified, single-threaded copy of tif1.retry.CircuitBreaker. The real class adds a lock. Read the live instance with tif1.get_circuit_breaker().
Retry Strategy
tif1 has one retry loop per fetch path:- Synchronous path (
PayloadLoader.fetch_from_cdn;drivers.json,weather.json,rcm.json): each CDN source gets its own retry loop (tif1.retry.retry_with_backoff, wrapped around the circuit breaker). OnlyNetworkErroris retried. A 403 or 404 moves on to the next source at once. - Async batch path (
fetch_json_async; laps and telemetry): each attempt walks all CDN sources once. tif1 waits and walks again only when every source failed. The wait ismin(retry_backoff_factor ** attempt, max_retry_delay)seconds, plus up toretry_jitter_maxseconds of jitter (default 0).
Request Timeout Management
tif1 uses one timeout value in seconds for every request (timeout, default 30). There are no separate connect, read, or total timeouts.
Stage 4: Async Parallel Fetching
tif1 fetches many payloads in parallel with asyncio, for example the telemetry files of many laps. The laps of a session come from one file,session_laptimes.json. tif1 fetches per-driver laptimes.json files in parallel only for drivers that this file does not cover.
Parallel Fetching
async_fetch.py runs the blocking requests of the shared niquests.Session in a thread pool. An asyncio.Semaphore caps the number of requests in flight (max_concurrent_requests, default 22). The block below is a simplified copy:
HTTP/2 Multiplexing
tif1 uses theniquests library. niquests supports HTTP/2 and multiplexes requests over a single TCP connection.
HTTP/1.1 Limitations:
- One request at a time per TCP connection
- Multiple connections required for parallelism
- High overhead: TCP handshake + TLS handshake per connection
- Head-of-line blocking
- Multiple requests over single TCP connection
- Binary framing for efficiency
- Header compression (HPACK)
- Stream prioritization
tif1.http_session (TIF1_HTTP_MULTIPLEXED, default true).
Connection Pooling
tif1.http_session.get_session() mounts one HTTPAdapter for https:// with these sizes:
timeout (default 30 seconds) to each request.
Error Handling in Parallel Fetching
fetch_multiple_async() in tif1.async_fetch returns one entry per request. A failed fetch becomes None, so one failure does not cancel the others. A file that every CDN reports as missing gives None silently. tif1 logs other failures at WARNING.
max_concurrent_requests semaphore, so a large batch needs no manual splitting.
Stage 5: High-Performance JSON Parsing
After the CDN fetch, tif1 parses JSON withorjson. On tif1 payloads, this library parses 3x to 7x faster than the standard Python json module.
Why orjson?
Performance Comparison (median of 7 runs, Intel Core i9-13900HX, Python 3.14):
Key Features:
- Written in Rust
- Direct bytes-to-Python object conversion (no intermediate string)
- Native support for datetime, UUID, and other types when it serializes
Parsing Pipeline
The block below is a simplified copy of the checks inasync_fetch.py. A body that is not valid JSON, or not a JSON object, raises InvalidDataError:
Data Structure Examples
Every payload is columnar: one JSON list per field, with the same length for every list. Missing values arrive as the string"None", which tif1 turns into NaN, NaT, or null. The examples show the first two entries of each list, from the 2025 Bahrain Grand Prix race.
Lap Data JSON Structure ({driver}/laptimes.json; session_laptimes.json has the same fields for every driver):
ms1 to ms3 (mini-sector strings), s1T to s3T, vi2, vfl, fresh, lST, delR, ff1G, and iacc. The other per-lap weather fields are wT, wH, wP, wR, wWD, and wWS. Times are float seconds.
Telemetry Data JSON Structure ({driver}/{lap}_tel.json, one file per lap; VER/10_tel.json shown):
weather.json):
Payload Size
tif1 payloads are small: one telemetry file per lap is about 150 KB. tif1 parses each payload whole with orjson; it does not stream them.Validation After Parsing
Validation is off by default (validate_data, validate_lap_times, validate_telemetry). When on, the models in tif1.validation check the columnar payload. Every non-empty list must have the same length. Stints must be 1 or more, and tyre life 0 or more. The block below is a cut-down version of tif1.validation.LapData:
Stage 6: DataFrame Construction and Transformation
After parsing and validating JSON, tif1 constructs DataFrames with optimized column names, types, and ordering.DataFrame Construction Pipeline
The block below is a simplified view ofcore_utils/helpers.py (_create_lap_df and _process_lap_df):
Column Naming Convention
tif1 uses the FastF1 column names (PascalCase), so FastF1 code reads tif1 frames without changes. Rename Mapping (an excerpt ofLAP_RENAME_MAP in core_utils/constants.py):
Type Optimization
tif1 applies a fixed dtype contract per backend. It does not downcast: numeric columns stay 64-bit. Pandas Type Optimization (simplified from_apply_laps_dtypes):
session.laps:
Column Ordering
tif1 orders lap columns as FastF1 does (FASTF1_LAPS_COLUMN_ORDER in core_utils/constants.py). The tif1 columns LapTimeSeconds and QualifyingSession come after the FastF1 columns. Payload columns that keep their upstream names come last: ms1 to ms3, drv, and team. Driver and Team come from drivers.json, so drv and team are not renamed:
Index Management
Pandas Index Strategy:Missing Data Handling
DataFrame Validation
Performance Benchmarks
DataFrame Construction Performance (2025 Bahrain Grand Prix race, 1128 laps, Intel Core i9-13900HX):
Memory Usage (2025 Bahrain Grand Prix race, as loaded; pandas
memory_usage(deep=True), polars estimated_size()):
Stage 7: Data Enrichment and Augmentation
After the dtype step, tif1 adds one computed column to the laps:LapTimeSeconds. The other analysis columns arrive with the payload. Examples are the per-lap weather columns, Stint, IsPersonalBest, and the telemetry channels RelativeDistance, DriverAhead, DistanceToDriverAhead, and AccelerationX/Y/Z.
The functions in this stage are recipes for extra columns that tif1 does not add. They run on the pandas backend: pass session.laps or a telemetry frame such as session.get_fastest_lap_tel(). On pandas, LapTime and the sector times are timedeltas, so the recipes use LapTimeSeconds for arithmetic with plain numbers.
Lap Data Enrichment
Computed Time Columns:Weather Data Integration
session.laps carries a weather sample that the source data matched to each lap (WeatherTime, AirTemp, …, WindSpeed), but that match is misaligned for many laps. laps.get_weather_data() returns the sample of each lap with the fastf1 rule. To attach the nearest sample of session.weather to another time column, use pd.merge_asof. Both LapStartTime and the weather Time are timedeltas from the session start on pandas:
Telemetry Enrichment
Acceleration Calculation:DriverAhead (the car number of the car ahead, missing when no car is ahead) and DistanceToDriverAhead (meters). The recipe below adds the 3-letter code of the car ahead at the lap start, from the lap positions:
session.get_circuit_info().corners lists the official corner numbers and their distances, which give a more reliable corner map than speed thresholds.
Enrichment Performance
The recipes are vectorized pandas operations. On a full race (about 1,100 laps) or one lap of telemetry, each recipe runs in milliseconds. The extra columns add memory in proportion to their count: each float64 column costs 8 bytes per row.Stage 8: Cache Storage and Finalization
The final stage saves processed data to both cache tiers and returns the DataFrame to the user.Cache Storage Strategy
Dual-Tier Write (memory first, then SQLite):ValueError inside the cache, which the read path logs
and turns into a cache miss.
Serialization for SQLite (frame tier):
Cache Eviction Policies
LRU Eviction (Memory Cache):VACUUM. Rows stay until a
caller removes them by scope:
missing_payloads verdicts older than
TIF1_MISSING_PAYLOADS_TTL_DAYS (default 7.0) are filtered out on load.
Cache Statistics and Monitoring
The cache keeps no hit or miss counters and exposes no statistics API. Measure cache effectiveness by timing a cold load against a warm one:tif1.setup_logging(logging.DEBUG) to see which tier answered each lookup.
Final Data Return
On pandas, thelaps property wraps the frame in the Laps class and links it to its session. tif1 does not set DataFrame.attrs. On polars, session.laps is a PolarsLaps: a pl.DataFrame subclass with the same methods, linked to its session.
Complete Pipeline Timing
Measured forsession.laps of the 2025 Bahrain Grand Prix race (Intel Core i9-13900HX, Python 3.14, pandas 3.0.6):
Data Transformation Through the Pipeline
This section follows data through each transformation stage. The details help with debugging and performance optimization.Stage-by-Stage Data Evolution
Stage 1: Raw JSON (from CDN)
The examples followVER/laptimes.json of the 2025 Bahrain Grand Prix race (57 laps). The payload is columnar: one list per field, one entry per lap.
- Format: UTF-8 encoded JSON, one list per field (42 fields)
- Size: ~18 KB for one driver, ~340 KB for
session_laptimes.json(all 20 drivers) - Naming: short upstream keys (
s1,sesT,wAT, …) - Types: Mixed (strings, numbers, booleans); missing values are the string
"None"
Stage 2: Python Dictionary (after orjson parsing)
- Format: Native Python dict of lists
- Types: Python native (int, float, str, bool)
- Access: O(1) dictionary lookups
Stage 3: Initial DataFrame (after construction)
- Format: pandas DataFrame
- Size: ~31 KB for one driver (57 laps)
- Column names: short upstream keys
- Types: Default pandas types; columns with
"None"entries areobject
Stage 4: Renamed DataFrame (after column renaming)
- Format: pandas DataFrame
- Size: Same as Stage 3
- Column names: FastF1 names (PascalCase)
- Types: Still default types
Stage 5: Typed DataFrame (after the dtype contract)
session.laps table, which has a RangeIndex. pick_driver() keeps them.
Characteristics:
- Format:
Laps(pandas) orpl.DataFrame(polars) - Size: ~25 KB for one driver (46 columns on pandas, including the FastF1
indexcolumn) - Columns: FastF1 order, then
LapTimeSecondsand the tif1 extras - Ready for analysis
Stage 6: Final DataFrame (cached and returned)
- Format: pandas/polars DataFrame
- Size: ~0.46 MB (pandas) or ~0.35 MB (polars) for the full race (1128 laps)
- Cached: the JSON payload (memory and SQLite tiers) and the built frame (backend lap LRU and SQLite laps frame tier)
- Ready: For immediate analysis
Data Type Comparison: Pandas vs Polars
tif1 applies a dtype contract per backend after construction. The table lists the types of the mainlaps columns, as loaded for the 2025 Bahrain Grand Prix race.
Key Differences:
- Time columns: pandas converts the upstream float seconds to
timedelta64[ns]; polars converts them toDuration("ns").LapTimeSecondsis a float on both backends. - String columns: pandas uses
category; polars usesString. SetTIF1_POLARS_LAP_CATEGORICAL=trueto getCategoricalon polars. - Missing values: polars uses
nullfor every type; pandas usesNaN,NaT, or<NA>, depending on the column type. - Integer columns with no missing values are
Int64on polars andfloat64on pandas (FastF1 convention).
Memory Usage Comparison
Full Pipeline Memory Usage (session_laptimes.json of the 2025 Bahrain Grand Prix race, 1128 laps):
On pandas, the dtype contract shrinks the frame: text columns become
category, and the "None" strings leave the object columns. Polars stores the same data in about a quarter less memory.
Advanced Performance Optimizations
tif1 implements many performance optimizations throughout the data pipeline. This section explains them for faster code and better architectural decisions.1. HTTP/2 Multiplexing and Connection Reuse
HTTP Protocol Evolution
HTTP/1.0 (Legacy):- One request per TCP connection
- Connection closed after each request
- High overhead: TCP handshake (3-way) + TLS handshake (2-3 round trips)
- Connection keep-alive (reuse connection)
- Pipelining (limited support)
- Head-of-line blocking (requests must complete in order)
- Binary framing protocol (vs text-based HTTP/1.1)
- Multiplexing: Multiple requests over single connection
- Header compression (HPACK algorithm)
- Stream prioritization
- No head-of-line blocking at HTTP layer
Implementation in tif1
tif1.http_session.get_session() returns the process-wide session. It is built once, with the settings below:
2. Lazy Loading and On-Demand Data Fetching
Lazy loading fetches data only when the code needs it. This reduces unnecessary network I/O and memory usage.Implementation
The block below is a simplified view oftif1.core.Session. The attribute names match the real class; the _build_* helpers stand for the property bodies.
Performance Benefits
3. Categorical Data Type Optimization
Converting string columns to categoricals gives large memory savings for columns with few distinct values.Memory Comparison
Performance Comparison
Automatic Categorization in tif1
4. Backend Selection: Pandas vs Polars
Select the backend that matches the workload. Data Backends lists measured times and memory for both backends. On the tables of one session, both backends finish common operations in about 1 ms. The polars frames use about 25% less memory for laps.When to Use Each Backend
Use Pandas When:- Compatibility with existing pandas code is required
- A library requires pandas (seaborn, scikit-learn, and others)
- Mutable DataFrames are required (in-place operations)
- Dataset is small (<10k rows)
- The complete pandas ecosystem is required
- The datasets are large (>100k rows), such as the telemetry of many sessions
- Memory is constrained
- Lazy evaluation is required
Switching Backends
5. Async Parallel Fetching
See Stage 4. Two settings control the parallelism:max_concurrent_requests(TIF1_MAX_CONCURRENT_REQUESTS, default 22): requests in flight for one batchtelemetry_prefetch_max_concurrent_requests(TIF1_TELEMETRY_PREFETCH_MAX_CONCURRENT_REQUESTS, default 32): requests in flight for a telemetry prefetch
6. JSON Parsing Optimization
orjson parses tif1 payloads 3x to 7x faster than stdlibjson (see Stage 5).
Benchmark Comparison
7. Cache Optimization Strategies
Pre-warming Cache
Cache Size Tuning
The config reads the environment once, when tif1 is first used, so set these variables before Python starts:8. Batch Operations
Process multiple items together for better performance.Performance Summary
Key Optimizations and Their Effect (measured on one machine, see the sections above):Comprehensive Error Handling
tif1 implements an error handling system with a hierarchical exception structure, detailed error context, and recovery strategies.Exception Hierarchy
src/tif1/exceptions.py defines eleven exception classes. Every one is exported from tif1. Nine of them form the TIF1Error hierarchy:
ValueError subclasses, not TIF1Error subclasses:
get_session() and get_event_by_name() raise EventNotFoundError when an event name matches no event of the season. They raise EventNotInSeasonError when a circuit or country alias names an event that is not on that season’s calendar. An example is "Suzuka" in 2021.
Every exception carries message (the formatted text) and context (a dict of keyword arguments passed at raise time). The constructors accept extra **context keys, so handlers should read e.context.get(...) rather than rely on attributes.
Network Errors
NetworkError is raised when every CDN source fails, when the circuit breaker is open, or when offline_mode is on and the cache misses. The synchronous path raises the subclass CircuitBreakerOpenError for the open breaker. The CDN fallback loop in cdn.py logs each failed source at WARNING before raising.
NetworkError too; raise TIF1_TIMEOUT or TIF1_MAX_RETRIES through the environment or tif1.get_config().set(...) when a slow link needs more headroom.
Data Not Found Errors
DataNotFoundError means every CDN refused the payload with a 4xx other than 408 or 429. It also means that the negative-verdict tier already knows the payload is missing.
DataNotFoundError. tif1 resolves the name with fuzzy matching, so a typo such as "Monacco" loads the Monaco Grand Prix. A fuzzy match needs a score of at least 70 out of 100. A name below that score, such as "Nonexistent Grand Prix", raises tif1.EventNotFoundError:
DriverNotFoundError and LapNotFoundError are subclasses, so one except tif1.DataNotFoundError handler covers all three.
Invalid Data Errors
InvalidDataError is raised when a payload fails pydantic validation in validation.py or cannot be parsed. Validation failures always raise; there is no fallback to unvalidated data.
Session Not Loaded Errors
SessionNotLoadedError is defined and exported for FastF1-style code paths. tif1 sessions load lazily on attribute access, so the current code never raises it.
Cache Errors
The cache never raises on read or write failures.tif1.CacheError exists in the
hierarchy as a direct TIF1Error subclass with no subclasses of its own. cache.py does
not raise it. tif1 logs a failed SQLite read, a corrupt compressed row, or a failed write.
Each case degrades to a cache miss, so the loader fetches from the CDN instead.
Diagnosing cache problems
cache.sqlite at startup, tif1 logs SQLite cache unavailable
and runs without the payload cache: reads return nothing and writes are skipped. The
per-session memo and the backend lap LRU still work.
Error Recovery Strategies
Automatic Retry with Exponential Backoff
Fallback to Alternative Data Source
Graceful Degradation
Error Context and Debugging
All tif1 exceptions include detailed context for debugging.Monitoring and Observability
tif1 provides monitoring capabilities for understanding system behavior, diagnosing issues, and optimizing performance.Logging System
Log Levels and Configuration
What Gets Logged
The lines below use the custom format from the previous example. The messages come from the tif1 source. The exact set depends on the tif1 version and on which cache tiers answer. Cache keys use the URL-encoded event name. DEBUG Level (a session served from the SQLite cache):Cache miss lines. Its batch fetches log Fetched: ... from jsDelivr at DEBUG (tif1.async_fetch).
INFO Level:
Performance Monitoring
Timing Decorators
Performance Metrics Collection
Cache Monitoring
Cache Statistics
Cache Performance Testing
Circuit Breaker Monitoring
Network Monitoring
Request Tracking
Memory Monitoring
The memory examples usepsutil, which tif1 does not install. Install it with pip install psutil.
Comprehensive Monitoring Dashboard
Data Flow Patterns and Scenarios
Common data flow patterns help with code optimization for different use cases. The times are measured for the laps of the 2025 Bahrain Grand Prix race (Intel Core i9-13900HX, Python 3.14, pandas 3.0.6).Pattern 1: Cold Start (First Load)
Scenario: First time loading data, no cache available.- Pre-warm cache during application startup
- Use async loading for non-blocking operation
- Load only the required data (laps vs telemetry)
Pattern 2: Warm Start (SQLite Cache Hit)
Scenario: Data exists in the SQLite cache, but not in memory (for example, a new process).get_session(). Without a laps frame row, tif1 reads the payload tier and builds the frame (about 30 ms on pandas).
Network I/O: None
Optimization Tips:
- Keep SQLite cache on SSD for faster access
- Keep the cache directory between runs; cached payloads never expire
- Compare warm and cold load times (the cache keeps no hit counters)
Pattern 3: Hot Start (Memory Hit)
Scenario: Data exists in memory in the same process.- Reuse session objects to maximize memory hits
- Increase the memory cache size when RAM is available
- Keep frequently accessed data in memory
Pattern 4: Partial Cache Hit
Scenario: A telemetry batch (get_fastest_laps_tels()) where some laps are cached and others need fetching.
- Batch fetch missing laps with one call instead of one call per lap
- Pre-warm cache for commonly accessed sessions
- Use selective loading (only load needed drivers)
Pattern 5: Network Failure with Retry
Scenario: jsDelivr times out on a cached session, so tif1 falls back to Hugging Face. The timings assume the default settings (timeout 30 s, max_retries 3, retry_backoff_factor 2.0, jitter on).
The async batch path (laps and telemetry) walks all CDNs in one attempt:
drivers.json, weather.json, rcm.json) retries each CDN before it moves on:
ultra_cold_skip_retries), so it skips the backoff.
A 403 or 404 does not trigger these loops. tif1 moves to the next CDN at once. It raises DataNotFoundError when every CDN refuses the file with a 4xx other than 408 or 429.
Optimization Tips:
- Reduce
timeout(TIF1_TIMEOUT) ormax_retries(TIF1_MAX_RETRIES) for faster failure detection - After 3 failed fetches, tif1 skips a CDN source for the rest of the process
- After 5 consecutive failures, the circuit breaker fails fast for 60 seconds
Pattern 6: Batch Loading Multiple Sessions
Scenario: Load data for multiple sessions efficiently.Pattern 7: Incremental Data Loading
Scenario: Load data incrementally as needed.Pattern 8: Cache Warming Strategy
Scenario: Pre-warm cache for better user experience.Advanced Optimization Strategies
These strategies achieve maximum performance in production environments.Strategy 1: Intelligent Cache Pre-warming
Pre-warm cache strategically based on usage patterns.Strategy 2: Adaptive Timeout Management
Adjust timeouts based on network conditions.Strategy 3: Selective Data Loading
Load only the required data.Strategy 4: Batch Operations for Multiple Analyses
Batch operations to minimize overhead.Strategy 5: Memory-Efficient Iteration
Process large datasets without loading everything into memory.Strategy 6: Polars for Large-Scale Analysis
Use Polars for better performance on large datasets.Strategy 7: Connection Pooling Optimization
tif1 builds one shared niquests session per process, so tune it through the config, not through a custom adapter. Set these variables before Python starts:Strategy 8: Lazy Evaluation with Polars
Use Polars lazy evaluation for complex pipelines.Strategy 9: Compression for Cache Storage
Optimize cache storage with compression. The codec and level are fixed; there is no compression-level setting.Strategy 10: Monitoring-Driven Optimization
Use monitoring data to identify bottlenecks.Comprehensive Summary
The tif1 data flow architecture targets maximum performance, reliability, and developer experience. This section summarizes the key concepts and gives actionable recommendations.Architecture Principles
1. Performance First- Every component optimized for speed
- Multi-tier caching: a warm
session.lapsloads in about 1.5 ms, a repeated access in about 1 µs - HTTP/2 multiplexing enables parallel fetching
- orjson parses tif1 payloads 3x to 7x faster than stdlib
json - Categorical types cut the memory of the text columns by about 90% (pandas)
- Polars frames use 25-40% less memory than pandas frames
- Circuit breaker prevents cascading failures
- Automatic retry with exponential backoff
- Multi-source CDN fallback (jsDelivr → Hugging Face → StaticDelivr)
- Error handling with structured context (
e.context) - Graceful degradation for non-critical data
- Lazy loading minimizes unnecessary work
- Intuitive API with sensible defaults
- Detailed logging and monitoring capabilities
- Exceptions carry the year, event, session, and other keys of the failed request
- Flexible backend selection (pandas/polars)
Performance Characteristics
Load Time Comparison (laps of the 2025 Bahrain Grand Prix race, pandas, Intel Core i9-13900HX):
Memory Usage (same race):
Key Optimizations
1. Multi-Tier Caching- Memory: about 3 µs per payload read; 1024 JSON and 2048 telemetry payloads
- SQLite: about 2 ms per 343 KB payload read; unlimited capacity
- Laps frame tier: the built laps DataFrame in one SQLite row
- Automatic promotion from SQLite to memory
- No expiry: cached payloads persist until cleared
- HTTP/2 multiplexing over single connection
- Up to
max_concurrent_requests(default 22) requests in flight - A failed fetch in a batch becomes
Nonewithout cancelling the others - Automatic retry when every CDN fails
- Categorical encoding for string columns (pandas)
- Time columns as
timedelta64[ns](pandas) orDuration("ns")(polars) - Boolean flags as
bool/Boolean; numeric columns stay 64-bit - The pandas laps frame shrinks by about a third (718 KB to 462 KB for a full race)
- One computed column (
LapTimeSeconds); per-lap weather comes with the payload - Telemetry channels such as
RelativeDistance,DriverAhead, andAccelerationX/Y/Zcome with the payload - The Stage 7 recipes add more columns in a few milliseconds
Best Practices
For Maximum Performance:Common Pitfalls and Solutions
Pitfall 1: Creating New Sessions RepeatedlyPerformance Tuning Checklist
Before Deployment:- Enable appropriate logging level (INFO for production)
- Configure cache size based on available memory
- Set
TIF1_MISSING_PAYLOADS_TTL_DAYSif missing payloads should re-check sooner - Pre-warm cache for frequently accessed data
- Choose appropriate backend (pandas vs polars)
- Configure timeouts based on network conditions
- Set up monitoring and alerting
- Test error handling and recovery
- Watch the
Cache hitandCache missDEBUG log lines (the cache keeps no hit counters) - Monitor network success rate (target: > 95%)
- Monitor memory usage (should be stable)
- Monitor circuit breaker state (should be
"closed") - Check for slow queries (> 5s)
- Review error logs regularly
- Clear unused cache tiers with
cache.invalidate(scope)when disk space matters - Update cache warming strategy based on usage
- Profile code to identify bottlenecks
- Increase the memory cache size if repeated loads still miss
- Use Polars for large datasets
- Batch operations where possible
- Use async loading for non-blocking operations
- Optimize network timeouts
- Consider CDN proximity
- Review and optimize data loading patterns
Conclusion
The tif1 data flow architecture takes a complete approach to high-performance data loading and processing. Combine the eight-stage pipeline, multi-tier caching, async parallel fetching, and these best practices to get:- About 1.5 ms for a warm
session.lapsfrom the SQLite laps frame tier, and about 1 µs for a repeated access - Parallel fetches of many payloads, up to
max_concurrent_requestsat a time - About a third less memory for pandas laps through the dtype contract
- 25-40% less memory for the frames of the polars backend
- CDN fallback across three mirrors, with retries and a circuit breaker
Related Documentation
Caching Strategy
The multi-tier caching system.
Backends
Pandas vs Polars comparison and selection guide.
Sessions
Session management and data loading.
HTTP API
HTTP client and network operations.
Utilities
Helper functions and utilities.
CLI
Command-line interface for data management.
Additional Resources
- GitHub Repository: TracingInsights/tif1
- Issue Tracker: Report bugs and request features
- Discussions: Community discussions and Q&A
- Examples: Code examples and tutorials