Documentation
The Orbtrace handbook
Start at the top and read straight through. Every page is numbered, every screen has a legend, every graph has a meaning. If you've never used an observability tool before, this guide assumes nothing.
Start here
What Orbtrace is, what it does, and a ten-minute first run.
- What is Orbtrace?Read this first if you've never used an observability tool. It explains, in plain language, the problem Orbtrace solves and what you'll see in the UI.
- ConceptsThe words "log", "trace", "span", "metric", "SLO", "RCA" all mean specific things. This page defines them with concrete analogies before you see them in the UI.
- QuickstartFrom "nothing installed" to "I see my first trace on the screen" — copy-paste, in order, on any machine with Docker. Honest about every step, including standing up a Collector.
Installation & Deployment
Prepare, then deploy on a single host, Kubernetes, or the cloud.
- Installation preparationWhat to decide and prepare before installing Orbtrace — the three deployment paths, hardware and kernel prerequisites, the real port list, and the post-install checklist.
- Capacity planningSize the deployment for your load — tell the calculator your daily volume, retention, and service count and get back the Helm sizing, Doris FE/BE counts, vCPU, memory, and disk to provision. Grounded in Apache Doris's published deployment guidance.
- Single-host (Docker Compose)The recommended all-in-one deployment — one docker compose up -d brings up the Orbtrace app, Doris, Postgres+pgvector, and Valkey on a single machine. Also the fastest way to evaluate.
- Bare metal (Ansible)The same single-host stack as Docker Compose, installed and managed for you on one Linux host — Docker set up, secrets vaulted, and the stack running as a systemd service.
- Deploying on KubernetesRun the stateless Orbtrace app in Kubernetes with the OCI Helm chart, and connect it to the datastores it needs. Overview, recommended architecture, and the step-by-step sub-pages.
- Provide the datastoresHow to run Postgres+pgvector and Valkey (or Redis) for a Kubernetes deployment — bundled in the chart, on a VM or managed service, or via Docker — and point the chart at them.
- Setting up DorisHow to provide the Doris telemetry store that the Helm chart points at with doris.host — choosing where Doris runs, the requirements, why in-cluster Doris uses the operator, installing the operator, applying the DorisCluster, and bringing Orbtrace up against it.
- Install with HelmAuthenticate to the registry, edit the chart values, run helm install, and verify — the step-by-step Helm install for Orbtrace once your datastores are ready.
- OpenShift / OKDInstalling Orbtrace on OpenShift under the default restricted-v2 SCC — the values-openshift overlay, the one node-level prerequisite (kernel settings via the Node Tuning Operator), the Doris operator PSA + SCC, and Route-based ingress.
- Ports & exposureHow you reach Orbtrace on Kubernetes and how to change any port — the app on 8080, your Collector's OTLP ports, and the Doris/Postgres/Valkey ports.
- Deploying on CloudRun Orbtrace on a managed Kubernetes cluster — EKS, AKS, or GKE — using the Helm path plus the cloud's managed Postgres, cache, storage, and load balancer.
- Deploying on AWS (EKS)Run Orbtrace on Amazon EKS the recommended way — RDS for Postgres+pgvector, a throughput-tuned gp3 StorageClass, Doris via the operator or EC2, an ALB ingress with ACM TLS, and the AWS-specific gotchas (EBS AZ-locking, IRSA, security groups).
- Deploying on Azure (AKS)Run Orbtrace on Azure Kubernetes Service the recommended way — Azure Database for PostgreSQL with the pgvector allowlist, a tunable Premium SSD v2 StorageClass, Doris via the operator or Azure VMs, AGIC ingress, and the Azure-specific gotchas.
- Deploying on GCP (GKE)Run Orbtrace on Google Kubernetes Engine the recommended way — Cloud SQL for Postgres+pgvector, a tunable Hyperdisk StorageClass, Doris via the operator or GCE, GKE Ingress with a managed certificate, and the GCP-specific gotchas.
- Sign-in & SSOHow users sign in to Orbtrace. Pick a Single Sign-On provider, configure it once, and your team gets in. No passwords, no separate accounts to maintain.
- First loginWhat to expect the first time you sign in to a fresh Orbtrace install, and the five things to verify before letting your team in.
- LicensingHow Orbtrace licensing works — the free COMMUNITY edition, the paid editions, how to obtain and activate a license offline, and exactly what happens when one expires.
Send your data
Point your apps at Orbtrace and watch data arrive.
- Instrument your appsSend logs, traces, and metrics from your real services into Orbtrace. Copy-paste blocks for Java, .NET, Go, Node, Python, PHP, Ruby, Rust, the raw-JSON-over-HTTP path, plus databases, caches, and message queues.
- Integration patternsHow the OpenTelemetry Collector connects your apps to Orbtrace's Doris — the two field patterns, the per-signal Doris exporter wiring, recommended production settings, advanced tuning, and layouts for single hosts, Kubernetes, OpenShift and service meshes.
Configure
Settings, AI provider, authentication, sampling, retention.
Screens, one by one
Every page of the UI explained — what you see, what each chart means.
- UI tourEvery layout element of the Orbtrace UI explained — top bar, sidebar, time picker, command palette, theme, footer. Read once before the per-screen guides.
- HomeThe first screen you land on after sign-in. What every panel shows, what each colour means, what to click first when something looks wrong.
- ServicesThe two screens you'll spend most of your time on. The list answers "which service is unhappy?", the detail answers "why?".
- Service mapA live graph of who calls whom across your fleet. Read this page to understand what edge thickness, colour, and node shape mean — and how to use the map to find a bad dependency in seconds.
- LogsThe screen for "find the log line that explains this". Histogram, search bar, pattern clustering, detail drawer — what each of them shows and why.
- Live tailLike `tail -f` but for your whole fleet — a streaming feed of log lines as they arrive, with the same filters as the Logs screen, no histogram and no pause.
- TracesHow to find the right trace in the list (histogram + columns + autocomplete), then how to read the waterfall and span attributes once you've opened one.
- MetricsPick a metric, slice it by attributes, plot it. What the four chart types show, how to combine metrics, and how to save a query as a dashboard panel.
- DashboardsDrag-and-drop dashboards built from logs, traces, and metric queries. What panel types exist, how variables work, how sharing works.
- AlertsThe complete alerting console — rules, channels, recipients, routing, escalation, schedules, silences, maintenance, audit, analytics, and GitOps. What each subpage is for and the order to set them up.
- Incidents & RCAWhen an alert fires, an incident opens. Causal RCA writes a paragraph that says what caused it, with span citations. This page explains every part of the incident screen.
- ReplayPick a moment in the past. Change one fact ("what if we hadn't deployed?"). Orbtrace simulates the counterfactual outcome using past data and your AI provider. This page explains how to run one and how to read the result.
- Astra (AI assistant)The chat assistant that can search your telemetry, fetch traces, run RCA, and draft alerts for you — plus the "What I noticed" proactive panel. How to use it, what it can do, and the guardrails.
- OperationsService-by-operation drill-down — the same screen as "service detail" but pivoted to one specific endpoint (e.g. `POST /checkout`).
- AdminThe administrator-only settings — AI provider, anomaly detection, sampling caps, SLO defaults, service catalog, integrations, users, license, retention, Astra PII, and telemetry health. What each subpage is for.
- How the numbers are calculatedExactly what every headline number on the Services and SLO screens means, the formula behind it, and the honest caveats — request rate, error rate, percentiles, health, burn rate, error budget, Apdex, saturation, and "deviating".
Operate
Day-two operations — backups, upgrades, hardening, air-gapped runs.
- Backup & restoreWhat to back up (and what not to), how the Helm backup CronJobs work, the manual Compose/Ansible procedure, and how to restore — for both the settings database and the telemetry store.
- UpgradesHow to move Orbtrace to a new version safely on Docker Compose, Helm, and Ansible — what migrates automatically, what to back up first, and how to roll back.
- Security hardeningThe checklist to run before Orbtrace faces anything beyond your laptop — TLS, secrets, network exposure, authentication posture, actuator surface, and the audit trail.
- Air-gapped operationRunning Orbtrace on a network with no internet access — the offline install bundle, local AI with Ollama, offline licensing, and what (if anything) ever needs to reach out.
Daily workflows
Step-by-step recipes for the jobs SREs do every day.
- Investigate an incidentThe full SRE playbook from "my pager went off" to "I resolved the incident". The exact clicks in order, with screenshots-in-words.
- SLO + alertsHow to pick an SLO target, set it in Orbtrace, and wire the four-window burn-rate alerts that come with it. Includes a sample SLO for an HTTP API.
- Run a replayA worked example. We take a real incident (slow checkout after a deploy), ask the counterfactual, and read the result.
Reference
Search syntax, troubleshooting, frequently asked questions.
- Search syntaxThe complete query language used in the Logs search bar, the Traces search bar, the Metrics filters, and the alert-rule editor. Same syntax everywhere.
- TroubleshootingDecision tree for "something is broken" — start at the symptom, end at the fix. Covers no-data, partial-data, slow UI, AI failures, login issues, container crashes.
- FAQThe questions every prospect and new operator asks in the first week. Answered in one paragraph each.
- Webhook verificationVerify that an alert webhook really came from your Orbtrace instance — HMAC-SHA256 signature, timestamp-skew check, and idempotency-key de-dup. Receiver snippets for Node, Python, Go, and Java.
- Span stitchingTune the async-stitching engine that reconnects orphan spans — scheduler cadence, candidate windows, the confidence floor, and the three scorer weights. Plus the two independent ways to turn it off and which one to use.