Basic Initialization
Initialize the SDK early in your application startup (before any requests are handled):
import proliferate
proliferate.init(
endpoint="https://api.proliferate.com/api/v1/errors",
api_key="pk_your_project_key",
)
The SDK automatically detects environment and release from environment variables and Git. See Auto-Detection below. Configuration Options
Required Parameters
The API endpoint URL for error ingestion. Typically https://api.proliferate.com/api/v1/errors
Your project API key. Get this from your Proliferate dashboard under Project Settings > API Keys.Format: pk_{project_slug}_{random_hex}
Optional Parameters
environment
str
default:"auto-detected"
The environment name (e.g., "production", "staging", "development").If not provided, the SDK checks these environment variables in order:
PROLIFERATE_ENVIRONMENTENVIRONMENTENVPYTHON_ENVAPP_ENV
Defaults to "production" if none are found. release
str
default:"auto-detected"
The release version or commit SHA. Used for:
- Grouping errors by release
- Source map resolution
- Release-based filtering in the dashboard
If not provided, the SDK auto-detects from environment variables and Git. Whether to actually send errors to Proliferate.Set to False for local development or testing to prevent test errors from appearing in production.import os
proliferate.init(
endpoint="https://api.proliferate.com/api/v1/errors",
api_key="pk_your_project_key",
enabled=os.getenv("ENVIRONMENT") == "production",
)
Auto-Detection
Release Auto-Detection
The SDK automatically detects the release version from these sources (in order):
Environment Variables
Checks common CI/CD environment variables:
PROLIFERATE_RELEASE (highest priority)RELEASE_VERSION (Docker convention)GITHUB_SHA (GitHub Actions)VERCEL_GIT_COMMIT_SHA (Vercel)CF_PAGES_COMMIT_SHA (Cloudflare Pages)RENDER_GIT_COMMIT (Render)RAILWAY_GIT_COMMIT_SHA (Railway)HEROKU_SLUG_COMMIT (Heroku)GITLAB_CI_COMMIT_SHA (GitLab CI)CIRCLE_SHA1 (CircleCI)GIT_COMMIT (Generic)COMMIT_SHA (Generic)
Git Command
If no environment variable is found, runs git rev-parse HEAD to get the current commit SHA.This typically fails in Docker containers (where .git is not copied). Set the release via environment variable in production.
Fallback
If all detection methods fail, release is set to None.
Environment Auto-Detection
The SDK checks these environment variables (in order):
PROLIFERATE_ENVIRONMENTENVIRONMENTENVPYTHON_ENVAPP_ENV
If none are set, defaults to "production".
Complete Example
import os
import proliferate
# Explicit configuration
proliferate.init(
endpoint="https://api.proliferate.com/api/v1/errors",
api_key=os.getenv("PROLIFERATE_API_KEY"),
environment="staging",
release="v2.1.0",
enabled=True,
)
# Auto-detection (recommended for most cases)
proliferate.init(
endpoint="https://api.proliferate.com/api/v1/errors",
api_key=os.getenv("PROLIFERATE_API_KEY"),
# environment and release auto-detected
)
FastAPI Example
from fastapi import FastAPI
import proliferate
from proliferate.integrations.fastapi import ProliferateMiddleware
# Initialize SDK before creating the app
proliferate.init(
endpoint="https://api.proliferate.com/api/v1/errors",
api_key="pk_your_project_key",
)
app = FastAPI()
# Add middleware to capture unhandled exceptions
app.add_middleware(ProliferateMiddleware)
@app.get("/")
async def root():
return {"message": "Hello World"}
Flask Example
from flask import Flask
import proliferate
from proliferate.integrations.flask import init_app
# Initialize SDK
proliferate.init(
endpoint="https://api.proliferate.com/api/v1/errors",
api_key="pk_your_project_key",
)
app = Flask(__name__)
# Initialize Flask integration
init_app(app)
@app.route("/")
def root():
return {"message": "Hello World"}
Environment Variables
Recommended environment variable setup:
# Required
PROLIFERATE_API_KEY=pk_your_project_key
# Optional (auto-detected if not set)
PROLIFERATE_ENVIRONMENT=production
PROLIFERATE_RELEASE=v2.1.0
# Or use standard environment variables
ENVIRONMENT=production
RELEASE_VERSION=v2.1.0
Checking Configuration
You can check if the SDK is initialized and view the detected configuration:
import proliferate
# Check initialization status
if proliferate.is_initialized:
print(f"Environment: {proliferate.environment}")
print(f"Release: {proliferate.release}")
else:
print("SDK not initialized")
Next Steps
