libalb

A Python library for processing AWS Application Load Balancer (ALB) logs.

Features

• Parse access logs: Extract detailed request/response information
• Parse connection logs: Analyze TLS connection details
• Parse health check logs: Monitor target health status
• S3 integration: Read logs directly from S3 buckets (optional)
• Type-safe: Full type hints for better IDE support and code quality
• Well-tested: Comprehensive test suite with pytest

Installation

Basic installation

# Using uv (recommended)
uv pip install libalb

# Using pip
pip install libalb

With S3 support

# Using uv
uv pip install "libalb[s3]"

# Using pip
pip install "libalb[s3]"

Development installation

# Clone the repository
git clone https://github.com/yourusername/libalb.git
cd libalb

# Install with development dependencies
uv pip install -e ".[dev,s3]"

Quick Start

Parsing Access Logs

from libalb import parse_access_log, parse_access_log_file

# Parse a single log line
log_line = 'https 2018-07-02T22:23:00.186641Z app/my-loadbalancer/...'
entry = parse_access_log(log_line)

print(f"Client: {entry.client_ip}:{entry.client_port}")
print(f"Status: {entry.elb_status_code}")
print(f"Request: {entry.request_method} {entry.request_url}")

# Parse an entire log file
entries = parse_access_log_file('access.log')
for entry in entries:
    if entry.elb_status_code >= 500:
        print(f"Server error at {entry.timestamp}: {entry.request_url}")

Parsing Connection Logs

from libalb.connection_logs import parse_connection_log_file

entries = parse_connection_log_file('connection.log')
for entry in entries:
    print(f"TLS {entry.tls_protocol} with {entry.tls_cipher}")

Reading Logs from S3

from libalb.s3_reader import list_log_files, read_log_from_s3
from libalb import parse_access_log

# List all log files in a bucket
bucket = 'my-alb-logs'
prefix = 'AWSLogs/123456789012/elasticloadbalancing/us-east-1/'
log_files = list_log_files(bucket, prefix)

# Read and parse logs from S3
for key in log_files:
    for line in read_log_from_s3(bucket, key):
        entry = parse_access_log(line)
        # Process entry...

Log Format Reference

Access Logs

Access logs contain detailed information about requests:

• Client and target IP/port
• Request timing (processing, target, response)
• HTTP status codes
• Request details (method, URL, protocol, user agent)
• TLS information (cipher, protocol)
• Target group ARN and trace ID

AWS Documentation

Connection Logs

Connection logs capture TLS connection information:

• Client IP and port
• TLS protocol and cipher
• Handshake latency
• Client certificate details (if mTLS)

AWS Documentation

Health Check Logs

Health check logs track target health:

• Target IP and port
• Health check protocol, port, and path
• Response status and time
• Health status and reason

AWS Documentation

Development

Setting up development environment

# Clone and install with dev dependencies
git clone https://github.com/yourusername/libalb.git
cd libalb
uv pip install -e ".[dev,s3]"

Running tests

# Run all tests
pytest

# Run with coverage
pytest --cov=libalb --cov-report=html

# Run only unit tests
pytest tests/unit/

# Run a specific test file
pytest tests/unit/test_access_logs.py

Code quality

# Format code with black
black src/ tests/

# Lint with ruff
ruff check src/ tests/

# Type check with mypy
mypy src/

Project Structure

libalb/
├── src/libalb/          # Source code
│   ├── __init__.py      # Public API exports
│   ├── access_logs.py   # Access log parsing
│   ├── connection_logs.py  # Connection log parsing
│   ├── health_logs.py   # Health check log parsing
│   └── s3_reader.py     # S3 integration
├── tests/               # Test suite
│   ├── unit/           # Unit tests
│   ├── integration/    # Integration tests
│   └── conftest.py     # Shared fixtures
├── examples/           # Example scripts
├── pyproject.toml      # Project metadata and config
└── README.md          # This file

Working with Claude Code

This project is structured for effective collaboration with Claude Code:

1. Clear module boundaries: Each log type has its own module
2. Type hints throughout: Helps Claude understand your intent
3. Comprehensive docstrings: Claude can reference documentation
4. Test-driven structure: Easy to add tests for new features
5. Configuration in pyproject.toml: Single source of truth

Tips for working with Claude Code:

• Ask Claude to implement parsing logic for specific log types
• Request new features like filtering, aggregation, or export formats
• Have Claude add tests for new functionality
• Ask for help analyzing log data patterns

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass and code is formatted
5. Submit a pull request

Roadmap

• Implement core parsing logic for all log types
• Add filtering and querying capabilities
• Support for streaming large log files
• CLI tool for quick log analysis
• Export to various formats (JSON, CSV, Parquet)
• Integration with pandas DataFrames
• Log aggregation and statistics