Jaeger 安裝指南

發表於 分類於

什麼是 Jaeger？

Jaeger 是一套開源的分散式追蹤系統，常用於觀察微服務架構中請求在不同服務之間的流向、耗時與錯誤位置。透過 Jaeger，可以把分散在多個服務中的 trace 資料集中起來，協助開發者分析效能瓶頸與服務之間的呼叫關係。

本文會示範如何在 Ubuntu 環境中安裝 Jaeger Tracing，並透過 systemd 將 Jaeger 設定成系統服務。這裡使用 Jaeger 的 OpenTelemetry Native Backend 設定，讓服務可以接收 OTLP gRPC 與 HTTP 格式的 trace 資料，並透過 Jaeger Query UI 查詢追蹤結果。

Jaeger 的主要功能：

  • 分散式追蹤：記錄請求在多個服務之間的完整流向
  • 效能分析：查看每個 span 的耗時，協助找出延遲來源
  • 錯誤排查：透過 trace 資料定位服務呼叫失敗或異常的位置
  • 服務觀察：搭配 OpenTelemetry 收集 trace，建立基本的可觀測性基礎

為什麼使用 Jaeger？

相較於只依賴應用程式日誌，Jaeger 可以用更直觀的方式呈現跨服務請求的完整脈絡：

  1. 請求脈絡清楚：可以追蹤一次請求經過哪些服務與操作
  2. 問題定位更快：能從 trace 中看出延遲、錯誤與異常發生的位置
  3. 支援 OpenTelemetry：可以接收 OTLP gRPC 與 HTTP 格式的 trace 資料

安裝流程

整體流程會先建立 Jaeger 專用的系統使用者，接著安裝 Jaeger 執行檔、建立設定檔目錄與 config.yaml，最後建立 systemd service 並啟動服務。

建立 Jaeger 使用者與安裝執行檔

首先建立 Jaeger 專用的系統使用者。這個使用者不需要登入系統，也不需要家目錄，主要用途是讓 Jaeger 服務能以獨立權限執行。

1
sudo useradd --no-create-home --shell /bin/false jaeger

Jaeger 的安裝檔可以從 Jaeger 官方下載頁 取得。進入下載頁後，依照伺服器的作業系統與 CPU 架構選擇對應版本，例如 Linux AMD64 環境可下載 Linux 版本的壓縮檔。下載並解壓縮後，確認目錄中可以看到 jaeger 執行檔，再繼續後續安裝步驟。

接著將已下載並解壓縮完成的 jaeger 執行檔複製到 /usr/local/bin/，並將檔案擁有者設定為 jaeger。

1
2
3
sudo cp jaeger /usr/local/bin/

sudo chown jaeger:jaeger /usr/local/bin/jaeger

建立 Jaeger 設定目錄

Jaeger 服務啟動時會讀取 /etc/jaeger/config.yaml，因此需要先建立設定檔目錄，並設定適當的群組與權限。

1
sudo mkdir -p /etc/jaeger && sudo chown root:jaeger /etc/jaeger && sudo chmod 2750 /etc/jaeger

這裡將 /etc/jaeger 的擁有者設為 root，群組設為 jaeger，代表設定目錄仍由系統管理者維護，但 Jaeger 服務所屬的 jaeger 群組可以讀取設定檔。chmod 2750 中的 750 代表擁有者具備讀取、寫入與執行權限，群組具備讀取與執行權限，其他使用者則沒有任何權限；前面的 2 則是 setgid 權限，讓這個目錄底下新建立的檔案或子目錄自動繼承 jaeger 群組，避免 Jaeger 服務因為群組不一致而無法讀取設定。

建立目錄後，新增 Jaeger 的設定檔。

1
sudo nano /etc/jaeger/config.yaml

設定內容如下。這份設定會使用 memory 作為 trace storage，並啟用 Jaeger Query UI 與 OTLP receiver。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
extensions:
  jaeger_storage:
    backends:
      memory:
        memory:
          max_traces: 100000

  jaeger_query:
    storage:
      traces: memory
    http:
      endpoint: "0.0.0.0:16686"

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: "0.0.0.0:4317"
      http:
        endpoint: "0.0.0.0:4318"

exporters:
  jaeger_storage_exporter:
    trace_storage: memory

service:
  extensions: [jaeger_storage, jaeger_query]
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [jaeger_storage_exporter]

建立 systemd service

設定檔完成後，建立 Jaeger 的 systemd service，讓 Jaeger 可以透過 systemctl 管理。

1
sudo nano /etc/systemd/system/jaeger.service

服務檔內容如下。這裡會指定 Jaeger 使用剛才建立的 jaeger 使用者執行，並讀取 /etc/jaeger/config.yaml 作為啟動設定。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
[Unit]
Description=Jaeger Tracing
Wants=network-online.target
After=network-online.target

[Service]
User=jaeger
Group=jaeger
Type=simple
ExecStart=/usr/local/bin/jaeger --config=/etc/jaeger/config.yaml
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

啟動 Jaeger 服務

建立服務檔後，重新載入 systemd 設定，啟動 Jaeger，並設定開機自動啟動。

1
2
3
4
5
6
7
sudo systemctl daemon-reload

sudo systemctl start jaeger

sudo systemctl enable jaeger

sudo systemctl status jaeger

若服務狀態顯示 active (running)，代表 Jaeger 已經正常啟動。接著可以開啟瀏覽器進入 http://127.0.0.1:16686，確認 Jaeger Query UI 是否可以正常開啟。

查看 Jaeger 服務日誌

如果需要觀察 Jaeger 啟動過程或排查設定問題，可以使用 journalctl 即時查看服務日誌。

1
sudo journalctl -u jaeger.service -f

當 Jaeger 正常啟動後，應用程式就可以透過 OTLP gRPC 4317 或 OTLP HTTP 4318 將 trace 資料送到 Jaeger，再透過 16686 的 Jaeger Query UI 查詢追蹤結果。

Demo 驗證

服務啟動後，開啟瀏覽器進入 http://127.0.0.1:16686，可以看到 Jaeger Query UI。這個畫面會列出已收到 trace 的服務名稱，並提供時間範圍、標籤與操作名稱等查詢條件。若應用程式已經透過 OpenTelemetry 將 trace 送到 Jaeger，就可以在這裡選擇對應服務並查詢請求紀錄。

查詢結果中每一筆 trace 都代表一次完整的請求流程。點進 trace 詳細頁後，可以看到請求經過的 span、每個步驟的耗時，以及不同服務之間的呼叫順序。透過這個視圖，可以快速判斷延遲發生在哪個服務或哪個操作上，也能用來排查跨服務呼叫失敗的問題。