Deploy Open-Source APM Databuff in 5 Minutes: OpenTelemetry Distributed Tracing Quick Start

For backend and DevOps engineers new to open-source APM — spin up the platform with one curl command, configure standard OTLP ingestion, and see your first distributed trace in the Web UI.

Why OTLP standard + open-source APM

Move beyond proprietary agent lock-in — use the OpenTelemetry ecosystem's universal protocol for application performance monitoring.

The problem: Traditional APM tools often tie you to their own agents — switching backends means changing SDKs and re-collecting data. OpenTelemetry (OTel) unifies Trace, Metrics, and Logs under the OTLP protocol. On the application side, you only need to configure an Exporter pointing at the backend Ingest endpoint to get application performance monitoring and distributed tracing.

Databuff is an open-source APM that uses OTLP as its sole ingestion standard. The architecture has only three core containers: Ingest, Doris (storage), and Web (platform). Compared to multi-component stacks like SkyWalking, deployment and operations costs are significantly lower.

Figure 0 · Ingest → Doris → Web

OTLP vs proprietary agent APM — at a glance:

• Ingestion protocol — Proprietary: vendor-specific format · Databuff: OTLP gRPC 4317 / HTTP 4318
• Application changes — Proprietary: bound to specific SDK · Databuff: any OTel SDK / auto-instrumentation
• Deployed components — Proprietary: probe + OAP + storage + UI, etc. · Databuff: Ingest + Doris + Web (3 containers)
• License — Proprietary: commercial / mixed · Databuff: fully open source

The Ingest service exposes these OTLP ports by default:

ai-apm-ingest:
  ports:
    - "4317:4317"   # OTLP gRPC
    - "4318:4318"   # OTLP HTTP

Getting started tip: The HTTP 4318 endpoint http://<host>:4318/v1/traces is the most friendly for curl, Demo apps, and most SDKs; gRPC 4317 is better suited for high-throughput production workloads.

Prerequisites and ai-apm-install.sh

Docker + Compose · run as root · Web UI ready in ~5 minutes

Prerequisites

• OS: Linux (amd64 / arm64 supported; the script auto-detects architecture and downloads the matching image bundle)
• Dependencies: Docker, Docker Compose, curl, tar
• Permissions: Must run as root (default install directory: /opt/databuff-ai-apm)
• Memory: ≥ 8 GB available RAM recommended (Doris FE/BE + three service containers)

One-command platform install

The official install script runs a fully automated 5-step flow: check environment → download deployment package → load images → clean old version → install and start.

# Latest version — one-click install
curl -fsSL https://databuff.ai/databuff/ai-apm-install.sh | bash

# Pin a specific version
curl -fsSL https://databuff.ai/databuff/ai-apm-install.sh | bash -s -- --version 0.1.1

Public install script: ai-apm-install.sh. After a successful install, the console prints the Web UI URL, default credentials, and Ingest endpoint:

Web UI
  http://<host-ip>:27403
Credentials
  admin / Databuff@123
Ingest
  http://<host-ip>:4318/v1/traces

Ports at a glance:

• Web UI — port 27403 — APM console, AI platform entry
• Ingest (OTLP HTTP) — port 4318 — Trace / Metrics HTTP ingestion
• Ingest (OTLP gRPC) — port 4317 — Trace / Metrics gRPC ingestion
• Doris FE — ports 8030 / 9030 — storage engine (internal; no direct access needed)

Common operations:

cd /opt/databuff-ai-apm
./start.sh    # Start
./stop.sh     # Stop

Demo app install and OTLP exporter configuration

Don't want to modify production code first? Install the Demo to generate sample data, then mirror the config in your own apps.

Demo one-click data seeding

After the platform is installed, run the Demo install script. It continuously reports simulated Traces to Ingest — open the UI to see service topology and distributed tracing data.

curl -fsSL https://databuff.ai/databuff/ai-apm-demo-install.sh | bash

Demo script: ai-apm-demo-install.sh.

The Demo container points to Ingest via environment variables — the same approach you'd use for production apps:

ai-apm-demo:
  environment:
    OTEL_EXPORTER_OTLP_ENDPOINT: http://ai-apm-ingest:4318
    SEED_INTERVAL_SECONDS: 30

Bring your own app (Java / Spring Boot, OpenTelemetry Java Agent):

export OTEL_SERVICE_NAME=order-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://<ingest-host>:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
java -javaagent:opentelemetry-javaagent.jar -jar order-service.jar

Node.js (@opentelemetry/sdk-node) core configuration:

const exporter = new OTLPTraceExporter({
  url: 'http://<ingest-host>:4318/v1/traces',
});
// Set serviceName to a recognizable name for service list aggregation

Verify ingestion succeeded: After installing the Demo, wait ~30 seconds (SEED_INTERVAL_SECONDS), then refresh the Web UI service list. If it's still empty, check that firewall rules allow port 4318 and that the Exporter URL includes the /v1/traces suffix (HTTP protocol).

Web UI verification: service list → trace explorer

Log in at http://<host>:27403 and follow the topology → metrics → traces path to confirm data is visible.

Step 1 · Service list

Go to Application Performance → Services to see Demo-generated services like service-a and service-b, along with request count, error rate, and response time — the entry view for application performance monitoring.

Figure 1 · Service list — top charts + service table, confirming OTLP data has been stored

Step 2 · Global dashboard

Open the Global Dashboard to view per-minute health timelines and alert distribution across services — a quick snapshot of overall system health.

Figure 2 · Global dashboard — health timelines for all services at a glance

Step 3 · First trace in trace explorer

Go to Application Performance → Trace Explorer, select the last 1 hour, and you'll see Trace count distribution and response time scatter plots. Click any Trace to drill down into the Span waterfall view — completing the loop from "deploy" to "see your first distributed trace".

Figure 3 · Trace explorer — Trace count and response time distribution

Recommended troubleshooting path: Global topology to spot abnormal nodes → service details to confirm metrics → trace explorer to pinpoint slow Spans.

FAQ

The most common questions during deployment and ingestion setup:

• Ports 4317 / 4318 not reachable — Check cloud security groups / iptables rules; inside the container run curl http://127.0.0.1:4318/health to confirm Ingest health; for cross-host reporting, set the Exporter address to the host IP rather than Docker internal hostnames.
• Is 8 GB RAM enough? — Sufficient for local dev / Demo validation. Doris FE 768m + BE 3G + ingest/web each 384m ≈ 5 GB container limits total; production recommends 16 GB+ with larger Doris heap settings.
• Does AI analytics need an LLM Key? — APM tracing does not depend on an LLM — service list, topology, and Traces work fully without a Key. The AI platform requires an API Key in Settings → Model Configuration to enable smart Q&A / inspection (optional).
• Install script reports Docker unavailable — Confirm docker info works and you're running as root; Compose v2+ required (script includes ensure_compose_cli check).
• Service list is empty — Install the Demo first or confirm app Exporter points to the correct Ingest; wait 1–2 minutes for minute-level aggregation; check that OTEL_SERVICE_NAME is set.

---

References: Install script · Demo script · DataBuff on GitHub · OpenTelemetry docs