SDK v0.6.1

Teracron Python SDK

Memory monitoring, distributed tracing, and event tracking for Python applications — encrypted end-to-end with RSA-4096 + AES-256-GCM.

Installation

bash
pip install teracron-sdk

Requires Python ≥ 3.9. Dependencies: psutil, cryptography, requests.

Quick Start

1. Copy your API key from the dashboard → Project Settings → SDK Setup.

bash
export TERACRON_API_KEY="tcn_..."

2. One line in your app:

python
import teracron
teracron.up()

Metrics flow in a background daemon thread. Shutdown is automatic via atexit.

Workflow Tracing

Decorate functions with @trace to capture spans with timing, status, and error details. Nested calls build parent-child span trees automatically.

python
from teracron import trace

@trace("payment")
def create_order(cart):
    ...

@trace("payment")
async def charge_card(order_id, amount):
    ...

@trace("payment")
def process_payment(cart):
    order = create_order(cart)          # child span
    charge_card(order.id, cart.total)   # child span

Exceptions are captured (error_type, error_message) but never swallowed — they always re-raise.

Parameter Capture (Opt-In)

By default, no parameter values are sent. Whitelist specific params explicitly:

python
@trace("payment", capture=["order_id", "amount"])
def charge_card(order_id, amount, card_number):
    # order_id and amount captured — card_number is NOT
    ...

Context Manager

python
from teracron import trace_context, async_trace_context

with trace_context("payment", operation="validate") as span:
    span.set_metadata({"order_id": "ORD-123"})
    validate_order(order)

async with async_trace_context("payment", operation="verify") as span:
    span.set_metadata({"txn_id": "T-001"})
    await verify_payment(txn)

Cross-Process Propagation

python
from teracron import get_trace_header, set_trace_header

# Service A — outbound request
headers["X-Teracron-Trace"] = get_trace_header()

# Service B — inbound request
set_trace_header(request.headers.get("X-Teracron-Trace"))

Sampling

python
teracron.up(trace_sample_rate=0.1)  # Record 10% of traces

Deterministic per trace_id. Non-sampled functions execute normally — only telemetry recording is skipped.

PII Scrubber

python
def my_scrubber(data: dict) -> dict:
    data.pop("email", None)
    data.pop("ssn", None)
    return data

teracron.up(tracing_scrubber=my_scrubber)

Receives a shallow copy — your original data is never mutated. If the scrubber raises, data is dropped entirely (never leaked).

Framework Middleware

FastAPI / Starlette

python
from fastapi import FastAPI
from teracron.tracing.middleware.fastapi import TeracronTracingMiddleware

app = FastAPI()
app.add_middleware(TeracronTracingMiddleware, workflow="api")

Django

python
# settings.py
MIDDLEWARE = [
    "teracron.tracing.middleware.django.TeracronTracingMiddleware",
    # ...
]
TERACRON_WORKFLOW = "api"  # optional, default: "http"

Celery

python
from celery import Celery
from teracron.tracing.middleware.celery import setup_celery_tracing

app = Celery("tasks")
setup_celery_tracing(app, workflow="tasks")

Standalone Agent (Sidecar)

bash
export TERACRON_API_KEY="tcn_..."
export TERACRON_TARGET_PID=$(pgrep -f "gunicorn")
teracron-agent

Configuration

ParameterEnv VariableDefaultDescription
api_keyTERACRON_API_KEYrequiredAPI key from dashboard
domainTERACRON_DOMAINwww.teracron.comIngest endpoint domain
interval_sTERACRON_INTERVAL10Collection interval (5–300s)
max_buffer_sizeTERACRON_MAX_BUFFER10Snapshots before flush
flush_deadline_sTERACRON_FLUSH_DEADLINE60Max seconds before forced flush
timeout_sTERACRON_TIMEOUT10HTTP timeout (2–30s)
debugTERACRON_DEBUGfalseDebug logging to stderr
target_pidTERACRON_TARGET_PIDselfPID of process to monitor
tracing_enabledTERACRON_TRACING_ENABLEDtrueMaster tracing switch
trace_batch_sizeTERACRON_TRACE_BATCH_SIZE100Spans before flush (1–10000)
trace_flush_intervalTERACRON_TRACE_FLUSH_INTERVAL10Trace flush interval (1–300s)
trace_sample_rateTERACRON_TRACE_SAMPLE_RATE1.0Sampling rate (0.0–1.0)
tracing_scrubber—NonePII scrubber callable
python
teracron.up(
    tracing_enabled=True,
    trace_batch_size=50,
    trace_flush_interval=5.0,
    trace_sample_rate=0.5,
    tracing_scrubber=my_scrubber,
)

API Reference

teracron.up(**kwargs) → TeracronClient

Start telemetry. Reads TERACRON_API_KEY from env. Idempotent — calling again returns the same instance.

teracron.down()

Stop the agent. Performs a final flush. Safe to call even if up() was never called.

TeracronClient (advanced)

python
from teracron import TeracronClient

client = TeracronClient(api_key=os.environ["TERACRON_API_KEY"])
client.start()
# ...
client.stop()

Security

  • •RSA-4096 OAEP + AES-256-GCM hybrid envelope encryption
  • •API key contains only the public key — no secrets
  • •Ephemeral AES key + IV per flush — no key reuse
  • •AES key material zeroed after encryption
  • •All traffic over HTTPS (TLS 1.2+)
  • •SDK never logs PII, keys, or metric payloads
  • •Parameter capture is opt-in only
  • •PII scrubber runs before data enters the buffer