← Back to Dashboard

Overcast SDK

Simple monitoring and incident management for startups

The Overcast SDK provides an easy way to add monitoring, logging, and incident management to your application without complex infrastructure setup. Perfect for startups that need observability but don't have dedicated DevOps teams or complex logging infrastructure.

Table of Contents

Features

✅ Simple Integration

Just 3 lines of code to get started

✅ Self-Contained

Uses SQLite database, no external dependencies

✅ Real-time Dashboard

Web UI for monitoring incidents and metrics

✅ CLI Tools

Command-line interface for incident management

✅ Smart Correlation

Automatic incident detection and correlation

✅ Lightweight

Minimal performance impact on your application

Quick Start

1. Installation

pip install -r requirements.txt

2. Basic Usage

import overcast

# Initialize the SDK
overcast.init(
    api_key="your-api-key-here", 
    customer_name="Your Startup"
)

# Log events
overcast.log("User login successful", level="INFO", service="auth")

# Record metrics
overcast.metric("response_time", 0.23, tags={"endpoint": "/api/users"})

# Send alerts
overcast.alert("Database connection failed", severity="high", service="db")

# Shutdown when done
overcast.shutdown()

3. Context Manager (Recommended)

import overcast

with overcast.OvercastContext(api_key="your-key", customer_name="Your Startup"):
    overcast.log("Application started", service="web-app")
    overcast.metric("startup_time", 1.2, service="web-app")
    
    # Your business logic here
    do_business_logic()
    
    # Overcast automatically shuts down when exiting context

Dashboard & CLI

Web Dashboard

Start the dashboard to monitor your incidents in real-time:

python -m sdk.server --api-key your-key --customer-name "Your Startup"

Visit http://localhost:5000 to see:

Command Line Interface

Use the CLI for incident management:

# Start interactive CLI
python -m sdk.server --api-key your-key --cli-only

# Available commands:
overcast list          # Show recent incidents
overcast triage        # Auto-triage incidents 
overcast logs [service] # Show recent logs
overcast metrics [service] # Show recent metrics
overcast status        # System status

API Reference

overcast.init(api_key, customer_name, server_url)

Initialize the Overcast SDK.

api_key (str): Your Overcast API key
customer_name (str): Your organization name
server_url (str, optional): Server URL (default: localhost)

overcast.log(message, level, service, **kwargs)

Log a message with context.

message (str): Log message
level (str): Log level (DEBUG, INFO, WARN, ERROR, CRITICAL)
service (str): Service name (default: "default")
**kwargs: Additional metadata

overcast.metric(name, value, tags, service)

Record a metric value.

name (str): Metric name
value (float): Metric value
tags (dict, optional): Key-value tags
service (str): Service name (default: "default")

overcast.alert(message, severity, service, **kwargs)

Send an alert for immediate attention.

message (str): Alert message
severity (str): Alert severity (low, medium, high, critical)
service (str): Service name (default: "default")
**kwargs: Additional metadata

overcast.shutdown()

Shutdown the SDK and clean up resources.

Integration Examples

Web Application (Flask/Django)

from flask import Flask
import overcast

app = Flask(__name__)

# Initialize Overcast
overcast.init(api_key="your-key", customer_name="Your Web App")

@app.route('/api/users')
def get_users():
    start_time = time.time()
    
    try:
        overcast.log("Fetching users", level="INFO", service="web-api")
        
        # Your business logic
        users = fetch_users_from_db()
        
        # Record response time
        response_time = time.time() - start_time
        overcast.metric("response_time", response_time, 
                       tags={"endpoint": "/api/users"})
        
        return jsonify(users)
        
    except Exception as e:
        overcast.log(f"Failed to fetch users: {e}", level="ERROR", service="web-api")
        overcast.alert(f"API error: {e}", severity="high", service="web-api")
        return jsonify({"error": "Internal server error"}), 500

# Shutdown on app teardown
@app.teardown_appcontext
def shutdown_overcast(error):
    overcast.shutdown()

Background Jobs

import overcast

def process_user_data(user_id):
    with overcast.OvercastContext(api_key="your-key", customer_name="Background Jobs"):
        try:
            overcast.log(f"Processing user {user_id}", service="background-worker")
            
            # Process data
            result = expensive_data_processing(user_id)
            
            # Record success
            overcast.metric("job_success", 1, tags={"user_id": user_id})
            overcast.log(f"User {user_id} processed successfully", service="background-worker")
            
            return result
            
        except Exception as e:
            overcast.log(f"Failed to process user {user_id}: {e}", 
                        level="ERROR", service="background-worker")
            overcast.alert(f"Background job failed: {e}", 
                          severity="medium", service="background-worker")
            raise

Configuration

Environment Variables

You can use environment variables instead of hardcoding configuration:

export OVERCAST_API_KEY="your-api-key"
export OVERCAST_CUSTOMER_NAME="Your Startup"
export OVERCAST_DB_PATH="./data/overcast.db"
export OVERCAST_DASHBOARD_PORT="5000"
from sdk.core.config import OvercastConfig

# Load from environment
config = OvercastConfig.from_env()

Best Practices

1. Service Organization

Organize your logging by service/component:

Good: Organized by service
overcast.log("User authenticated", service="auth")
overcast.log("Order processed", service="orders") 
overcast.log("Payment completed", service="payments")
Avoid: Everything in default service
overcast.log("Something happened")  # service="default"

2. Meaningful Metrics

Use descriptive metric names and relevant tags:

Good: Descriptive with context
overcast.metric("http_request_duration", 0.25, 
               tags={"method": "POST", "endpoint": "/api/orders", "status": "200"})
Avoid: Generic metrics without context
overcast.metric("duration", 0.25)

3. Appropriate Alert Levels

Troubleshooting

Common Issues

Q: SDK not capturing logs/metrics

Q: Dashboard not accessible

Q: High memory usage

Q: Performance impact

Debug Mode

Enable debug logging to troubleshoot issues:

from sdk.core.config import OvercastConfig

config = OvercastConfig(
    api_key="your-key",
    customer_name="Your Startup",
    log_level="DEBUG"  # Enable debug logging
)
Ready to get started? Check out example_usage.py for a complete working example!