Token Runtime ID

A lightweight Python library for adding traceable runtime IDs to your logs. Perfect for tracking execution flow across nested function calls and correlating log entries.

What's This For?

Ever had a hard time following logs when multiple requests or tasks are running at the same time? This library automatically generates hierarchical runtime IDs that make it easy to trace which log entries belong to the same execution context.

[2024-01-15 10:30:45] [runtime_id: abc123] Starting request processing
[2024-01-15 10:30:46] [runtime_id: abc123:def456] Calling database
[2024-01-15 10:30:47] [runtime_id: abc123:def456] Query completed
[2024-01-15 10:30:48] [runtime_id: abc123] Request completed

Installation

pip install token-runtime-id

Quick Start

Basic Logging Integration

import logging
from token_runtime_id import runtime_id, RuntimeIdLogFilter, get_runtime_id

# Set up logging with the runtime ID filter
logger = logging.getLogger()
handler = logging.StreamHandler()
handler.addFilter(RuntimeIdLogFilter())
formatter = logging.Formatter('%(asctime)s [%(runtime_id)s] %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)
logger.setLevel(logging.INFO)

# Decorate your functions
@runtime_id
def process_request():
    logging.info("Processing request")
    query_database()
    logging.info("Request completed")

@runtime_id
def query_database():
    logging.info("Querying database")
    # Database query here...
    logging.info("Query finished")

process_request()

Output:

2024-01-15 10:30:45,123 [a1b2c3d4] Processing request
2024-01-15 10:30:45,124 [a1b2c3d4:e5f6g7h8] Querying database
2024-01-15 10:30:45,125 [a1b2c3d4:e5f6g7h8] Query finished
2024-01-15 10:30:45,126 [a1b2c3d4] Request completed

Features

• Automatic hierarchical IDs: Nested function calls build up IDs like parent:child:grandchild
• Context-safe: Uses Python's contextvars - works with threads and async
• Logging integration: Built-in logging filter to inject IDs into log records
• Highly configurable: Customize ID length, prefix, characters, depth, and more
• Zero external dependencies: Just Python standard library
• Framework agnostic: Works with any Python application

Configuration Options

The @runtime_id decorator accepts several configuration options:

@runtime_id(
    length=8,                    # Length of random ID segment (default: 8)
    prefix="API",                # Static prefix for root IDs (default: None)
    prefix_process_id=True,      # Include OS process ID (default: False)
    characters="0123456789abcd", # Character pool for random IDs (default: alphanumeric)
    max_depth=3,                 # Maximum nesting levels (default: 3)
    sep=":"                      # Separator between segments (default: ":")
)
def my_function():
    pass

Examples with Different Configurations

With process ID and custom prefix:

@runtime_id(prefix_process_id=True, prefix="API")
def handle_request():
    print(get_runtime_id())  # Output: 12345:API:a1b2c3d4

Shorter IDs:

@runtime_id(length=4)
def quick_task():
    print(get_runtime_id())  # Output: a1b2

Custom separator:

@runtime_id(sep=".")
def dotted_ids():
    print(get_runtime_id())  # Output: a1b2c3d4.e5f6g7h8

Advanced Usage

Accessing Runtime IDs

from token_runtime_id import get_runtime_id, require_runtime_id

@runtime_id
def my_function():
    # Get the current runtime ID (returns None if not set)
    current_id = get_runtime_id()

    # Require a runtime ID (raises RuntimeIdException if not set)
    required_id = require_runtime_id()

Custom Log Attribute Name

By default, the logging filter adds the runtime ID as runtime_id. You can customize this:

# Use a different attribute name
handler.addFilter(RuntimeIdLogFilter(record_attr_name="request_id"))
formatter = logging.Formatter('%(asctime)s [%(request_id)s] %(message)s')

API Reference

Decorators

@runtime_id

Decorator to generate and manage runtime IDs.

Parameters:

• length (int): Length of random ID segment. Default: 8
• prefix (str | None): Static prefix for root IDs. Default: None
• prefix_process_id (bool): Include OS process ID in root IDs. Default: False
• characters (str): Character pool for random generation. Default: "0123456789abcdefghijklmnopqrstuvwxyz"
• max_depth (int): Maximum nesting depth allowed. Default: 3
• sep (str): Separator between ID segments. Default: ":"

Raises:

• ValueError: If configuration parameters are invalid
• RuntimeIdException: If max_depth is exceeded

Functions

get_runtime_id() -> str | None

Returns the current runtime ID, or None if not set.

require_runtime_id() -> str

Returns the current runtime ID, or raises RuntimeIdException if not set.

Classes

RuntimeIdLogFilter

Logging filter that injects runtime IDs into log records.

Parameters:

• record_attr_name (str): Attribute name for the runtime ID in log records. Default: "runtime_id"

Raises:

• ValueError: If record_attr_name is not a valid Python identifier

RuntimeIdException

Exception raised when runtime ID operations fail.

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.