API Reference

Complete reference for the Observable Code Python SDK

observable.track()

Track a function or block of code. Can be used as a decorator or context manager.

Signature

observable.track(name: str) → _Tracker

Parameters

name (str) - A descriptive name for the tracked operation

Usage as Decorator

# Sync function
@observable.track("send_report")
def send_report():
    ...

# Async function
@observable.track("fetch_prices")
async def fetch_prices():
    ...

Usage as Context Manager

with observable.track("batch_import"):
    process_records()
    validate_data()
    # All code in this block is tracked

What Gets Captured

Status: completed or failed
Duration: Execution time in milliseconds
Error details: On exception, captures error type and message (exception is re-raised)
Metadata: Any data attached via trace()

observable.trace()

Attach a key-value pair to the next track() call in the current thread. Values are cleared after each tracked call.

Signature

observable.trace(key: str, value: Any) → None

Parameters

key (str) - The metadata key
value (Any) - The metadata value (will be JSON-serialized)

Example

observable.trace("records_processed", 500)
observable.trace("source", "s3://my-bucket")

@observable.track("nightly_sync")
def sync():
    ...
# Event metadata: {"records_processed": 500, "source": "s3://my-bucket"}

Note: Trace data is thread-local and cleared after each tracked function completes.

observable.event()

Manually post an event without wrapping a function. Keyword arguments become event metadata.

Signature

observable.event(name: str, status: str = "completed", **kwargs: Any) → None

Parameters

name (str) - Event name
status (str, optional) - Event status, defaults to "completed"
**kwargs - Any additional metadata as keyword arguments

Examples

# Success event with metadata
observable.event("payment_received", amount=99.99, currency="USD")

# Failed event
observable.event("webhook_failed", status="failed", endpoint="/stripe")

# Simple notification
observable.event("deployment_complete")

CLI Commands

Observable Code includes a command-line interface for setup and management.

observable setup

First-time pairing wizard. Creates a session, shows QR code, and waits for you to scan it.

observable setup

observable pair

Re-pair with a new phone or replace existing pairing.

observable pair

observable show-key

Print the current session ID from config file.

observable show-key

observable status

Check if the current session is paired and active.

observable status

Configuration

Credentials are resolved in this order:

Source	How to set
Environment variable	`export OBSERVABLE_CODE_SESSION_ID=<uuid>`
Config file	`observable setup` writes `~/.observable-code/config.json`

Custom API URL

The API URL defaults to http://localhost:3000 and can be overridden:

export OBSERVABLE_CODE_API_URL=https://your-deployment.vercel.app

Behavior

Fire-and-forget: Events are posted in a background daemon thread — your function's return is never delayed
Timeout: 2 seconds per HTTP request
Failures: Silently swallowed (a warning is printed to stderr)
Process exit: Never blocked by a pending post

Design principle: Observable Code never breaks your code. If credentials are missing or the API is unreachable, your functions continue running normally.