Skip to main content

bronto-sdk

CI PyPI OpenSSF Scorecard Python License: MIT

Python SDK for the Bronto observability platform.

Installation

pip install bronto-sdk
# or
uv add bronto-sdk

Requires 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.

Quickstart

Sync

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.

Async

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.

Typed operations

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.

Escape hatches

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.

Credentials: two modes

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 key

Per-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.

Errors

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
        ...
    raise

retryable 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.

Regions and base_url

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.io

KNOWN_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.

Per-request options

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.

Domain helpers

bronto_sdk.domain is pure Bronto knowledge — no I/O, no client needed.

Time ranges

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 projection

parse_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.

Query escaping

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 reference

The 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.

Datasets

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.

MCP endpoint registry

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.

Development

uv sync          # create .venv and install dev dependencies
just prepare     # format, lint, typecheck, spec digest gate, tests

just 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/.

License

MIT — see LICENSE.

Metadata

Release files for bronto-sdk 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bronto-sdk 0.2.1
File Size Uploaded Provenance Actions
bronto_sdk-0.2.1.tar.gz 294.2 kB With provenance Details for bronto_sdk-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for bronto-sdk 0.2.1
File Interpreter ABI Platform Actions
bronto_sdk-0.2.1-py3-none-any.whl Python 3 none any Details for bronto_sdk-0.2.1-py3-none-any.whl

Total release size: 342.8 kB

Release files / bronto_sdk-0.2.1.tar.gz

Download URL bronto_sdk-0.2.1.tar.gz
Size 294.2 kB
Tags Source
SHA-256 checksum
How to use checksums
c8f7810573c349c9f0c96218ba480d7d20ef0bb209debd7832279dabe0cf702a
BLAKE2b-256 checksum
How to use checksums
5037c861079de746f846ca827440f1d326853974c70cb3b40772687522b27447
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / bronto_sdk-0.2.1-py3-none-any.whl

Download URL bronto_sdk-0.2.1-py3-none-any.whl
Size 48.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
058ee18949726df32557477879df7441293539cb16f9f41ac44206334c842e14
BLAKE2b-256 checksum
How to use checksums
873864241a482f902847c3ff3d38b08ffc36e2160e4e8e1bf04fc76ce2cbe4a9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for bronto-sdk 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for bronto_sdk-0.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page