Concepts

Read this page once, slowly. After it, every screen in Orbtrace will make sense. It assumes nothing.

Why your software needs "telemetry"

Imagine your software is a busy restaurant. From outside you can see customers walk in and out — that's all. You have no idea:

• Which dishes the kitchen prepared and which steps each took.
• Whether the dishwasher is overloaded.
• Whether the new chef you hired last Tuesday is slower than the old one.

To answer those questions, the restaurant needs records of what happened. In software, those records are called telemetry. Orbtrace handles three kinds:

1. 1

   Logs — the diary

   A log line is a single sentence your software writes when something happens.

   2026-05-13 14:02:11.842  INFO   checkout-api    User 42 placed an order for $19.99
   2026-05-13 14:02:12.103  ERROR  checkout-api    Payment provider returned 503

   Each line has:

   • A timestamp (when it happened).
   • A severity (INFO, WARN, ERROR, FATAL).
   • A service name (which program wrote it — checkout-api).
   • A message (the human-readable sentence).
   • Optionally, attributes (structured fields like user_id=42, order_total=19.99).

   In Orbtrace, you search and filter logs in the Logs screen.

2. 2

   Traces and spans — the receipt

   A trace is a record of one request as it travels through every service that touched it. Each step in that journey is called a span.

   If a customer clicks "buy", the request might hit:

   • frontend (10 ms — render the button click)
     • checkout-api (140 ms — validate the cart)
       • inventory-service (12 ms — check stock)
       • payment-provider (115 ms — charge the card)
       • email-service (5 ms — queue the receipt)

   The whole journey is one trace (with five spans nested under it). Each span knows:

   • Its parent (which span called it).
   • Its start time and duration.
   • Whether it succeeded or failed.
   • Its attributes (e.g. db.statement="SELECT * FROM orders").

   When you see the trace waterfall in Orbtrace, each horizontal bar is one span; the depth of the bar shows nesting.

   Why traces matter

   Logs answer "what did one service say?". Traces answer "where did the whole request spend its time?". When a page is slow, traces show you which step was the slow one — without you guessing.

3. 3

   Metrics — the dashboard number

   A metric is a number measured at regular intervals.

   • "Requests per second to checkout-api" → measured every 10 seconds.
   • "Memory used by inventory-service pod" → measured every 15 seconds.
   • "Queue depth in email-worker" → measured every 5 seconds.

   Metrics come in three flavours:

   On screen

   • CounterGoes only up. Example: total orders since the service started. To see "orders per minute" you ask Orbtrace for rate(orders_total[1m]).
   • GaugeGoes up and down. Example: current queue depth, current memory in use, current CPU percent.
   • HistogramRecords the distribution of values, not just the latest. Example: request latency — you can ask for "the 99th percentile of last minute's latencies".

   You explore metrics in the Metrics screen and build dashboards from them in Dashboards.

SLO — the promise you make

An SLO (Service Level Objective) is a measurable promise about how well a service performs. Example: "99.9% of checkout requests complete in under 500 ms, measured over a rolling 30-day window."

Three numbers anchor every SLO:

• SLI (Service Level Indicator) — the thing you measure. "Fraction of requests under 500 ms."
• SLO — the target. "99.9% of them."
• Error budget — how much you're allowed to break. If your target is 99.9% over 30 days, you have a budget of 0.1% failures — that's 43 minutes of "unhealthy" per month.

When your service burns through its error budget fast (say, 14× faster than it should), Orbtrace fires a burn-rate alert. SLOs are configured in Admin → SLOs.

RCA — the AI's answer to "why?"

RCA stands for Root Cause Analysis. In Orbtrace, RCA is an AI feature: during an incident, it reads the traces, logs, and recent deploys, and produces a paragraph like:

"checkout-api p99 latency jumped from 220 ms to 2.1 s at 14:02 (Europe/Istanbul). The change correlates with deploy a8f21b at 13:58, which modified OrderRepository.findByUser to remove an index hint. Spans b3f2… and c81a… show 1.8 s spent inside that query against orders (id 84210)."

It cites span IDs so you can click and verify. RCA results live in Incidents.

Time-Travel Replay — the counterfactual

Once an incident is closed, you can ask Orbtrace: "what if deploy a8f21b hadn't happened?" — and it estimates a probable answer using past data, similar past incidents, and the AI. It is a grounded heuristic, not a full simulator: you get a probabilistic outcome with a confidence interval, citing comparable past incidents — useful for post-mortems and pre-deploy canary calls. See Time-Travel Replay.

OpenTelemetry — the bus your data rides

Your applications never talk to Orbtrace directly. They speak OpenTelemetry (OTel) — the open standard the whole industry has agreed on for telemetry data. Every major language has an OTel SDK (Java, Node, Python, Go, .NET, Ruby, Rust, …), and adding it is usually a single line of config.

From there, the path your data takes is short and always the same. Your app hands its logs, traces, and metrics to a small program called the OpenTelemetry Collector. The Collector collects data from all your apps, groups it into efficient batches, and writes it into Apache Doris — Orbtrace's database. When you open Orbtrace, it reads from Doris and draws what you see on screen.

Why this indirection? Because the standard belongs to the industry, not to us: you instrument your apps once, against OTel, and they stay vendor-neutral — the same data could feed any OTel-compatible backend.

One important thing to understand up front: Orbtrace does not bundle the Collector. Orbtrace ships the product — the server, the UI, and the storage — and you run the Collector yourself (it's the standard, unmodified otel/opentelemetry-collector-contrib image with a config we provide). This is deliberate and matches how other modern observability stacks work: the Collector already handles OTLP ingest, batching, retry, and back-pressure at 100K+ events/sec, so re-implementing it would add nothing. Standing one up is a single docker run — see Integration patterns.

That's why you'll see "OTLP", "OTel SDK", and "Collector" mentioned throughout these docs.

Vocabulary you'll meet later

You don't need to memorise these. They'll appear in context.

Next up: the ten-minute Quickstart.