TrueWatch 工作坊：ExpressCart 展示範例設定指南

🌟 這是基於 Markmoffat 的 expresscart 打造的 Truewatchshop 應用程式

查看 expresscart 說明文件 📖 請點此。

ℹ️ 目的：
Truewatchshop 的目的是為客戶與合作夥伴提供一個訓練用的沙盒環境。
此沙盒讓使用者能在安全的實作環境中，探索、實驗並學習如何使用 Truewatch 進行監控、追蹤與應用程式效能管理。
應用程式已完成埋點，此訓練沙盒的重點在於如何導入資料，並熟悉 Truewatch 平台與工作流程。

🛠️ 技術堆疊

本專案使用以下技術建置：

Node.js：🟢 用於執行 JavaScript 的後端執行環境。
Express.js：🚀 用於建置應用程式的網頁框架。
MongoDB：🗄️ 用於儲存應用程式資料的 NoSQL 資料庫。
Docker：🐳 用於部署應用程式的容器化平台。
Nginx：🌐 作為反向代理使用的網頁伺服器。
Truewatch RUM / APM / LOG：📊 用於效能監控與除錯的追蹤工具。

⚙️ 事前準備

開始之前，請確認您已具備以下條件：

Truewatch 帳號 📝
請至 truewatch.com 註冊 Truewatch 帳號，以使用監控與分析功能。
具備網路連線的 Linux 系統 💻
使用具穩定網路連線的 Linux 主機（實體或虛擬皆可）。

提示：建議使用 Linux 虛擬機以利隔離與簡化設定。若您尚未擁有虛擬機，Windows 使用者可使用 Oracle VirtualBox，MacOS 使用者可使用 OrbStack 建立虛擬環境。
此訓練沙盒是使用 Orbstack 與 Ubuntu 22.04.5 LTS 建立的。
- 若您選擇使用 Orbstack，安裝指南請參閱此處。
- 若您選擇使用 Virtualbox，安裝指南請參閱此處。
請建立一台使用 Ubuntu 22.04.5 LTS 的 Linux 虛擬機。
已安裝 DataKit 📦
從您的 Truewatch 帳號安裝 DataKit，以啟用追蹤與監控功能。
更多官方 Datakit 安裝說明請參閱此處。

安裝您的 Datakit：
- 前往您的 Truewatch 平台，並使用您的 Truewatch 帳號登入。
- 導覽至 Integrations > Datakit。
- 複製下方截圖中以綠色標示的 部署指令碼。

前往您剛安裝好的 Linux 主機，並在主控台中執行該 部署指令碼：

DK_DATAWAY="https://id1-openway.truewatch.com?token=tkn_xxxxxxxx" bash -c "$(curl -L https://static.truewatch.com/datakit/install.sh)"

確認 datakit 是否正在執行：

ps aux | grep datakit
root         806 11.6  0.3 2036304 34012 ?       Sl   01:59 116:22 /usr/local/datakit/externals/datakit-ebpf run --datakit-apiserver 0.0.0.0:9529 --hostname ubuntu --l7net-enabled httpflow --pprof-host 127.0.0.1 --pprof-port 6061 --netlog-metric --netlog-log --trace-env-list DK_BPFTRACE_SERVICE,DD_SERVICE,OTEL_SERVICE_NAME --enabled ebpf-net,ebpf-trace

Docker 🐳
安裝 Docker 以在容器中執行應用程式。
取得 Docker 安裝說明請點此。
```
sudo apt-get update
sudo apt-get install -y git docker.io docker-compose
sudo usermod -aG docker $USER
newgrp docker
```
注意：最後兩個指令會將您的使用者加入 docker 群組，讓您無需使用 sudo 即可執行 Docker。您可能需要登出並重新登入才能生效。
Git 🧰
安裝 Git 以複製儲存庫並管理原始碼：
```
sudo apt-get update
sudo apt-get install -y git
```

🚀 專案設定步驟

複製儲存庫：

git clone https://github.com/TrueWatchTech/expresscart-demo-setup-guide
cd expresscart-demo-setup-guide

安裝相依套件並建置專案：
```
docker-compose build
```
啟動服務：
```
docker-compose up -d
```

填入測試資料至資料庫：

docker exec -it expresscart npm run testdata

[選用] 自訂商品圖片：
- 前往 Truewatchshop 的管理頁面。
- 使用以下帳密登入：
  - 使用者名稱：[email protected]
  - 密碼：test
