Logging

Logging configuration and utilities for tif1

Overview

tif1 provides logging functions to control verbosity and debug output. The logging system uses Python’s standard logging module with customizable levels.

Functions

setup_logging()

def setup_logging(level: int = logging.WARNING) -> None

Configure logging for tif1 with a specific log level.

Parameters:

• level (int, optional): Logging level constant from Python’s logging module. Defaults to logging.WARNING

Available Levels:

• logging.DEBUG - Detailed information for debugging
• logging.INFO - Informational messages
• logging.WARNING - Warning messages (default)
• logging.ERROR - Error messages
• logging.CRITICAL - Critical errors

Behavior:

• Sets up basic logging configuration with timestamp formatting
• Configures the tif1 logger to the specified level
• Suppresses noisy urllib3_future connection warnings (sets to ERROR level)

Example:

import logging
import tif1

# Enable debug logging
tif1.setup_logging(logging.DEBUG)

# Enable info logging
tif1.setup_logging(logging.INFO)

# Set to warning (default)
tif1.setup_logging(logging.WARNING)

set_log_level()

def set_log_level(level: str) -> None

Set the tif1 log level using a string name (fastf1-compatible function).

Parameters:

• level (str): Log level name as a string:
  • "DEBUG" - Detailed debugging information
  • "INFO" - General informational messages
  • "WARNING" - Warning messages
  • "ERROR" - Error messages
  • "CRITICAL" - Critical errors

Note: This function is part of the fastf1 compatibility layer and provides the same interface as fastf1’s logging functions.

Example:

import tif1

# Set log level using string
tif1.set_log_level('DEBUG')
tif1.set_log_level('INFO')
tif1.set_log_level('WARNING')

Log Format

The default log format includes:

• Timestamp (YYYY-MM-DD HH:MM:SS)
• Logger name
• Log level
• Message

Example output:

2024-03-15 14:23:45 - tif1.cache - INFO - Loaded config from /home/user/.tif1rc
2024-03-15 14:23:45 - tif1.cache - DEBUG - SQLite cache initialized at /home/user/.cache/tif1/cache.sqlite
2024-03-15 14:23:46 - tif1.core - DEBUG - Cache hit (memory): 2024/Monaco/R/laps

Configuration via Config

You can also set the log level through the configuration system:

import tif1

config = tif1.get_config()
config.set('log_level', 'DEBUG')

Or via environment variable:

export TIF1_LOG_LEVEL="DEBUG"

Or in .tif1rc configuration file:

{
  "log_level": "DEBUG"
}

See Configuration for more details.

Examples

Basic Setup

import logging
import tif1

# Enable debug logging to see all operations
tif1.setup_logging(logging.DEBUG)

# Now all tif1 operations will log debug messages
session = tif1.get_session(2024, 'Monaco', 'R')
session.load()

Conditional Debug Mode

import logging
import tif1
import os

# Enable debug logging in development
if os.getenv('DEBUG'):
    tif1.setup_logging(logging.DEBUG)
else:
    tif1.setup_logging(logging.WARNING)

session = tif1.get_session(2024, 'Monaco', 'R')
session.load()

Using fastf1-Compatible Function

import tif1

# For fastf1 users - same interface
tif1.set_log_level('DEBUG')

session = tif1.get_session(2024, 'Monaco', 'R')
session.load()

Info Level for Production

import logging
import tif1

# Show important events but not debug details
tif1.setup_logging(logging.INFO)

session = tif1.get_session(2024, 'Monaco', 'R')
session.load()
# Will show: cache hits, data loading, etc.

Quiet Mode (Errors Only)

import logging
import tif1

# Only show errors
tif1.setup_logging(logging.ERROR)

session = tif1.get_session(2024, 'Monaco', 'R')
session.load()
# Will only show errors, no info or debug messages

Custom Logger Configuration

import logging
import tif1

# Set up custom handler
handler = logging.FileHandler('tif1.log')
handler.setLevel(logging.DEBUG)

formatter = logging.Formatter(
    '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
handler.setFormatter(formatter)

logger = logging.getLogger('tif1')
logger.addHandler(handler)
logger.setLevel(logging.DEBUG)

# Now tif1 logs will also go to tif1.log file
session = tif1.get_session(2024, 'Monaco', 'R')
session.load()

Environment-Based Configuration

# Set via environment variable
export TIF1_LOG_LEVEL="DEBUG"
python my_script.py

# my_script.py
import tif1

# Log level is already set from TIF1_LOG_LEVEL env var
session = tif1.get_session(2024, 'Monaco', 'R')
session.load()

Log Categories

tif1 uses different loggers for different components:

Logger	Component
tif1	Root logger for all tif1 messages
tif1.config	Configuration loading and validation
tif1.cache	Cache operations (hits, misses, writes)
tif1.core	Core data loading and session management
tif1.retry	Retry logic and circuit breaker
tif1.async_fetch	Async HTTP fetching
tif1.http_session	HTTP session management
tif1.cdn	CDN operations and fallbacks

Filter Specific Components

import logging

# Only debug cache operations
logging.getLogger('tif1.cache').setLevel(logging.DEBUG)

# Keep everything else at WARNING
logging.getLogger('tif1').setLevel(logging.WARNING)

Typical Log Messages

DEBUG Level

Cache hit (memory): 2024/Monaco/R/laps
Cache hit (SQLite): 2024/Monaco/R/telemetry/VER/1
Cached: 2024/Monaco/R/session
SQLite cache initialized at ~/.cache/tif1/cache.sqlite with WAL mode

INFO Level

Loaded config from ~/.tif1rc
Cache cleared
Saved config to ~/.tif1rc

WARNING Level

Invalid timeout=0, using default=30
Failed to load config from ~/.tif1rc: JSON decode error
SQLite cache unavailable: Permission denied
No valid HTTPS cdns found in config, using default

ERROR Level

Failed to save config to ~/.tif1rc: Permission denied

Best Practices

1. Development: Use DEBUG level to see all operations

   tif1.setup_logging(logging.DEBUG)
   

2. Production: Use WARNING (default) or ERROR to reduce noise

   tif1.setup_logging(logging.WARNING)
   

3. Debugging Issues: Enable DEBUG temporarily to diagnose problems

   tif1.setup_logging(logging.DEBUG)
   # ... reproduce issue ...
   tif1.setup_logging(logging.WARNING)  # restore
   

4. CI/CD: Use ERROR level to keep logs clean

   import os
   if os.getenv('CI'):
       tif1.setup_logging(logging.ERROR)
   

5. File Logging: Add file handler for persistent logs

   import logging
   handler = logging.FileHandler('tif1.log')
   logging.getLogger('tif1').addHandler(handler)
   

Source Code

For the complete implementation:

• setup_logging(): __init__.py:120-140
• set_log_level(): fastf1_compat.py (re-exported in __init__.py:89)