Metadata-Version: 2.4
Name: opspulse-sdk
Version: 0.1.0
Summary: OpsPulse Python SDK — send events from your backend services without ever breaking them
License-Expression: MIT
Project-URL: Homepage, https://github.com/mobosmartisok/opspulse
Project-URL: Repository, https://github.com/mobosmartisok/opspulse
Project-URL: Issues, https://github.com/mobosmartisok/opspulse/issues
Keywords: monitoring,incidents,alerting,error-tracking,opspulse
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# opspulse-sdk

Send errors and events from your Python backend to [OpsPulse](https://github.com/mobosmartisok/opspulse) without ever breaking your application.
Zero dependencies (standard library only). `capture()` never blocks and never raises: bounded queue, batching,
exponential backoff with jitter, secret redaction, flush at exit.

## Install
```bash
pip install opspulse-sdk
```
Python 3.9 or newer.

## Use
Create an API key in OpsPulse (Project → API keys), then:

```python
import opspulse

opspulse.init(
    api_key="opk_…",
    endpoint="https://opspulse.example.com/api/v1",   # your OpsPulse address
    source="billing-worker",                          # which service this is
)

# a business event (severity "error" or higher opens an incident)
opspulse.capture("job.failed", severity="error", fingerprint="invoice-sync", attributes={"job": "invoice-sync"})

# an exception
try:
    ...
except Exception as e:
    opspulse.capture_exception(e)

# standard logging
import logging
logging.getLogger().addHandler(opspulse.OpsPulseHandler(opspulse._client))
```

## Guarantees
- **Never breaks your app:** errors inside the SDK are swallowed; `capture()` returns immediately.
- **Secrets stay home:** keys such as `password`, `token`, `api_key` are replaced with `[REDACTED]` before leaving the process.
- **Safe to retry:** every event has an id; resending is deduplicated by the server.
- **Bounded memory:** the queue is capped (default 1000); the oldest events are dropped under pressure.
- **Flushed on exit:** pending events are sent when the process ends (`opspulse.flush()` to force).

## Raw API (any other language)
```bash
curl -X POST https://opspulse.example.com/api/v1/ingest/events \
  -H "Authorization: Bearer opk_…" -H "Content-Type: application/json" \
  -d '{"schema_version":1,"event_id":"<uuid>","source":"billing","event_type":"job.failed","severity":"error","occurred_at":"2026-01-01T00:00:00Z","fingerprint":"invoice-sync","attributes":{}}'
```

## Links
- Source and issues: <https://github.com/mobosmartisok/opspulse>
- Report a problem: <https://github.com/mobosmartisok/opspulse/issues>

## License
[MIT](LICENSE). The SDK runs inside your application, so it is open source; the OpsPulse server is licensed separately.
