token-runtime-id 0.2.0
A lightweight Python library for adding traceable runtime IDs to your logs
Requires Python: >=3.11

# 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.

```python
[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

```bash
pip install token-runtime-id
```

## Quick Start

### Basic Logging Integration

```python
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:

```python
@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:**
```python
@runtime_id(prefix_process_id=True, prefix="API")
def handle_request():
    print(get_runtime_id())  # Output: 12345:API:a1b2c3d4
```

**Shorter IDs:**
```python
@runtime_id(length=4)
def quick_task():
    print(get_runtime_id())  # Output: a1b2
```

**Custom separator:**
```python
@runtime_id(sep=".")
def dotted_ids():
    print(get_runtime_id())  # Output: a1b2c3d4.e5f6g7h8
```

## Advanced Usage

### Accessing Runtime IDs

```python
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:

```python
# 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.