exemplar-python-sdk 0.1.0

Exemplar monitoring client — singleton SDK with heartbeat helpers

exemplar-python-sdk

Python client for Exemplar monitoring. The client is a singleton: initialize once with your API key, then send heartbeats from sync or async code.

Install

From PyPI (import name is still exemplar):

pip install exemplar-sdk

From a local checkout, poetry install installs this project into Poetry’s virtualenv (no separate pip step needed):

poetry install

To smoke-test the built wheel inside that same env (after poetry build):

poetry run pip install dist/exemplar_sdk-*.whl

Using plain pip install dist/... uses whatever pip is first on your PATH (often system Python) and can fail with permission errors on macOS.

Requires Python 3.9+.

Usage

1. Initialize once (API key)

Call init at application startup (before any heartbeat). A second init raises RuntimeError.

import exemplar

exemplar.init(api_key="<personal_access_token>")
# optional: exemplar.init(api_key="...", base_url="https://production-api.exemplar.dev")

2a. Simple heartbeat (sync)

Use from a cron job, Celery task, Flask/Django view, or any synchronous code:

import exemplar

exemplar.init(api_key=os.environ["EXEMPLAR_API_KEY"])

exemplar.send_heartbeat(
    "69c3a0754e257b7d18094f9a",
    metadata={"hostname": "worker-01"},
)

This sends POST /api/monitoring/heartbeat with Content-Type: application/json and header X-API-Key: <token>, matching:

curl -sS -X POST 'https://production-api.exemplar.dev/api/monitoring/heartbeat' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: <personal_access_token>' \
  -d '{"monitor_id":"69c3a0754e257b7d18094f9a","metadata":{"hostname":"worker-01"}}'

2b. Background loop (async)

For FastAPI, Starlette, asyncio services, or any framework that runs an async event loop: start a task that heartbeats on an interval (like a cron in the background):

import asyncio
import exemplar

async def main():
    exemplar.init(api_key="...")
    asyncio.create_task(
        exemplar.heartbeat_background_loop(
            "69c3a0754e257b7d18094f9a",
            interval_seconds=60.0,
            metadata={"hostname": "worker-01"},
        )
    )
    ...

Cancel the task when shutting down. Pass a shared httpx.AsyncClient if you want connection reuse with other HTTP calls.

Development

poetry install
poetry run pytest

API summary

Function	Role
exemplar.init(api_key=..., base_url=...)	Create singleton (call once)
exemplar.get_client()	Access the client after init
exemplar.send_heartbeat(monitor_id, metadata=...)	One synchronous POST
exemplar.heartbeat_background_loop(...)	Async infinite loop with interval_seconds