tradata-perf 0.2.1
High-performance monitoring and optimization toolkit for trading applications
License: MIT
Requires Python: >=3.8

# Tradata Performance Package

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

High-performance monitoring and optimization toolkit for trading applications. Provides comprehensive performance monitoring, metrics collection, health checking, and HTTP optimization capabilities.

## 🚀 Features

### **Performance Monitoring**
- **Real-time monitoring** of API performance, response times, and throughput
- **Cache performance tracking** with hit/miss rates and efficiency metrics
- **System health monitoring** with comprehensive health checks
- **Performance alerts** and threshold monitoring

### **Metrics Collection**
- **Request/response metrics** with detailed breakdowns
- **Custom business metrics** collection and aggregation
- **Performance counters** and call tracking
- **Time-series metrics** with statistical analysis

### **FastAPI Middleware**
- **Performance monitoring middleware** for automatic request tracking
- **Cache monitoring middleware** for cache performance insights
- **Request timing middleware** with detailed timing headers
- **Performance headers middleware** for client-side monitoring

### **HTTP Optimization**
- **High-performance HTTP client** with connection pooling
- **Request optimization** and performance tuning
- **Automatic metrics collection** for external API calls
- **Connection management** and error handling

### **Decorators & Utilities**
- **Performance decorators** for automatic timing and profiling
- **Metrics decorators** for custom data collection
- **Business metrics decorators** for domain-specific monitoring
- **Performance profiling** with memory and CPU tracking

## 📦 Installation

### Basic Installation
```bash
pip install tradata-perf
```

### Development Installation
```bash
pip install tradata-perf[dev]
```

### Advanced Features
```bash
pip install tradata-perf[advanced]
```

## 🎯 Quick Start

### Basic Performance Monitoring

```python
from tradata_perf import PerformanceMonitoringMiddleware, get_performance_monitor
from fastapi import FastAPI

app = FastAPI()

# Add performance monitoring middleware
app.add_middleware(PerformanceMonitoringMiddleware)

# Get performance monitor instance
monitor = get_performance_monitor()

@app.on_event("startup")
async def startup():
    # Monitor is automatically initialized
    pass

@app.get("/performance")
async def get_performance():
    # Get comprehensive performance summary
    summary = monitor.get_performance_summary()
    return summary
```

### Using Performance Decorators

```python
from tradata_perf.decorators import timing, profile, monitor_performance

@timing
def slow_function():
    time.sleep(1)
    return "Done"

@profile(track_memory=True, track_cpu=True)
def memory_intensive_function():
    # Function automatically profiled
    return "Profiled"

@monitor_performance(threshold_ms=1000)
def critical_function():
    # Warning logged if execution exceeds 1 second
    return "Monitored"
```

### Custom Metrics Collection

```python
from tradata_perf.decorators import collect_metrics, business_metrics
from tradata_perf import get_metrics_collector

@collect_metrics(metric_type="histogram", tags={"service": "quotes"})
def process_quotes(symbols):
    # Metrics automatically collected
    return len(symbols)

@business_metrics(
    metric_name="quotes_processed",
    value_extractor=lambda result: len(result),
    tags={"service": "quotes"}
)
def get_quotes(symbols):
    # Business metrics automatically collected
    return ["AAPL", "TSLA", "GOOGL"]

# Manual metrics collection
collector = get_metrics_collector()
await collector.collect_custom_metric(
    name="custom_metric",
    value=42.0,
    tags={"category": "example"},
    metadata={"description": "Custom metric example"}
)
```

### HTTP Client Optimization

```python
from tradata_perf import get_http_client

# Get optimized HTTP client
http_client = get_http_client()

# Make optimized requests
response = await http_client.get("https://api.example.com/data")

# Get performance statistics
stats = http_client.get_performance_stats()
print(f"Success rate: {stats['success_rate_percent']}%")
```

## 🏗️ Architecture

### **Core Components**