- 導覽至 Products。

找到商品 「Duckworth Woolfill Jacket」，並點擊底部的 add image URL。系統會顯示 Product Image URL 視窗。

開啟新的瀏覽器分頁，並在 Google 搜尋關鍵字 Duckworth Woolfill Jacket 以取得圖片網址。例如，您可使用以下網址：
https://content.steepandcheap.com/images/items/large/FJR/FJRZ0M5/GRE.jpg。
將該網址複製到 Product Image URL 欄位並新增圖片。
對其他商品重複上述步驟以更新其圖片網址。

注意：您可以透過 RUM 統計資料監控圖片載入時間。

📊 基礎設施監控設定步驟

依照事前準備章節中第 3 步所述安裝 Datakit。
安裝了 datakit 的 Linux 主機會將其指標資料傳送至 Truewatch 平台。
前往您的 Truewatch 平台進行驗證。
導覽至 Infrastructure > Host。點擊 Honeycomb 以切換至 Honeycomb 檢視。

您應可看到您的主機。將滑鼠移至上方即可快速檢視主機的關鍵指標（CPU、記憶體使用量、load5）。

透過設定 Datakit 的 container.conf，啟用容器監控（此處以 Docker 為例）：
- 前往您的 Linux 主控台，切換至 /usr/local/datakit/conf.d/container/ 目錄。接著將 container.conf.sample 複製為 container.conf，並重新啟動 Datakit：
```
cd /usr/local/datakit/conf.d/container
sudo cp container.conf.sample container.conf
sudo datakit service -R
```
前往您的 Truewatch 平台進行驗證。
導覽至 Infrastructure > Containers。

點擊容器名稱以探索 Containers 檢視畫面

導覽至 Scenes > New Dashboard。在 Template Name 欄位輸入 Docker，並按下 Enter。系統會顯示 Docker Monitor View 範本，點擊它。輸入名稱後點擊確認。

完成上述步驟後，您將進入 Docker Monitor View 畫面。以下為範例，您可使用左上角欄位（主機名稱、容器名稱、容器 ID）進行篩選。

基礎設施監控對於維持應用程式環境的健康、效能與可靠性至關重要。透過使用 Truewatch，您可即時掌握伺服器、容器與網路資源的狀態，藉此快速偵測問題、優化資源使用，並確保使用者獲得順暢的體驗。

🌐 RUM 設定步驟

前往您的 Truewatch 平台，並使用您的 Truewatch 帳號登入。
建立客戶端權杖：
前往 Management > Client Token > Create。複製新建立的權杖並妥善保存，下一步將會用到。

登入您的 Truewatch 控制台，並前往 Real User Monitoring > Application List > Create Application。

於 App Type 選擇 Web。在 App Name 欄位輸入應用程式名稱，並指定 App Id。

選擇 Public DataWay Deployment，接著選擇 CDN Asynchronous Loading。在 clientToken 欄位輸入您先前保存的 Client Token。

輸入以下數值（或最符合您應用程式的數值）：
- service = frontend
- env = production
- version = 1.0.0.0

複製以綠色標示的自動產生指令碼，並保存於您慣用的編輯器中。

設定 Nginx 以套用上述參數：
- 前往主控台中的 expresscart-demo-setup-guide 目錄，導覽至 nginx/conf.d
```
cd expresscart-demo-setup-guide
cd nginx/conf.d/
```
- 使用您慣用的編輯器編輯 default.conf，並貼上步驟 5 中自動產生指令碼的內容。

注意：我們已將 Nginx 設定為透過 sub_filter 指令自動注入指令碼，以自動埋點 RUM 代理程式，使其能自動植入使用者的瀏覽器端。透過此方式，您無需修改前端 HTML 程式碼。關於 Nginx sub_filter 指令的更多資訊請參閱此處。

停止並重新啟動服務：

docker-compose down
docker-compose up -d

開啟瀏覽器並前往 http://localhost:8080。您應可在連接埠 8080 看到正在執行的網頁應用程式。

與您的應用程式互動：
- 使用帳號 [email protected]、密碼 test 登入。
- 模擬使用者選擇商品並加入購物車。
前往您的 Truewatch 平台，前往 RUM > Application，並選擇您的應用程式。
在 Analysis Dashboard 中觀察統計資料。