Docs · Getting started
Up and running in two commands.
Polartrace instruments your app with a preload flag (Node.js) or a CLI wrapper (Python) - no code changes for Express, Fastify, Koa, NestJS, Flask, FastAPI or Django. Agents flush every 10 seconds, so your first request shows up moments after you deploy.
Before you start
- Create a free account - no card required.
- In the console, open Integrations and create a service. Its name becomes your POLARTRACE_APP_NAME.
- Copy the license key the wizard shows you.
Node.js quickstart
Requires Node 18+. The agent auto-instruments HTTP, Express, Fastify, Koa and NestJS, plus MongoDB/Mongoose, PostgreSQL and Redis - via OpenTelemetry, with zero code changes.
bash - Node.js
# install
$ npm install polartrace
# run with the preload flag - zero code changes
$ POLARTRACE_APP_NAME=checkout-api POLARTRACE_LICENSE_KEY=<your-key> node -r polartrace server.js
In Docker, use CMD ["node", "-r", "polartrace", "server.js"] and pass both variables as environment. TypeScript apps running under tsx or ts-node work the same way.
Prefer explicit setup? The programmatic API (new Polartrace({...}) + agent.middleware()) is documented in the agent README.
Python quickstart
Requires Python 3.8+. Flask, FastAPI and Django attach automatically - the CLI wraps your normal start command, so it works with uvicorn, gunicorn and manage.py unchanged.
bash - Python
# install
$ pip install polartrace
# write polartrace.config.json, then paste your license key into it
$ polartrace-admin init --name checkout-api
# verify connectivity
$ polartrace-admin test → Polartrace connection: OK
# run your app exactly as before, wrapped
$ polartrace-admin run-program python app.py
Environment variables (POLARTRACE_APP_NAME, POLARTRACE_LICENSE_KEY) work instead of the config file if you prefer. Outbound requests, SQLAlchemy, psycopg2, PyMongo and Redis get client spans automatically.
Kubernetes
The cluster agent is a single read-only deployment that snapshots nodes, pods, workloads and HPA state, streams cluster events, and can collect container logs for namespaces you opt in. Install it from the console: Integrations → Kubernetes walks you through deploying the agent and verifies the connection at the end.
Configuration reference (Node.js)
| Variable | Effect |
|---|---|
| POLARTRACE_APP_NAME | Required. The service name - must match the service you created in the console. |
| POLARTRACE_LICENSE_KEY | Required. The API key from the console's integration wizard. |
| POLARTRACE_ENABLE_CONSOLE_LOG | Capture console output onto each request log. |
| POLARTRACE_DISABLE_HOST_METRICS | Turn off CPU / memory / event-loop sampling. |
| POLARTRACE_DISABLE_MONGO_SPANS | Turn off MongoDB / Mongoose query spans. |
| POLARTRACE_DISABLE_POSTGRES_SPANS | Turn off PostgreSQL (pg) query spans. |
| POLARTRACE_DISABLE_REDIS_SPANS | Turn off Redis command spans. |
Sensitive fields - passwords, tokens, secrets, API keys, authorization and cookie headers, card numbers - are replaced with [REDACTED] on your server before anything is transmitted. Inline SQL literals are scrubbed to placeholders.
Supported frameworks
Node.js - npm polartrace
- Express 4 · Fastify 4–5 · Koa 2–3 · NestJS 9–10
- HTTP server & client spans (automatic)
- MongoDB & Mongoose · PostgreSQL (pg) · Redis (ioredis, node-redis 4+)
- Console-log capture, error stacks, log ↔ trace correlation
- Host & process metrics incl. event-loop lag
Python - PyPI polartrace
- Flask · FastAPI · Django (zero-code attach)
- Outbound spans: requests, urllib3, httpx
- SQLAlchemy · psycopg2 · PyMongo · Redis
- Host & process metrics
- Log ↔ trace correlation: Node.js only today
Both agents are built on OpenTelemetry SDKs and official instrumentations, and export to Polartrace's collector. Go, Java, Ruby and .NET are on the roadmap.
Concepts
- Span
- The smallest unit of work - one HTTP call, one database query. Spans carry kind (SERVER / CLIENT / INTERNAL), status, attributes and events.
- Trace
- All spans that share one request context, across every service the request touched.
- Request log
- One entry per handled request: method, path, status, duration, headers - plus captured console output and error stacks for Node.js.
- Service
- A deployable unit (e.g. checkout-api) bound to an API key. Services live inside environments (production, staging, …) within your organization.
- Monitor
- A threshold rule on a metric. Monitors fire alerts - with optional separate warning and critical levels - and notify on recovery.
Monitors & alerts
Monitors evaluate every minute over a window you choose (default 5 minutes) and support >, <, >=, <= against eight metrics:
- Error rate (% of requests ≥ 400)
- Latency (p99 of request durations)
- CPU (process, weighted average)
- Memory (RSS as % of host memory)
- Request volume
- K8s pod restarts
- K8s pods not ready
- K8s nodes not ready
Alerts deliver by email on every plan and to a Slack incoming webhook on Growth and above - each with a trend chart and a deep link to the exact alert. Notifications are edge-triggered: one on breach, one on recovery, nothing in between.
Stuck? Email support@polartrace.io or open an issue on GitHub.
Start free