Metadata-Version: 2.4
Name: nexusapm
Version: 1.0.0
Summary: NexusAPM Python auto-instrumentation SDK (Flask / FastAPI)
Home-page: https://github.com/Intelli-APM/apm/tree/main/agent/nexusapm-python
Author: NexusAPM
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Framework :: Flask
Classifier: Framework :: FastAPI
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Provides-Extra: accurate-memory
Requires-Dist: psutil; extra == "accurate-memory"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# nexusapm (Python SDK)

One-line auto-instrumentation for Flask and FastAPI applications, reporting
to a [NexusAPM](https://github.com/Intelli-APM/apm) backend.

## Install

```bash
pip install nexusapm
```

## Usage

**Flask:**
```python
import nexusapm

nexusapm.init(app, service_name="my-app",
               backend_url="https://your-nexusapm-backend.example.com",
               api_key="your-api-key")  # or set NEXUSAPM_API_KEY in the environment
```

**FastAPI:**
```python
import nexusapm

nexusapm.init(app, service_name="my-api", framework="fastapi",
               backend_url="https://your-nexusapm-backend.example.com",
               api_key="your-api-key")
```

That's it — every request handled after this point is automatically traced.

## What gets captured automatically

- **Per request:** route, method, status, duration → sent as a trace
- **Per request:** response time → sent as a metric
- **Errors and slow requests** (4xx/5xx, or over 1s) → sent as log lines
- **Every 10 seconds:** app-level rollups — memory usage, average response
  time, request throughput, error rate

## Distributed tracing across services

If this app calls another NexusAPM-instrumented service over HTTP (via the
`requests` library), the current request's trace ID is automatically
propagated onto that outgoing call — no extra code needed. The two
services' spans show up correlated under one trace in the NexusAPM
dashboard, instead of two disconnected traces.

## Configuration

| Option         | Required | Default                        | Notes                                     |
|----------------|----------|----------------------------------|--------------------------------------------|
| `service_name` | No       | `"unknown-python-service"`       | Shows up as this service's name everywhere |
| `backend_url`  | No       | `http://localhost:3001`          | Your NexusAPM backend's URL                |
| `api_key`      | No*      | `NEXUSAPM_API_KEY` env var       | *Required for any data to actually be accepted — falls back to the env var if not passed explicitly |
| `framework`    | No       | `"flask"`                        | Set to `"fastapi"` for FastAPI apps        |
| `debug`        | No       | `False`                          | Logs `[NexusAPM]`-style debug lines        |

## Optional: more accurate memory reporting

```bash
pip install nexusapm[accurate-memory]
```

Uses `psutil` for real RSS memory instead of the standard-library fallback.

## License

MIT
