Documentation

SDK Reference

Add monitoring to any Python or JavaScript script in under 2 minutes. No infrastructure changes.

Quickstart

Install the package, add two lines to your script, and run it. Your execution appears in the dashboard automatically.

terminal

pip install echologs

your_script.py

import echologs

with echologs.run():
    # your existing code — nothing changes
    print("Hello from EchoLogs!")

Set ECHOLOGS_API_KEY in your terminal before running. Get your key from the API Keys page →

Installation

Requires Python 3.8 or above.

pip

pip install echologs

No other packages required. The SDK reads ECHOLOGS_API_KEY from os.environ automatically. See the Environment variables section for how to set it safely.

Initialise

The SDK auto-initialises when it finds ECHOLOGS_API_KEY in your environment. You never need to call init() manually.

auto init — recommended

import echologs
# SDK reads ECHOLOGS_API_KEY from os.environ automatically

explicit init — optional

import echologs

echologs.init("el_your_api_key")

Context manager

The recommended pattern. Wrap your code and EchoLogs automatically captures timing, stdout, stderr, and errors.

python

import echologs

with echologs.run():
    print("Starting...")
    result = do_work()
    print("Done.")

Override the auto-detected name:

python

with echologs.run(name="invoice-puller"):
    ...

Decorator / wrapper

If your script is already in a function, use the decorator pattern instead.

python

import echologs

@echologs.monitor(name="invoice-puller")
def run():
    print("Running...")
    # your code here

run()

Environment variables

Never hardcode your API key. Always set it as an environment variable — the SDK reads it automatically.

Production

Set it in your platform's environment settings. The SDK picks it up automatically — no code changes needed.

github actions

env:
  ECHOLOGS_API_KEY: ${{ secrets.ECHOLOGS_API_KEY }}

Local — Option A: export in terminal (safest)

Set the variable once per terminal session. Nothing goes in any file that could be committed.

terminal

# Set once per terminal session — never touches your code
export ECHOLOGS_API_KEY=el_your_api_key_here   # mac / linux
set    ECHOLOGS_API_KEY=el_your_api_key_here   # windows

python your_script.py

Local — Option B: .env file with python-dotenv

Convenient if you have many env vars. Install python-dotenv once, create a .env file, and load it at the top of your script.

pip — one time

pip install python-dotenv

.env — never commit this file

ECHOLOGS_API_KEY=el_your_api_key_here

your_script.py

from dotenv import load_dotenv
load_dotenv()  # loads .env file into os.environ
import echologs

with echologs.run():
    print("Running...")

Always add .env to your .gitignore. Your API key must never be committed to version control or hardcoded in your source code.

Error handling

If your code throws, EchoLogs marks the execution as failed, captures the full stack trace, and re-raises so your existing error handling still works.

python

with echologs.run():
    # raises → marked FAIL, traceback captured, alerts sent, re-raised
    result = call_openai_api()
    process(result)

Slack alerts require Pro or Team. Email alerts are available on all plans. Configure at app.echologs.com/scripts →

Script naming

EchoLogs auto-detects the script name from your filename. You can rename the display name in the dashboard anytime without touching your code.

SDK name (permanent)

invoice_puller

Auto-detected or set via name=

Display name (editable)

Invoice Puller

Change anytime in dashboard

If you change the name in your code, EchoLogs creates a new script entry. Use the same name consistently across all runs.

Examples

OpenAI summariser

python

from openai import OpenAI
import echologs

client = OpenAI()

with echologs.run(name="openai-summariser"):
    articles = fetch_articles()
    for article in articles:
        response = client.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": article["body"]}]
        )
        save_summary(article["id"], response.choices[0].message.content)
    print("Done.")

Database cleanup

python

import psycopg2, os, echologs

with echologs.run(name="db-cleanup"):
    conn = psycopg2.connect(os.environ["DATABASE_URL"])
    cur  = conn.cursor()
    cur.execute("DELETE FROM logs WHERE created_at < NOW() - INTERVAL '90 days'")
    conn.commit()
    print("Done.")
    cur.close(); conn.close()

APScheduler cron

python

from apscheduler.schedulers.blocking import BlockingScheduler
import echologs

scheduler = BlockingScheduler()

@scheduler.scheduled_job('cron', hour=9, minute=0)
def run():
    with echologs.run(name="daily-digest"):
        send_digest()
        print("Done.")

scheduler.start()