Metadata-Version: 2.4
Name: vibemonitor-py
Version: 0.1.0
Summary: Vibemonitor Python SDK — capture and send logs to Vibemonitor
Author-email: Vibemonitor <sdk@vibemonitor.ai>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://vibemonitor.ai
Project-URL: Documentation, https://docs.vibemonitor.ai/sdk/python
Project-URL: Repository, https://github.com/vibemonitor/vibemonitor-python
Project-URL: Issues, https://github.com/vibemonitor/vibemonitor-python/issues
Keywords: logging,observability,monitoring,logs,vibemonitor
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0

# Vibemonitor Python SDK

Capture and send application logs to [Vibemonitor](https://vibemonitor.ai) with one line of code.

## Installation

```bash
pip install vibemonitor
```

## Quick Start

```python
import vibemonitor

vibemonitor.init(api_key="your-api-key")
```

That's it. All your existing Python logging is now auto-captured and sent to Vibemonitor.

```python
import logging

logger = logging.getLogger("auth-service")

logger.info("User 46 logged in")              # → sent to Vibemonitor
logger.error("OTP expired for user 45")        # → sent to Vibemonitor
logger.exception("Payment failed")            # → sent with full traceback
```

## How It Works

1. **Auto-capture** — The SDK hooks into Python's built-in `logging` module. Every `logger.info()`, `logger.error()`, `logger.exception()` call is automatically captured.

2. **Non-blocking** — Logs are queued in memory and sent by a background thread. Your application is never slowed down.

3. **Compressed** — Logs are gzip-compressed before sending, reducing bandwidth by ~80%.

4. **Safe** — The SDK never crashes your application. All internal errors are silently handled.

5. **Auto-detect service name** — If you don't specify a service name, the SDK detects it automatically from `pyproject.toml`, Flask, Django, FastAPI, or the script filename.

## Get Your API Key

1. Log in to [vibemonitor.ai](https://vibemonitor.ai)
2. Go to **Settings** → **API Keys**
3. Click **Create API Key** and copy the token

## Configuration

```python
vibemonitor.init(
    api_key="your-api-key",
    service="auth-service",      # optional: auto-detected if not set
    environment="production",    # optional: from VIBEMONITOR_ENV env var
    version="2.3.1",             # optional: from VIBEMONITOR_VERSION env var
)
```

### Service Name Auto-Detection

If you don't pass `service=`, the SDK detects it automatically:

| Priority | Source | Example |
|----------|--------|---------|
| 1 | `init(service="auth")` | `auth` |
| 2 | `VIBEMONITOR_SERVICE` env var | `auth-service` |
| 3 | `pyproject.toml` name field | `my-api` |
| 4 | Flask / Django / FastAPI app name | `payments` |
| 5 | Script filename | `auth_service` (from `auth_service.py`) |
| 6 | Fallback | `unknown-service` |

### Environment Variables

All settings can be configured via environment variables:

```bash
VIBEMONITOR_SERVICE=auth-service
VIBEMONITOR_ENV=production
VIBEMONITOR_VERSION=2.3.1
VIBEMONITOR_FLUSH_INTERVAL=2.0          # seconds between flushes (default: 2)
VIBEMONITOR_MAX_QUEUE_SIZE=1000         # max logs in queue (default: 1000)
VIBEMONITOR_SCRUB_PATTERNS=email,ip,credit_card,password,jwt,aws_key
```

### Data Scrubbing

The SDK automatically redacts sensitive data before sending. Enabled by default for: emails, phone numbers, IPs, credit cards, passwords, JWTs, AWS keys, and more.

## Manual Logging

For logs outside the standard `logging` module:

```python
vibemonitor.log(
    severity="ERROR",
    message="Custom event occurred",
    attributes={"user_id": "45", "order_id": "991"}
)
```

## Shutdown

To flush remaining logs on app exit:

```python
vibemonitor.shutdown()
```

This is called automatically via `atexit`, but you can call it explicitly for immediate flush.

## Requirements

- Python 3.8+
- `httpx` (installed automatically)

---

## Development

### Local testing

```bash
# Install in editable mode
pip install -e .

# Override the endpoint for local testing
export VIBEMONITOR_ENDPOINT=http://localhost:8000/api/v1/ingest/logs

# Smoke-test the import
python -c "import vibemonitor; print(vibemonitor.__version__)"

# Build wheel + sdist
pip install build
python -m build
```

## Release Process

A GitHub Actions workflow publishes to PyPI automatically on push to `main`. Same pattern as the JavaScript SDK: bump version locally → push → CI handles the rest.

### One-time prerequisites

1. **PyPI account** — https://pypi.org/account/register (if you don't have one)
2. **PyPI API token** — https://pypi.org/manage/account/#api-tokens → "Add API token" → Scope: this project (or "Entire account" if the package isn't published yet)
3. **GitHub secret** — Repo → Settings → Secrets and variables → Actions → "New repository secret"
   - Name: `PYPI_TOKEN`
   - Value: the token from step 2 (starts with `pypi-`)
4. **(Optional)** Branch protection — Repo → Settings → Branches → require `Test + Build` and `Version Bump Guard` status checks for PRs

### Release flow

```bash
# 1. Make code changes
vim vibemonitor/scrubber.py

# 2. Smoke-check locally (optional but fast)
python -c "import vibemonitor; print(vibemonitor.__version__)"
python -m build

# 3. Bump version (updates pyproject.toml + vibemonitor/__init__.py atomically)
python scripts/bump-version.py patch      # 0.1.0 → 0.1.1
# or:
python scripts/bump-version.py minor      # 0.1.0 → 0.2.0
python scripts/bump-version.py major      # 0.1.0 → 1.0.0

# 4. Commit + push
git add -A
git commit -m "fix: scrubber edge case"
git push origin main
```

GitHub Actions then:
1. Runs `python -m build` + a quick `import vibemonitor` smoke test
2. **Version guard** — fails CI if `vibemonitor/` changed but `pyproject.toml` version wasn't bumped
3. Publishes to PyPI via `twine upload` (only if local version != PyPI version)
4. Tags the commit `v<version>` on GitHub

### What runs when

| Event | Build | Version Guard | Publish to PyPI |
|---|---|---|---|
| Push to `main` | ✓ | ✓ | ✓ |
| Pull request to `main` | ✓ | ✓ | ✗ |
| Manual dispatch (on main) | ✓ | ✓ | ✓ |

### What the version guard catches

```
Scenario                                      Result
───────────────────────────────────────────────────────────────────
README-only / CI / config change            →  ✓ Pass (no publish)
vibemonitor/*.py change + bumped version    →  ✓ Publish
vibemonitor/*.py change + NO bump           →  ❌ FAIL — reminds you
Bump only, no source change                 →  ✓ Publish
First push (no tags yet)                    →  ✓ Skip guard, let publish decide
```

The guard compares HEAD against the last `v*` tag. If source files under `vibemonitor/` changed since that release but `pyproject.toml`'s version is still at what's on PyPI, CI fails loudly with a reminder to run `python scripts/bump-version.py patch`.

Tags are **never deleted** — every release leaves a permanent `v<version>` tag. Standard practice; makes rollback and audit trivial.
