Metadata-Version: 2.4
Name: sentienguard-apm
Version: 1.0.0
Summary: SentienGuard APM SDK for Python — auto-instruments your app via OpenTelemetry
Project-URL: Homepage, https://sentienguard.com
Author: SentienGuard
License-Expression: MIT
Keywords: apm,monitoring,opentelemetry,performance,sentienguard
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: FastAPI
Classifier: Framework :: Flask
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Requires-Dist: opentelemetry-api>=1.20
Requires-Dist: opentelemetry-instrumentation>=0.41b0
Requires-Dist: opentelemetry-sdk>=1.20
Provides-Extra: aiohttp
Requires-Dist: opentelemetry-instrumentation-aiohttp-client>=0.41b0; extra == 'aiohttp'
Provides-Extra: all
Requires-Dist: opentelemetry-instrumentation-aiohttp-client>=0.41b0; extra == 'all'
Requires-Dist: opentelemetry-instrumentation-django>=0.41b0; extra == 'all'
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0; extra == 'all'
Requires-Dist: opentelemetry-instrumentation-flask>=0.41b0; extra == 'all'
Requires-Dist: opentelemetry-instrumentation-httpx>=0.41b0; extra == 'all'
Requires-Dist: opentelemetry-instrumentation-psycopg2>=0.41b0; extra == 'all'
Requires-Dist: opentelemetry-instrumentation-pymongo>=0.41b0; extra == 'all'
Requires-Dist: opentelemetry-instrumentation-redis>=0.41b0; extra == 'all'
Requires-Dist: opentelemetry-instrumentation-requests>=0.41b0; extra == 'all'
Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.41b0; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.20; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: django
Requires-Dist: opentelemetry-instrumentation-django>=0.41b0; extra == 'django'
Provides-Extra: fastapi
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: opentelemetry-instrumentation-flask>=0.41b0; extra == 'flask'
Provides-Extra: httpx
Requires-Dist: opentelemetry-instrumentation-httpx>=0.41b0; extra == 'httpx'
Provides-Extra: psycopg2
Requires-Dist: opentelemetry-instrumentation-psycopg2>=0.41b0; extra == 'psycopg2'
Provides-Extra: pymongo
Requires-Dist: opentelemetry-instrumentation-pymongo>=0.41b0; extra == 'pymongo'
Provides-Extra: redis
Requires-Dist: opentelemetry-instrumentation-redis>=0.41b0; extra == 'redis'
Provides-Extra: requests
Requires-Dist: opentelemetry-instrumentation-requests>=0.41b0; extra == 'requests'
Provides-Extra: sqlalchemy
Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.41b0; extra == 'sqlalchemy'
Description-Content-Type: text/markdown

# @sentienguard/apm — Python SDK

Minimal, production-safe APM SDK for Python applications. Powered by OpenTelemetry with zero manual instrumentation.

## Installation

```bash
# Pick the extras for your stack
pip install sentienguard-apm[flask]
pip install sentienguard-apm[django]
pip install sentienguard-apm[fastapi]

# Or install everything
pip install sentienguard-apm[all]
```

## Quick Start

```python
# 1. Import the SDK (before your app code)
import sentienguard_apm

# 2. Your app — that's it, no other changes needed
from flask import Flask
app = Flask(__name__)

@app.route("/users/<int:id>")
def get_user(id):
    return {"id": id}
```

Set environment variables:

```bash
SENTIENGUARD_APM_KEY=your-app-key
SENTIENGUARD_SERVICE=my-api
```

The SDK automatically instruments your application and sends metrics to SentienGuard.

## Configuration

All configuration is via environment variables (same as the Node.js SDK):

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SENTIENGUARD_APM_KEY` | Yes | — | Your application's APM key |
| `SENTIENGUARD_SERVICE` | Yes | — | Service name (e.g., `orders-api`) |
| `SENTIENGUARD_ENV` | No | `production` | Environment name |
| `SENTIENGUARD_ENDPOINT` | No | `https://sentienguard-dev.the-algo.com/api/v1/apm/ingest` | Backend URL |
| `SENTIENGUARD_FLUSH_INTERVAL` | No | `10` | Flush interval in seconds |
| `SENTIENGUARD_DEBUG` | No | `false` | Enable debug logging |

> **Note:** If `SENTIENGUARD_APM_KEY` or `SENTIENGUARD_SERVICE` is missing, the SDK disables itself silently.

## What Gets Tracked

- **HTTP Requests** — Incoming requests with method, route, status, and latency
- **Dependencies** — Outgoing HTTP calls to external services
- **Databases** — MongoDB, PostgreSQL, MySQL, Redis, SQLAlchemy queries
- **Errors** — Unhandled exceptions

## Framework Examples

### Flask

```bash
pip install sentienguard-apm[flask]
```

```python
import sentienguard_apm
from flask import Flask

app = Flask(__name__)

@app.route("/api/orders/<int:id>")
def get_order(id):
    return {"id": id}
```

### Django

```bash
pip install sentienguard-apm[django]
```

```python
# settings.py — no middleware needed, auto-instrumented
# Just ensure sentienguard_apm is imported early

# wsgi.py or manage.py
import sentienguard_apm  # add this line at the top
```

### FastAPI

```bash
pip install sentienguard-apm[fastapi]
```

```python
import sentienguard_apm
from fastapi import FastAPI

app = FastAPI()

@app.get("/api/users/{user_id}")
async def get_user(user_id: int):
    return {"id": user_id}
```

## Late Initialization (dotenv)

If you load environment variables after import (e.g., with `python-dotenv`):

```python
from dotenv import load_dotenv
load_dotenv()

import sentienguard_apm
sentienguard_apm.initialize(force=True)
```

## API Reference

```python
import sentienguard_apm

sentienguard_apm.initialize(force=True)  # Re-init after env change
sentienguard_apm.shutdown()              # Graceful shutdown (flushes pending data)
```

## Auto-Instrumented Libraries

The SDK auto-detects and instruments these libraries if installed:

| Library | Install extra | What's tracked |
|---------|--------------|----------------|
| Flask | `[flask]` | Incoming requests |
| Django | `[django]` | Incoming requests |
| FastAPI | `[fastapi]` | Incoming requests |
| requests | `[requests]` | Outgoing HTTP |
| httpx | `[httpx]` | Outgoing HTTP (sync + async) |
| aiohttp | `[aiohttp]` | Outgoing HTTP (async) |
| PyMongo | `[pymongo]` | MongoDB operations |
| psycopg2 | `[psycopg2]` | PostgreSQL queries |
| redis-py | `[redis]` | Redis commands |
| SQLAlchemy | `[sqlalchemy]` | SQL queries |

## Requirements

- Python >= 3.8

## License

MIT
