Metadata-Version: 2.4
Name: failsense
Version: 0.1.0
Summary: Error tracking and LLM monitoring for Python applications
Home-page: https://github.com/failsense/failsense-python
Author: FailSense Team
Author-email: support@failsense.com
Project-URL: Bug Tracker, https://github.com/failsense/failsense-python/issues
Project-URL: Documentation, https://docs.failsense.com
Project-URL: Homepage, https://failsense.com
Keywords: error-tracking monitoring llm ai observability failsense
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3.0.0,>=2.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# FailSense Python SDK

[![PyPI version](https://badge.fury.io/py/failsense.svg)](https://badge.fury.io/py/failsense)
[![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)

Error tracking and LLM monitoring for Python applications.

## Features

- ✅ **Error Tracking** - Automatic exception capture with stack traces
- ✅ **Monitor Tracking** - Cron job and uptime monitoring
- ✅ **AI Tracer** - LLM API call monitoring (tokens, cost, latency)
- ✅ **Session Replay** - User session recording
- ✅ **Breadcrumbs** - Track user actions before errors
- ✅ **Zero Config** - Works out of the box

## Installation

```bash
pip install failsense
```

## Quick Start

### 1. Get Your API Key

Sign up at [failsense.com](https://failsense.com) and get your API key from Settings.

### 2. Initialize the SDK

```python
from failsense import Client

fs = Client(
    dsn="https://api.failsense.com",
    api_key="fs_live_..."  # Your API key
)
```

### 3. Track Errors

```python
try:
    1 / 0
except Exception:
    fs.capture_exception()
```

### 4. Monitor LLM Calls

```python
from openai import OpenAI

# Wrap your LLM client
raw_client = OpenAI(api_key="sk-...")
client = fs.monitor(raw_client, tracer_id=1)

# Use normally - automatically tracked!
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

## Usage Examples

### Error Tracking

```python
from failsense import Client

fs = Client(dsn="https://api.failsense.com", api_key="fs_live_...")

# Automatic exception capture
try:
    risky_operation()
except Exception:
    fs.capture_exception()

# With additional context
try:
    process_user(user_id=123)
except Exception:
    fs.capture_exception(context={"user_id": 123, "action": "process"})
```

### Breadcrumbs

```python
# Track user actions
fs.add_breadcrumb("navigation", "User clicked checkout")
fs.add_breadcrumb("http", "API call to /payment", data={"amount": 99.99})

# Breadcrumbs are automatically attached to errors
try:
    process_payment()
except Exception:
    fs.capture_exception()  # Includes breadcrumbs
```

### Monitor Tracking

```python
# Cron job monitoring
from failsense import Client

fs = Client(dsn="https://api.failsense.com", api_key="fs_live_...")

def daily_backup():
    try:
        backup_database()
        fs.check_in_monitor(monitor_id=1, status="ok")
    except Exception as e:
        fs.check_in_monitor(monitor_id=1, status="error", metadata={"error": str(e)})
```

### AI Tracer (LLM Monitoring)

```python
from failsense import Client
from openai import OpenAI

fs = Client(dsn="https://api.failsense.com", api_key="fs_live_...")

# Wrap your LLM client
raw_client = OpenAI(api_key="sk-...")
client = fs.monitor(raw_client, tracer_id=1)

# All calls are automatically tracked
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Explain quantum physics"}]
)

# Tracks:
# - Tokens used (input/output)
# - Latency
# - Cost estimation
# - Errors (with full prompt for debugging)
```

## Configuration

### DSN Options

```python
# Production
fs = Client(dsn="https://api.failsense.com", api_key="fs_live_...")

# Self-hosted
fs = Client(dsn="https://failsense.yourcompany.com", api_key="...")

# Local development
fs = Client(dsn="http://localhost:8000", api_key="...")
```

### Graceful Shutdown

```python
import atexit

fs = Client(dsn="...", api_key="...")

# Flush pending events on exit
atexit.register(fs.close)
```

## Framework Integration

### Django

```python
# settings.py
FAILSENSE_DSN = "https://api.failsense.com"
FAILSENSE_API_KEY = "fs_live_..."

# middleware.py
from failsense import Client

fs = Client(dsn=settings.FAILSENSE_DSN, api_key=settings.FAILSENSE_API_KEY)

class FailsenseMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        try:
            response = self.get_response(request)
            return response
        except Exception:
            fs.capture_exception(context={"path": request.path})
            raise
```

### Flask

```python
from flask import Flask
from failsense import Client

app = Flask(__name__)
fs = Client(dsn="https://api.failsense.com", api_key="fs_live_...")

@app.errorhandler(Exception)
def handle_exception(e):
    fs.capture_exception()
    return "Internal Server Error", 500
```

### FastAPI

```python
from fastapi import FastAPI, Request
from failsense import Client

app = FastAPI()
fs = Client(dsn="https://api.failsense.com", api_key="fs_live_...")

@app.middleware("http")
async def failsense_middleware(request: Request, call_next):
    try:
        response = await call_next(request)
        return response
    except Exception:
        fs.capture_exception(context={"path": request.url.path})
        raise
```

## Supported LLM Providers

- ✅ OpenAI (GPT-3.5, GPT-4)
- ✅ Anthropic (Claude 3)
- ✅ Google (Gemini)
- ✅ Any provider with `chat.completions.create()` interface

## Requirements

- Python 3.8 or higher
- `requests>=2.25.0`

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Links

- **Homepage**: https://failsense.com
- **Documentation**: https://docs.failsense.com
- **GitHub**: https://github.com/failsense/failsense-python
- **PyPI**: https://pypi.org/project/failsense
- **Support**: support@failsense.com

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Changelog

### 0.1.0 (2026-01-17)

- Initial release
- Error tracking
- Monitor tracking
- AI Tracer (LLM monitoring)
- Breadcrumbs
- Session replay support
