Python SDK for the Bronto observability platform.
pip install bronto-sdk
# or
uv add bronto-sdkRequires Python 3.11 or newer. The only runtime dependencies are httpx,
pydantic and typing_extensions.
The langchain extra is declared but carries no code yet — the name is
reserved so adding it later is not a breaking rename. The mcp extra installs
what bronto_sdk.mcp needs:
pip install "bronto-sdk[mcp]"PyPI uploads carry provenance attestations, and every release is also attached, with Sigstore signatures, to a GitHub Release. SECURITY.md covers verifying either.
from bronto_sdk import BrontoClient
from bronto_sdk.models import SearchRequest
with BrontoClient(api_key="...", region="eu") as client:
response = client.search.run(
SearchRequest(
select=["*", "@raw"],
from_=["my-collection.my-dataset"],
time_range="last 30 minutes",
limit=50,
)
)
for event in response.events or []:
print(event.time, event.raw)BrontoClient.from_env() builds the same client from BRONTO_API_KEY plus
either BRONTO_REGION or BRONTO_BASE_URL.
AsyncBrontoClient is a mirror of BrontoClient: identical method names,
async def bodies. There is no _async suffix to remember.
import asyncio
from bronto_sdk import AsyncBrontoClient
from bronto_sdk.models import SearchRequest
async def main() -> None:
async with AsyncBrontoClient(api_key="...", region="eu") as client:
response = await client.search.run(
SearchRequest(select=["count(*)"], from_expr="*", time_range="last 1 hour")
)
print(response.totals)
asyncio.run(main())The async client also takes max_concurrency (default 20), an
asyncio.Semaphore bounding in-flight requests so a fan-out cannot stampede
the API gateway.
| Call | HTTP | Returns |
|---|---|---|
client.search.run(request) |
POST /search |
SearchResponse |
client.monitors.list() |
GET /monitors |
MonitorsResponse |
client.monitors.retrieve(monitor_id) |
GET /monitors/{id} |
Monitor |
client.monitors.events(monitor_id, from_ts=…, to_ts=…) |
GET /monitors/{id}/events |
MonitorEventsResponse |
client.datasets.list(from_=…, from_expr=…) |
GET /datasets |
DatasetsResponse |
client.metrics.retrieve_definition(metric_id) |
GET /metrics/definitions/{id} |
MetricDefinition |
search.run() accepts a SearchRequest or a plain dict, validated on the
way in. Path parameters are URL-quoted.
Response models set extra="allow", so a new server-side field is additive
rather than breaking — it stays reachable through model_extra.
Typed coverage is narrow on purpose, and a missing endpoint must never block you on an SDK release:
usage = client.get("/limits", params={"period": "month"})
result = client.post("/analytics/errors", json={"from_ts": 0, "to_ts": 1})Both return the parsed JSON object as a dict and go through the same auth,
error mapping and timeout handling as the typed methods. Path joining accepts
"/search" and "monitors/m-1" alike — exactly one separating slash either way.
This is the subtlest part of the SDK and the one worth reading before you build a service on it. A client is one of two modes, fixed at construction:
Client-bound — built with api_key or bearer_token. Every call uses it.
Passing a per-request credential raises BrontoConfigError: the SDK will not
guess which of two credentials you meant.
client = BrontoClient(api_key="...", region="eu")
client.datasets.list() # uses the bound keyPer-request — built with neither. The client holds no credential, and every call must supply one:
client = BrontoClient(region="eu") # holds no credential
client.datasets.list(options={"bearer_token": tenant_jwt})There is no fallback between the modes, and a supplied-but-empty per-request credential fails closed. That is what makes a long-lived multi-tenant client safe by construction: there is no ambient credential on the client, so there is nothing to leak between tenants.
Within a single origin — one construction, or one request — bearer_token wins
over api_key. A bearer credential is sent verbatim as Authorization; an API
key as X-BRONTO-API-KEY.
A static-key fallback ("use the config key when the request carries none") is deliberately not in the SDK. A multi-tenant consumer owns that policy in its own credential adapter, where it can be reviewed.
BrontoError
├── BrontoConfigError bad or missing configuration, unknown region, mode violation
├── BrontoConnectionError an httpx transport failure (DNS, TLS, timeout)
└── BrontoAPIError any non-2xx response
├── BrontoBadRequestError 400
├── BrontoAuthenticationError 401
├── BrontoPermissionError 403
├── BrontoNotFoundError 404
├── BrontoRateLimitError 429 (adds retry_after)
└── BrontoServerError 5xx
Every status-specific class subclasses BrontoAPIError, so a broad
except BrontoAPIError keeps working as you narrow your handlers.
BrontoAPIError carries status_code, correlation_id, details,
error_type, body and headers. str() always shows the status and the
correlation id when present — it is the single most useful field when raising a
support ticket, so it is never buried.
from bronto_sdk import BrontoAPIError, BrontoNotFoundError
try:
monitor = client.monitors.retrieve("m-1")
except BrontoNotFoundError:
monitor = None
except BrontoAPIError as exc:
if exc.retryable: # True for 429 and 5xx
...
raiseretryable exists so you can write correct retry logic today; the SDK itself
does not retry in v0.1.
No credential ever reaches an error, a repr() or a log line. Response
headers attached to an error are redacted by key name, and the stored body is
bounded so a large error page cannot bloat a log line.
from bronto_sdk import KNOWN_REGIONS, ingest_base_url, rest_base_url, validate_region
rest_base_url("eu") # https://api.eu.bronto.io
ingest_base_url("eu") # https://ingestion.eu.bronto.ioKNOWN_REGIONS is ("eu", "us") and is a hint for error messages only, never
an allow-list. A new region (us-2, …) or a staging deployment must work
without an SDK release.
validate_region is a security control, not tidiness. The region is
interpolated into https://api.{region}.bronto.io, so a value containing /,
@, ., : or whitespace moves the host off bronto.io entirely —
region="evil.com/" would yield host api.evil.com and send your credential
there. Only the slug pattern ^[a-z0-9][a-z0-9-]*$ is accepted.
base_url is exempt from that validation by design — it is a full URL and
only ever comes from a trusted source (your own constructor argument or
BRONTO_BASE_URL). It wins over region. Passing an untrusted base_url means
passing an untrusted host, deliberately.
Redirects are not followed, and that is a security invariant rather than a
default nobody changed: the API key rides in a custom header, which HTTP
clients do not strip on a cross-domain redirect the way they strip
Authorization. Turning redirect-following on would hand the key to whatever
host a redirect names.
RequestOptions overrides client configuration for a single call. Absent keys
fall back to the client default; present ones win.
| Key | Effect |
|---|---|
timeout |
Per-request timeout in seconds (client default: 30.0) |
headers |
Extra headers, merged over the SDK's, per-request winning |
api_key |
API key for this call — per-request mode only |
bearer_token |
Bearer token for this call — per-request mode only |
idempotent |
Reserved. Inert in v0.1; v0.2's retry logic reads it |
client.search.run(request, options={"timeout": 120.0, "headers": {"X-Trace": tid}})headers is applied last and is not a credential channel: values there go
out verbatim, so putting an auth header in it bypasses the credential resolver
on purpose.
bronto_sdk.domain is pure Bronto knowledge — no I/O, no client needed.
from bronto_sdk.domain import iso_to_ms, ms_to_iso, parse_time_range, parse_window
iso_to_ms("2026-09-16T10:00:00Z") # 1789552800000
parse_time_range("last 30 minutes") # (from_ms, to_ms) absolute bounds
parse_window("2 hours ago") # 7200000 — the duration projectionparse_time_range mirrors the server-side reference implementation, so the SDK
and the query engine agree on what a phrase means. It handles calendar phrases
(today, yesterday, this week, previous quarter, this quarter last year, …) as well as the last N <unit> and N <unit> [ago] forms, with digit
or spelled-out counts. Pass ref= to pin "now" in a test. It raises
ValueError on input it cannot parse — never a silent wrong answer.
ms_to_iso uses integer arithmetic throughout, so sub-second precision and
large epoch-millisecond values survive intact.
from bronto_sdk.domain import quote_attribute, quote_value, wildcard_pattern
quote_value("O'Brien") # 'O''Brien' — a string literal
quote_attribute('a"b') # "a""b" — an attribute referenceThe SDK never auto-escapes. Nothing in the client or the resource layer rewrites a where clause you supply — the contract is that you pass valid, already-escaped query text. These helpers exist so that when you embed an untrusted value (model output, user input) you escape it explicitly at the call site, where a reviewer can see it:
where = f"level='error' AND service={quote_value(untrusted_name)}"Escaping is SQL-style and per quote character: single quotes wrap a string
literal and an embedded ' doubles; double quotes wrap an attribute reference
and an embedded " doubles. Backslash escaping is not supported by the query
engine — a \ is an ordinary character and is left untouched.
from bronto_sdk.domain import project_dataset
project_dataset(raw) # -> {"log_id": ..., "name": ..., "collection": ...}Reads both live shapes: the REST API returns id and dataset, the MCP tools
return log_id and name. They are genuinely different — do not assume one.
v0.1 ships the endpoint knowledge only, so consumers stop hardcoding the host.
There is no session opener yet (that is v0.2, behind the [mcp] extra) and
no mcp or langchain import anywhere in the package.
from bronto_sdk import mcp
mcp.url("eu") # https://mcp.eu.bronto.io/mcp
mcp.url(base_url="https://mcp.eu.staging.bronto.io") # …staging.bronto.io/mcp
mcp.auth_headers(api_key="...") # {"X-BRONTO-API-KEY": "..."}
mcp.auth_headers(bearer_token="...") # {"Authorization": "..."}url() follows the same region / base_url precedence as the clients, so
both answer the same input identically. auth_headers() reuses the clients'
credential resolution rather than restating it: bearer wins, and it fails closed
rather than ever returning an unauthenticated dict.
The header dict is meant to go onto the httpx client the MCP transport is
built on, which is how the streamable-HTTP client takes headers.
uv sync # create .venv and install dev dependencies
just prepare # format, lint, typecheck, spec digest gate, testsjust prepare must be green before every commit. Run just --list to see
every recipe, and see CONTRIBUTING.md for the full setup.
Runnable versions of everything above live in examples/.
MIT — see LICENSE.