Skip to content

SDK Initialization

Jump to bottom
Niccanor Dhas edited this page Feb 22, 2026 · 1 revision

SDK Initialization

The init() function is the entry point for the tmam Python SDK. Call it once at startup before any LLM or agent code runs.

Installation

pip install tmam

Basic Usage

from tmam import init

init(
    url="http://localhost:5050/api/sdk",
    public_key="pk-tmam-xxxxxxxx",
    secrect_key="sk-tmam-xxxxxxxx",
    application_name="my-app",
    environment="production",
)

Full Parameter Reference

from tmam import init

init(
    # ── Connection ────────────────────────────────────────
    url=None,               # str: OTLP endpoint. Env: TMAM_URL
    public_key=None,        # str: SDK public key. Env: TMAM_PUBLIC_KEY
    secrect_key=None,       # str: SDK secret key. Env: TMAM_SECRET_KEY

    # ── Identity ──────────────────────────────────────────
    application_name="default",  # str: name shown in dashboard filters
    environment="default",       # str: e.g. "production", "staging", "dev"

    # ── Tracing ───────────────────────────────────────────
    tracer=None,            # custom OpenTelemetry TracerProvider
    event_logger=None,      # custom EventLoggerProvider
    disable_batch=False,    # True = send spans synchronously (useful for scripts)
    capture_message_content=True,  # False = omit prompt/completion text from spans

    # ── Metrics ───────────────────────────────────────────
    meter=None,             # custom OpenTelemetry MeterProvider
    disable_metrics=False,  # True = disable all OTel metrics

    # ── GPU ───────────────────────────────────────────────
    collect_gpu_stats=False, # True = enable GPU utilization/memory metrics

    # ── Selective instrumentation ─────────────────────────
    disabled_instrumentors=[],  # list of provider names to skip
                                # e.g. ["openai", "langchain"]

    # ── Guardrails ────────────────────────────────────────
    guardrail_id=None,      # default guardrail ID for Detect calls

    # ── Pricing ───────────────────────────────────────────
    pricing_json=None,      # path or URL to a custom pricing JSON file
)

Using Environment Variables

All connection credentials can be set via environment variables instead of being passed to init():

export TMAM_URL="http://localhost:5050/api/sdk"
export TMAM_PUBLIC_KEY="pk-tmam-xxxxxxxx"
export TMAM_SECRET_KEY="sk-tmam-xxxxxxxx"
from tmam import init

# Reads credentials from environment automatically
init(application_name="my-app", environment="production")

Selective Instrumentation

By default, tmam instruments every supported library it detects in your environment. To skip specific providers:

init(
    url="...",
    public_key="...",
    secrect_key="...",
    disabled_instrumentors=["openai", "langchain", "chroma"],
)

Valid instrumentor names: openai, anthropic, cohere, mistral, bedrock, vertexai, groq, ollama, gpt4all, elevenlabs, vllm, google-ai-studio, azure-ai-inference, langchain, llama_index, haystack, embedchain, mem0, chroma, pinecone, qdrant, milvus, astra, transformers, litellm, together, crewai, ag2, multion, dynamiq, phidata, julep, ai21, controlflow, crawl4ai, firecrawl, letta, openai-agents, reka, premai, assemblyai, gpu

Privacy: Disabling Content Capture

If you do not want prompt text and completions stored in tmam (for compliance or privacy reasons):

init(
    url="...",
    public_key="...",
    secrect_key="...",
    capture_message_content=False,  # omit text, keep all metadata
)

Token counts, costs, latencies, model names, and all other metadata are still captured — only the text content of messages is excluded.

Batch vs. Synchronous Exporting

By default, spans are batched and exported in the background (disable_batch=False). For short-lived scripts where you need traces flushed before the process exits:

init(
    url="...",
    public_key="...",
    secrect_key="...",
    disable_batch=True,  # export each span immediately
)

Using a Custom OpenTelemetry Provider

If your application already has an OpenTelemetry setup, pass your own providers and tmam will export to both:

from opentelemetry.sdk.trace import TracerProvider
from tmam import init

my_tracer = TracerProvider()

init(
    url="...",
    public_key="...",
    secrect_key="...",
    tracer=my_tracer,
)

Framework-Specific Examples

FastAPI

from contextlib import asynccontextmanager
from fastapi import FastAPI
from tmam import init

@asynccontextmanager
async def lifespan(app: FastAPI):
    init(
        url="http://localhost:5050/api/sdk",
        public_key="pk-tmam-xxxxxxxx",
        secrect_key="sk-tmam-xxxxxxxx",
        application_name="my-fastapi-app",
    )
    yield

app = FastAPI(lifespan=lifespan)

Django

In manage.py or apps.py:

from tmam import init

init(
    url="http://localhost:5050/api/sdk",
    public_key="pk-tmam-xxxxxxxx",
    secrect_key="sk-tmam-xxxxxxxx",
    application_name="my-django-app",
)

Jupyter Notebook

from tmam import init

init(
    url="http://localhost:5050/api/sdk",
    public_key="pk-tmam-xxxxxxxx",
    secrect_key="sk-tmam-xxxxxxxx",
    application_name="notebook-experiment",
    disable_batch=True,  # flush immediately in interactive sessions
)

Clone this wiki locally