```
tradata_perf/
├── monitoring/           # Performance monitoring core
│   ├── performance_monitor.py    # Main monitoring system
│   ├── metrics_collector.py      # Metrics collection
│   └── health_checker.py         # Health monitoring
├── middleware/           # FastAPI middleware
│   ├── performance.py            # Performance tracking
│   └── cache.py                  # Cache monitoring
├── http/                # HTTP optimization
│   └── optimized_client.py       # High-performance client
├── decorators/          # Performance decorators
│   ├── performance.py            # Timing & profiling
│   └── metrics.py                # Metrics collection
└── utils/               # Utility functions
    ├── timing.py                 # Timing utilities
    └── profiling.py              # Profiling tools
```

### **Data Flow**

1. **Request Processing**: Middleware automatically captures request metrics
2. **Performance Tracking**: Decorators measure function execution times
3. **Metrics Collection**: Centralized metrics collection and aggregation
4. **Health Monitoring**: Continuous health checks and status reporting
5. **Performance Analysis**: Real-time performance insights and alerts

## 📊 Performance Metrics

### **System Metrics**
- Total requests and success rates
- Average, P95, and P99 response times
- Requests per minute and throughput
- Error rates and failure analysis

### **Cache Metrics**
- Cache hit/miss rates by endpoint
- Cache operation durations
- Memory usage and eviction rates
- Cache health status

### **Custom Metrics**
- Business-specific metrics
- Performance counters
- Custom aggregations
- Time-series analysis

## 🔧 Configuration

### **Environment Variables**
```bash
# Performance monitoring
PERF_MONITORING_ENABLED=true
PERF_METRICS_INTERVAL=60
PERF_HEALTH_CHECK_INTERVAL=30

# HTTP client
PERF_HTTP_POOL_SIZE=100
PERF_HTTP_TIMEOUT=10.0

# Metrics collection
PERF_MAX_METRIC_SERIES=1000
PERF_METRICS_RETENTION_HOURS=24
```

### **Configuration Classes**
```python
from tradata_perf.config import PerformanceConfig

config = PerformanceConfig(
    monitoring_enabled=True,
    metrics_interval=60,
    health_check_interval=30,
    http_pool_size=100,
    enable_profiling=False
)
```

## 🧪 Testing

### **Run Tests**
```bash
# Basic tests
pytest

# With coverage
pytest --cov=tradata_perf

# Performance benchmarks
pytest --benchmark-only
```

### **Test Coverage**
- **Unit tests** for all components
- **Integration tests** for middleware
- **Performance benchmarks** for critical paths
- **Async testing** for all async components

## 📈 Performance Characteristics

### **Overhead**
- **Middleware overhead**: < 1ms per request
- **Memory footprint**: < 50MB baseline
- **CPU overhead**: < 2% under normal load
- **Metrics collection**: Non-blocking, async-first design

### **Scalability**
- **High-throughput**: Supports 10,000+ requests/second
- **Memory efficient**: Automatic cleanup of old metrics
- **Horizontal scaling**: Stateless design for microservices
- **Resource optimization**: Minimal impact on application performance

## 🚀 Use Cases

### **Trading Applications**
- **Real-time performance monitoring** of trading algorithms
- **API latency tracking** for market data providers
- **Cache performance optimization** for quote data
- **Health monitoring** of critical trading services

### **Microservices**
- **Distributed performance monitoring** across services
- **Service health tracking** and alerting
- **Performance correlation** between services
- **Resource utilization monitoring**

### **High-Frequency Systems**
- **Ultra-low latency monitoring** with minimal overhead
- **Real-time performance alerts** for SLA violations
- **Performance profiling** of critical code paths
- **Throughput optimization** and bottleneck identification

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### **Development Setup**
```bash
git clone https://github.com/tradata/tradata-perf-py.git
cd tradata-perf-py
pip install -e .[dev]
pytest
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- **Documentation**: [Full API Documentation](docs/API.md)
- **Examples**: [Usage Examples](examples/)
- **Issues**: [GitHub Issues](https://github.com/tradata/tradata-perf-py/issues)
- **Discussions**: [GitHub Discussions](https://github.com/tradata/tradata-perf-py/discussions)

## 🔗 Related Projects

- **[tradata-core](https://github.com/tradata/tradata-core)**: Core logging and tracing framework
- **[tradata-utils-py](https://github.com/tradata/tradata-utils-py)**: Utility and infrastructure components

---

**Built with ❤️ by the Tradata Team**