Grafana Tempo là một backend dành cho distributed tracing (theo dõi/monitor phân tán) tối ưu chi phí và có khả năng xử lý khối lượng lớn. Công cụ này chỉ yêu cầu Object Storage (hoặc bộ nhớ lưu trữ cục bộ – local filesystem) để hoạt động mà không cần đến các cụm cơ sở dữ liệu hay bộ lập chỉ mục (indexing) phức tạp. Tempo chấp nhận các trace (dấu vết) ở nhiều định dạng như OpenTelemetry (OTLP), Jaeger và Zipkin, đồng thời tích hợp chặt chẽ với Grafana để trực quan hóa trace và đối chiếu với các metrics (chỉ số đo lường) cùng logs (nhật ký hệ thống).
Bài viết này sẽ hướng dẫn chi tiết cách cài đặt Tempo trên hệ điều hành Ubuntu 24.04 và Debian 13, cấu hình để nhận các OTLP traces, kết nối Grafana Alloy với vai trò như một đường ống dẫn trace (trace pipeline) và truy vấn các trace qua Grafana bằng ngôn ngữ TraceQL.
Điều kiện tiên quyết (Prerequisites)
- Một máy chủ (Server) đang chạy Ubuntu 24.04 LTS hoặc Debian 13 với tối thiểu 2GB RAM.
- Có quyền truy cập
roothoặcsudo. - Các ứng dụng đã được thiết lập OpenTelemetry SDKs hoặc thư viện client của Jaeger (để tạo ra các traces).
- Đã cài đặt Grafana để trực quan hóa trace.
Hướng Dẫn Toàn Tập Cài Đặt và Quản Trị Grafana Trên Ubuntu 24.04 / Debian 13 (Kèm Nginx & SSL): Tại đây
1. Tải xuống và Cài đặt Tempo
Tempo cung cấp các gói thư viện .deb chính thức trên mục Releases của GitHub. Bạn hãy tải và cài đặt phiên bản mới nhất bằng chuỗi lệnh sau:
VER=$(curl -sI https://github.com/grafana/tempo/releases/latest | grep -i ^location | grep -o v[0-9.]* | sed s/^v//)
curl -fsSLo /tmp/tempo.deb https://github.com/grafana/tempo/releases/download/v${VER}/tempo_${VER}_linux_amd64.deb
sudo dpkg -i /tmp/tempo.deb
rm /tmp/tempo.deb
Kiểm tra quá trình cài đặt để đảm bảo mọi thứ thành công:
tempo --version
Bạn sẽ thấy thông tin phiên bản trả về trên màn hình:
tempo, version 2.10.3 (branch: HEAD, revision: 4aeafc237)
build user:
build date:Gói cài đặt Debian này sẽ tự động tạo một tài khoản người dùng hệ thống là tempo, khởi tạo một dịch vụ systemd và đặt tệp cấu hình mặc định tại đường dẫn /etc/tempo/config.yml.
2. Cấu hình Tempo
Cấu hình mặc định của Tempo hoạt động rất tốt đối với một thiết lập độc lập (standalone). Trước tiên, bạn hãy tạo các thư mục dữ liệu:
sudo mkdir -p /var/tempo/{wal,blocks,generator/wal,generator/traces}
sudo chown -R tempo:tempo /var/tempo
Mở tệp cấu hình:
sudo vi /etc/tempo/config.ymlstream_over_http_enabled: true
server:
http_listen_port: 3200
log_level: info
distributor:
receivers:
otlp:
protocols:
grpc:
endpoint: "0.0.0.0:4317"
http:
endpoint: "0.0.0.0:4318"
jaeger:
protocols:
thrift_http:
grpc:
ingester:
trace_idle_period: 10s
max_block_bytes: 524288000
max_block_duration: 5m
compactor:
compaction:
block_retention: 72h
storage:
trace:
backend: local
wal:
path: /var/tempo/wal
local:
path: /var/tempo/blocks
metrics_generator:
registry:
external_labels:
source: tempo
cluster: production
storage:
path: /var/tempo/generator/wal
traces_storage:
path: /var/tempo/generator/traces
overrides:
defaults:
metrics_generator:
processors: [service-graphs, span-metrics, local-blocks]
generate_native_histograms: both
analytics:
reporting_enabled: false
Giải thích các thiết lập quan trọng:
- OTLP receiver trên cổng 4317/4318: Chấp nhận traces từ các ứng dụng sử dụng OpenTelemetry hoặc từ Grafana Alloy.
- Jaeger receiver: Chấp nhận traces theo định dạng của Jaeger, hỗ trợ tương thích ngược cho các hệ thống đã dùng sẵn chuẩn này.
- block_retention: 72h: Giữ lại dữ liệu trace trong 72 giờ (3 ngày). Bạn có thể tăng thời gian này tùy theo nhu cầu gỡ lỗi thực tế.
- metrics_generator: Tự động tạo ra các chỉ số RED (Rate, Errors, Duration) và sơ đồ dịch vụ (service graphs) từ các traces đẩy tới. Điều này giúp bạn dễ dàng truy vấn trên Grafana mà không cần phải thiết lập đo lường bổ sung.
- local backend: Lưu trữ các block trace ngay trên ổ cứng máy chủ cục bộ. Đối với môi trường sản xuất (production) có quy mô lớn, bạn nên chuyển sang sử dụng Object Storage như Amazon S3 hoặc Google Cloud Storage (GCS).
3. Khởi động và Kích hoạt Dịch vụ Tempo
Khởi động cùng hệ thống và bật dịch vụ Tempo. Kiểm tra trạng thái dịch vụ xem đã hoạt động chưa:
sudo systemctl enable --now tempo
sudo systemctl status --now tempo
Dịch vụ sẽ hiển thị trạng thái đang hoạt động (active):
● tempo.service - Tempo service
Loaded: loaded (/etc/systemd/system/tempo.service; enabled; preset: enabled)
Active: active (running) since Tue 2026-04-07 01:48:45 UTC; 8min ago
Main PID: 1400 (tempo)
Tasks: 9 (limit: 9430)
Memory: 25.3M (peak: 26.7M)
CPU: 2.493s
CGroup: /system.slice/tempo.service
└─1400 /usr/bin/tempo -config.file /etc/tempo/config.ymlXác minh xem Tempo đã sẵn sàng nhận trace hay chưa bằng lệnh:
Bạn hãy đợi khoảng 15 – 30 giây kể từ lúc khởi động dịch vụ sau đó chạy lại lệnh kiểm tra:
curl -s http://localhost:3200/ready
Nếu Tempo khỏe mạnh và hoạt động bình thường, nó sẽ trả về kết quả ready.
4. Mở Port Tường Lửa (Firewall)
Nếu máy chủ của bạn sử dụng UFW đang được kích hoạt, hãy mở các port (cổng) sau:
sudo ufw allow 3200/tcp
sudo ufw allow 4317/tcp
sudo ufw allow 4318/tcp
sudo ufw reload
- Cổng 3200: Đây là API HTTP của Tempo (chủ yếu được Grafana kết nối vào).
- Cổng 4317 và 4318: Nơi thu nhận OTLP gRPC và HTTP (điểm nhận traces từ các ứng dụng và Alloy).
5. Chuyển tiếp Traces thông qua Grafana Alloy
Nếu bạn đang chạy Grafana Alloy, hãy cấu hình nó để nhận OTLP traces từ ứng dụng rồi chuyển tiếp chúng về Tempo. Thêm các dòng khối mã sau vào tệp /etc/alloy/config.alloy:
Cấu hình này yêu cầu Alloy lắng nghe trên các cổng 4320/4321 (để tránh trùng với các cổng 4317/4318 của Tempo) và chuyển tiếp traces tới Tempo. Giờ đây, các ứng dụng có thể gửi traces tới Alloy (để xử lý theo dạng đường ống) hoặc gửi thẳng trực tiếp vào Tempo.
sudo mkdir -p /etc/alloy
sudo vi /etc/alloy/config.alloyotelcol.receiver.otlp "default" {
grpc {
endpoint = "0.0.0.0:4320"
}
http {
endpoint = "0.0.0.0:4321"
}
output {
traces = [otelcol.exporter.otlp.tempo.input]
}
}
otelcol.exporter.otlp "tempo" {
client {
endpoint = "localhost:4317"
tls {
insecure = true
}
}
}
6. Thêm Tempo làm Nguồn dữ liệu (Data Source) vào Grafana
Tại giao diện đồ họa của Grafana, bạn hãy điều hướng tới Connections > Data sources > Add data source.
Chọn Tempo đặt thông số URL là http://localhost:3200 và nhấn Save & test.
Ngoài ra, bạn có thể cấp phép tự động theo dạng provision:
sudo vi /etc/grafana/provisioning/datasources/tempo.yaml
Khởi động lại Grafana để nó tải nguồn dữ liệu vừa cấu hình:
sudo systemctl restart grafana-server
sudo systemctl status grafana-server
7. Gửi một Trace Kiểm tra
Để kiểm chứng xem toàn bộ “đường ống” đã hoạt động trơn tru chưa, hãy gửi một trace kiểm thử bằng curl thông qua điểm cuối OTLP HTTP:
curl -X POST http://localhost:4321/v1/traces \
-H "Content-Type: application/json" \
-d '{
"resourceSpans": [{
"resource": {"attributes": [{"key": "service.name", "value": {"stringValue": "test-service"}}]},
"scopeSpans": [{
"spans": [{
"traceId": "01020304050607080102040810203040",
"spanId": "0102040810203040",
"name": "test-span",
"kind": 1,
"startTimeUnixNano": "'$(date +%s)000000000'",
"endTimeUnixNano": "'$(( $(date +%s) + 1 ))000000000'",
"status": {"code": 1}
}]
}]
}]
}'
Tiếp theo, truy vấn dấu vết này trong chế độ xem Explore của Grafana bằng cách dùng cú pháp TraceQL. Chọn Data source là Tempo và gõ cụm tìm kiếm như sau:
{resource.service.name = "test-service"}
Bảng Tham chiếu các Port của Tempo
| Port | Protocol | Purpose |
|---|---|---|
| 3200 | HTTP | Tempo API (Grafana kết nối tới cổng này) |
| 4317 | gRPC | Trình tiếp nhận OTLP trace (gRPC) |
| 4318 | HTTP | Trình tiếp nhận OTLP trace (HTTP/protobuf) |
| 9095 | gRPC | Giao tiếp gRPC nội bộ |
| 14268 | HTTP | Trình tiếp nhận Jaeger thrift HTTP |
Khắc phục Sự cố Thường gặp (Troubleshooting)
Tempo báo lỗi không thể khởi động do xung đột Port 9095
Nếu bạn đang chạy hệ thống Grafana Mimir trên cùng một máy chủ này, cả Mimir và Tempo đều dùng mặc định cổng gRPC 9095. Để xử lý, hãy đổi cổng gRPC của Mimir sang một số khác (ví dụ: 9097) trong tệp /etc/mimir/mimir.yaml qua dòng grpc_listen_port: 9097.
Traces không hiển thị trên Grafana
Tempo cần một khoảng trễ nhỏ (vài giây) giữa quá trình tiếp nhận (ingestion) và khả năng bắt đầu truy vấn. Nếu chờ quá thời gian mà traces vẫn chưa hiển thị, hãy kiểm tra lại cấu hình URL Data Source của Tempo trong Grafana (phải là http://localhost:3200 chứ không phải port OTLP). Đồng thời, rà soát lại nhật ký lỗi của Tempo bằng lệnh sudo journalctl -u tempo -f.
Lỗi Phân quyền tại Thư mục WAL
Hãy đảm bảo rằng user tempo được trao quyền sở hữu với mọi thư mục dữ liệu bằng lệnh: sudo chown -R tempo:tempo /var/tempo. Gói .deb sẽ tự động tạo user nhưng đôi khi không thiết lập quyền cho các thư mục nằm ngoài đường dẫn mặc định.
Bước tiếp theo là gì?
Khi Tempo đã chạy ổn định, bạn đã hoàn thiện thành phần “Tracing” (Theo dõi phân tán) trong hệ sinh thái khả năng quan sát LGTM (Bao gồm: Loki quản lý log, Grafana trực quan hóa, Tempo theo dõi dấu vết, và Mimir đo lường các chỉ số metrics).
Sức mạnh thực sự của hệ sinh thái này nằm ở tính tương quan hóa (correlation). Giờ đây, bạn có thể dễ dàng nhấp chuột vào một dòng log bất kỳ trong Loki để nhảy thẳng đến trace liên quan bên trong Tempo, hoặc click vào một trace span để xem xét các metrics của nó ở thời điểm đó. Hãy cấu hình các liên kết trace-to-logs (từ trace đến log) và trace-to-metrics (từ trace đến metric) ngay trong phần Cài đặt Data source của Tempo trên Grafana để kích hoạt luồng công việc tuyệt vời này.
