Skip to content
You are reading the docs for Backstory 0.2 (private beta). Behavior may change before general availability; the changelog lists every change.

Backend SDKs

A backend SDK records every request your service handles, the database queries and calls it makes, its log lines, and its metrics. When a request comes from a page the browser recorder is on, all of it is linked to that replay, across every service the request touches.

Go, Node.js, and Python are available now. .NET is next.

Open Backend → Connect a service and create a server key. An owner or admin creates keys. A key can be limited to one environment. The secret is shown once.

Terminal window
go get backstory.io/go
func main() {
defer backstory.Start(context.Background())()
mux := http.NewServeMux()
// ...
http.ListenAndServe(":8080", backstory.Handler(mux))
}

Use backstory.Client() for outgoing calls, bspgx.Tracer() for pgx, and bsriver.Middleware() for River jobs.

Terminal window
npm i @backstory/node
node --import @backstory/node/start server.js

Or make import "@backstory/node/start" the first import of the app. Express, NestJS, Next.js, Koa, Hapi, pg, MongoDB, Redis, Kafka.js, the AWS SDK, and more are traced with no code.

Terminal window
pip install backstory
backstory-run gunicorn app:app

Or call backstory.start() before the web framework is imported. Django, FastAPI, Flask, SQLAlchemy, psycopg, Redis, Celery, boto3, and more are traced with no code.

Terminal window
BACKSTORY_SERVER_KEY=sk_live_… BACKSTORY_SERVICE=checkout-api BACKSTORY_ENVIRONMENT=production

Without a key the SDK does nothing, so the same build runs where Backstory is not set up. The service name and environment have sensible defaults, and the release is read from common CI systems.

LanguageCommand
Gogo run backstory.io/go/cmd/backstory-doctor
Node.jsnpx backstory doctor
Pythonbackstory doctor

The doctor checks the key, the connection, and the environment, lists the libraries it will trace, and sends a test request and log line. Both show up under Backend within a few seconds.

Under Backend → Settings, per service and environment, without a deploy:

  • Capture level. Everything; standard; critical (errors, slow requests, and requests with a replay); or off.
  • Log level. The lowest severity that is sent.
  • Boost. Capture everything for a service for a set time while you investigate.
  • Ignored routes (health checks are ignored by default), headers to keep, and field names to mask.
  • Runtime metrics and the metric interval.
  • Daily budget and monthly cap on backend data.

Changes reach running services within a minute.

Fields named like passwords, tokens, keys, cookies, and card numbers, plus the names you add in settings, are masked inside your process before anything is sent. Backstory scans again on arrival for secrets, tokens, emails, phone numbers, card numbers, and other personal data. User ids can be hashed with a project setting. PHI mode masks names, addresses, dates of birth, and other health identifiers, stops request and response bodies, and always hashes user ids.

Each SDK has a counter, a histogram, and a gauge.

metric.counter("orders.placed").add(1, { plan: account.plan });

Keep attribute values to a small set, such as plan, region, or status. A user id or order id as an attribute makes a new series every time and runs into the plan’s series limit. See pricing for how metrics count toward backend data.

The SDKs are OpenTelemetry, so spans from other OpenTelemetry libraries join the same traces. To keep your own setup, point its OTLP/HTTP exporter at https://api.backstory.io/v1/otlp with Authorization: Bearer sk_live_…. Add the W3C baggage propagator so the replay’s session.id reaches your spans.