Python SDK Reference

Installation

pip install stacklens

Requires Python 3.9+. The only dependency is httpx.

Configuration

import stacklens
 
stacklens.configure(api_key="sl-xxxx")
 
# For self-hosted deployments:
stacklens.configure(api_key="sl-xxxx", endpoint="https://api.your-domain.com")

Get your API key from the dashboard under Settings → API Keys.

`stacklens.configure(api_key, endpoint?)`

Initialises the SDK. Call once at application startup.

Parameter	Type	Default	Description
`api_key`	`str`	required	Your StackLens API key (`sl-...`)
`endpoint`	`str`	`https://api.getstacklens.ai`	API base URL (override for self-hosted)

`stacklens.trace(name, *, model, provider, input_tokens, output_tokens, ...)`

Record a single LLM span. Returns the trace ID string.

Parameter	Type	Default	Description
`name`	`str`	required	Operation name shown in the dashboard
`model`	`str`	required	Model identifier (e.g. `"gpt-4o"`)
`provider`	`str`	required	Provider name (e.g. `"openai"`)
`input_tokens`	`int`	required	Number of input/prompt tokens
`output_tokens`	`int`	required	Number of output/completion tokens
`total_tokens`	`int`	computed	Defaults to `input_tokens + output_tokens`
`cost_usd`	`float`	`0.0`	Estimated cost in USD
`attributes`	`dict[str, str]`	`{}`	Key-value metadata attached to the span
`tags`	`list[str]`	`[]`	String tags for dashboard filtering
`status`	`str`	`"ok"`	`"ok"` or `"error"`

trace_id = stacklens.trace(
    "document-summary",
    model="gpt-4o",
    provider="openai",
    input_tokens=850,
    output_tokens=120,
    cost_usd=0.0012,
    attributes={"document_id": "doc_abc123"},
    tags=["summarisation", "production"],
)

`stacklens.start_trace(name)` — context manager

Trace a multi-step operation. Yields a Span object. Flushes to StackLens on exit.

with stacklens.start_trace("agent-run") as span:
    # ... do your work ...
    span.record_llm(model="gpt-4o", provider="openai",
                    input_tokens=200, output_tokens=150)

If an exception is raised inside the block, the span status is set to "error" automatically.

`Span` — methods

`span.record_llm(...)`

Attach LLM metadata to this span.

Parameter	Type	Default	Description
`model`	`str`	required	Model identifier
`provider`	`str`	required	Provider name
`input_tokens`	`int`	required	Input token count
`output_tokens`	`int`	required	Output token count
`total_tokens`	`int`	computed	Defaults to `input + output`
`cost_usd`	`float`	`0.0`	Estimated cost in USD
`temperature`	`float`	`None`	Sampling temperature
`max_tokens`	`int`	`None`	Max tokens setting
`prompt`	`str`	`None`	Prompt content (stored encrypted at rest)
`completion`	`str`	`None`	Completion content
`is_streaming`	`bool`	`False`	Whether the response was streamed
`finish_reason`	`str`	`None`	Model's finish reason

`span.set_attribute(key, value)`

Attach a string key-value pair to the span.

span.set_attribute("user_id", "u_123")
span.set_attribute("session_id", "sess_abc")

`span.add_tag(*tags)`

Add one or more tags.

span.add_tag("production", "rag-pipeline")

`span.set_status(status)`

Set span status to "ok" or "error". (Automatically set to "error" on exception.)

`stacklens.prompts.get(name, *, env?)`

Fetch the active prompt for a given name and environment.

Parameter	Type	Default	Description
`name`	`str`	required	Prompt name as configured in FlowOps
`env`	`str`	`"production"`	`"dev"`, `"staging"`, or `"production"`

Returns the prompt content as a str.

system_prompt = stacklens.prompts.get("support-system-prompt")
dev_prompt = stacklens.prompts.get("onboarding-email", env="dev")

Exceptions

Exception	When raised
`stacklens.ConfigurationError`	`configure()` was not called before tracing
`stacklens.AuthError`	API key is invalid or missing the required scope
`stacklens.ApiError`	The StackLens API returned an error (has `.status_code`)
`stacklens.StackLensError`	Base class for all SDK exceptions

try:
    stacklens.trace("my-call", model="gpt-4o", provider="openai",
                    input_tokens=100, output_tokens=50)
except stacklens.AuthError:
    print("Check your API key")
except stacklens.ApiError as e:
    print(f"API error {e.status_code}")

Python SDK Reference

Installation

Configuration

stacklens.configure(api_key, endpoint?)

stacklens.trace(name, *, model, provider, input_tokens, output_tokens, ...)

stacklens.start_trace(name) — context manager

Span — methods

span.record_llm(...)

span.set_attribute(key, value)

span.add_tag(*tags)

span.set_status(status)

stacklens.prompts.get(name, *, env?)