seerpy 0.1.8

A lightweight monitoring and heartbeat client for Seer API

SeerPy

SeerPy is the official Python client for the Seer Monitoring API by Ansr Studio. It helps you monitor jobs, capture logs, record heartbeats, and automatically report execution results to your Seer dashboard.

🚀 Installation

pip install seerpy

🔑 Getting Started

1. Import and initialize

from seerpy import Seer

# Initialize with your Seer API key
seer = Seer(apiKey="YOUR_SEER_API_KEY")

2. Monitor jobs

Use the monitor() context manager to automatically track job execution time, status, and logs.

with seer.monitor("daily_etl_job", capture_logs=True, metadata={"source": "data-lake"}):
    print("Running ETL job...")
    # Your job logic here
    raise Exception("Simulated error")  # This will be logged and marked as failed

When you run this, Seer automatically captures:

• Start and end timestamps
• Job status (running, success, or failed)
• Logs (if capture_logs=True)
• Error traceback (if any)

💓 Heartbeat Monitoring

Send regular heartbeats from long-running processes to confirm they’re still active.

seer.heartbeat("worker_process", metadata={"pid": 1234, "status": "active"})

This helps detect downtime or stalled jobs in real time.

⚙️ Error Handling & Offline Support

If the Seer API is temporarily unavailable, payloads are safely stored locally using helpers like payloads.save_failed_payload. You can later replay them manually:

from payloads import replay_failed_payloads

replay_failed_payloads()

🔐 Using Environment Variables (Recommended)

Store your API key in an environment variable for safer usage in production.

Create a .env file:

SEER_API_KEY=your_api_key_here

Load it in your code:

from dotenv import load_dotenv
import os
from seerpy import Seer

load_dotenv()
api_key = os.getenv("SEER_API_KEY")
seer = Seer(apiKey=api_key)

🧩 API Reference

Method	Description
Seer(apiKey)	Initialize a new Seer client
monitor(job_name, capture_logs=False, metadata=None)	Context manager to monitor a code block
heartbeat(job_name, metadata=None)	Send a heartbeat signal for an ongoing job

📦 Example: Full Worker Script

from dotenv import load_dotenv
import os
from seerpy import Seer

load_dotenv()
seer = Seer(apiKey=os.getenv("SEER_API_KEY"))

def run_job():
    with seer.monitor("example_worker", capture_logs=True, metadata={"env": "prod"}):
        print("Starting work...")
        # simulate work
        for i in range(3):
            print(f"step {i+1}")
        # optionally send heartbeat during long tasks
        seer.heartbeat("example_worker", metadata={"progress": "50%"})
        print("Work complete.")

if __name__ == "__main__":
    run_job()

🛡️ License

Copyright (c) 2025 Ansr Studio.
All rights reserved. Use of this software is permitted solely for connecting to and interacting with the Seer API. Redistribution, modification, or any other use of this code is prohibited without written permission from Ansr Studio. See the LICENSE file for details.

🧠 About

Seer is a monitoring and observability platform built by Ansr Studio. It helps data engineers and developers track, analyze, and debug their workflows effortlessly.

Learn more at: https://ansrstudio.com