05 ClickStack

ส่งต่อ telemetry ด้วยตัวเก็บแบบไร้สถานะในเครื่อง เปิดใช้ Managed ClickStack และตรวจดูใน HyperDX ที่โฮสต์บนคลาวด์

จุดเริ่มต้น

คุณอยู่บน build-workshop-v1 — ไม่ต้อง checkout ตั้งงบเวลาประมาณ 15 นาที แอป ถูกใส่ instrument สำหรับ OpenTelemetry ไว้แล้ว ในโมดูลนี้คุณจะเปิดใช้มันด้วย overlay ของตัวเก็บข้อมูล

ข้อกำหนดเบื้องต้น: เซอร์วิส Cloud ของคุณรันอยู่ (โมดูล 01)

การจะวินิจฉัยแอปในภายหลัง คุณต้องมองเห็นมันก่อน ClickStack (สแต็ก observability ของ ClickHouse ที่มี HyperDX เป็น UI) เก็บ trace และ log ของ OpenTelemetry ไว้ใน ClickHouse ในโมดูลนี้คุณจะเปิดตัวเก็บข้อมูล เพื่อให้ทุกคำขอที่ผ่านแอป สร้าง telemetry ที่คุณคิวรีได้

เป้าหมาย

trace ของแอปและ log คิวรีของแบ็กเอนด์ไหลเข้า ClickStack โดยมี trace ของคำขอแบบครบวงจร อย่างน้อยหนึ่งรายการ และสตรีมของบันทึกคิวรีที่สำเร็จที่มองเห็นได้

ขั้นที่ 1 — รัน overlay ของตัวเก็บ OpenTelemetry

HyperDX พื้นที่จัดเก็บ และการประมวลผลคิวรียังคงถูกจัดการใน ClickHouse Cloud คอมโพเนนต์เดียว ที่อยู่ในเครื่องคือตัวเก็บ OpenTelemetry แบบไร้สถานะที่อยู่ข้างแอปในเครื่อง มันส่งต่อ telemetry และไม่ใช่การติดตั้ง ClickStack หรือ HyperDX ในเครื่อง

ตรวจพอร์ตของตัวเก็บข้อมูลก่อน

ตัวเก็บข้อมูลเผยแพร่ OTLP บนพอร์ตของโฮสต์ 4317 และ 4318 ซึ่งมักจะ ถูกใช้อยู่แล้ว ถ้า ./preflight.sh ใน ClickHouse_Demos/workshops/build_workshop/app ขึ้น WARN เกี่ยวกับพอร์ตเหล่านั้นในโมดูล 00 ให้ตั้ง OTEL_GRPC_HOST_PORT และ OTEL_HTTP_HOST_PORT ใน .env.workshop เป็นค่าที่ preflight แนะนำ (ตัวอย่าง 24317 / 24318) ก่อนจะเริ่ม overlay แบ็กเอนด์เข้าถึงตัวเก็บข้อมูลภายในเน็ตเวิร์ก ดังนั้นการแมปพอร์ตของโฮสต์ใหม่จึงปลอดภัย จาก ที่ไหนก็ได้ภายใน repository ที่โคลนมา ให้รัน cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh ใหม่เพื่อยืนยันว่าพอร์ตว่าง

`.env.workshop` และ `docker-compose.otel.yml`

ค่าเหล่านี้อยู่ในส่วน observability ของ ClickStack ใน .env.workshop.example ให้กรอกใน .env.workshop ของคุณ:

OTLP_AUTH_TOKEN=change-me-workshop-token   # shared secret securing OTLP ingest
CLICKSTACK_DATABASE=otel                   # ClickStack's own otel_* tables
OTEL_SERVICE_NAME=nyc-taxi-backend         # the service name shown in HyperDX
LOG_LEVEL=DEBUG                            # show successful queries in Log source

ห้าม source ไฟล์นี้เข้าเชลล์ของคุณ คำสั่ง Compose ด้านล่างอ่านมันโดยตรง ซึ่งช่วยกันรหัสผ่านและคีย์ API ของมันออกจากตัวแปรเชลล์ที่ export แล้ว และทำให้การแก้ไข ไฟล์ในภายหลังมีผลจริง

ตอนนี้ยกสแต็กขึ้นพร้อม overlay overlay จะตั้ง OTEL_ENABLED=true บน แบ็กเอนด์ เพิ่มเซอร์วิส otel-collector (clickhouse/clickstack-otel-collector) และ build ฟรอนต์เอนด์ใหม่ด้วยการตั้งค่า telemetry ของเบราว์เซอร์:

docker compose --env-file .env.workshop \
  -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build

ตัวเก็บข้อมูลใช้ CLICKHOUSE_HOST / CLICKHOUSE_PORT / CLICKHOUSE_USER / CLICKHOUSE_PASSWORD จาก .env.workshop ซ้ำ แบ็กเอนด์ export OTLP ไปที่ http://otel-collector:4318 (HTTP/protobuf) ถ้าต้องการเก็บ stdout ดิบของคอนเทนเนอร์บน โฮสต์ Linux ด้วย ให้เพิ่ม --profile container-logs

ขั้นที่ 2 — เปิดใช้ Managed ClickStack บนเซอร์วิสของคุณ

เวิร์กช็อปใช้ Managed ClickStack (HyperDX) ภายในเซอร์วิส ClickHouse Cloud ของคุณเอง: ตัวเก็บข้อมูลเขียนตาราง otel_* ไปที่เซอร์วิสของคุณ และ UI ของ HyperDX แสดงผล จากที่นั่น เปิดใช้ในคอนโซล:

คอนโซล - เซอร์วิสของคุณ -> ClickStack -> Start Ingestion -> ข้ามขั้นตอนตัวเก็บ ข้อมูล (ตัวเก็บข้อมูลของแอปรันอยู่แล้วจากขั้นที่ 1) -> Launch ClickStack

นั่นจะพาคุณเข้า HyperDX แบบ single sign-on telemetry เริ่มไหลไปแล้ว ดังนั้น UI ที่โฮสต์อยู่จะมีข้อมูลได้ทันทีที่เปิด

Managed ClickStack: สิ่งที่ต่างจากการติดตั้งแบบคลาสสิก

แบ็กเอนด์ใช้ OpenTelemetry แบบธรรมดา ไม่ใช่แพ็กเกจ hyperdx-opentelemetry แบบสะดวกที่เอกสาร ClickStack แนะนำ แพ็กเกจนั้นตรึง opentelemetry-api==1.30.0 ไว้แข็ง ซึ่งขัดกับ Langfuse v4 SDK ที่ฟีเจอร์แชท ใช้ (ต้องการ opentelemetry-api>=1.33.1) — ทั้งสองอยู่ในสภาพแวดล้อมเดียวกัน ไม่ได้ ตัวเก็บข้อมูลของ ClickStack รับ OTLP มาตรฐาน ดังนั้น distro แบบธรรมดา จึงทำงานเหมือนกัน เวิร์กช็อปเพียงตั้งตัวแปร env ของ exporter เอง
telemetry ของ ClickStack อยู่ในฐานข้อมูลแยกบนเซอร์วิสของคุณ (CLICKSTACK_DATABASE=otel) แยกจากฐานข้อมูลข้อมูลของแอป (CLICKHOUSE_DATABASE=nyc_tlc_data)
trace และ log ของ Python ในแบ็กเอนด์ไหลผ่าน OTLP จากแบ็กเอนด์ที่ auto-instrument ไว้ ตัวเก็บข้อมูล --profile container-logs ที่เป็นตัวเลือกมีไว้สำหรับเซอร์วิสที่ไม่ได้ instrument เท่านั้น เช่นตัวเขียนข้อมูลการเดินทาง เส้นทาง log ของ Docker บน Linux ของมันอาจไม่มีบน Docker Desktop

ขั้นที่ 3 — สร้างทราฟฟิกและหามันใน ClickStack

เปิดแดชบอร์ด Ops และปล่อยให้ช่วงเวลา 1m และ auto-refresh 5s ที่เป็นค่าเริ่มต้นทำงาน ประมาณ 30 วินาที แล้วเปิด ClickStack:

ใน Traces ให้ตามหนึ่งคำขอแบบครบวงจร (ฟรอนต์เอนด์ -> แบ็กเอนด์ -> ClickHouse)
ใน Logs ให้เลือก nyc-taxi-backend และหาบันทึก ClickHouse query ok ที่ซ้ำ ๆ timestamp ของมันควรเดินหน้าทุกครั้งที่รีเฟรช
คงระดับความรุนแรงให้มีความหมาย: คิวรีที่สำเร็จเป็น DEBUG ส่วนการลองใหม่จากการปลุกจาก idle จริงและความล้มเหลวจะปรากฏเป็น WARNING หรือ ERROR

คุณควรเห็นเซอร์วิสชื่อ nyc-taxi-backend ปรากฏใน HyperDX โดยมีคำขอ /api/... แสดงเป็น trace แต่ละอันมี span ลูกชื่อ clickhouse.query

หน้า HyperDX Search แสดง trace ของ nyc-taxi-backend — รายการสดของ span GET /api/health และ POST พร้อมคอลัมน์ timestamp, service และ duration

HyperDX แสดง trace ของแอป: เซอร์วิส nyc-taxi-backend พร้อม span ของคำขอ /api/...

วิธีตรวจสอบว่าคุณทำเสร็จ

เซอร์วิสชื่อ nyc-taxi-backend ปรากฏใน HyperDX
คำขอไปที่ /api/... แสดงเป็น trace แต่ละอันมี span ลูกชื่อ clickhouse.query ที่พา db.statement, db.elapsed_ms และ db.rows_returned มาด้วย
แหล่ง Log แสดงบันทึก DEBUG ... ClickHouse query ok ใหม่ ๆ ขณะที่แดชบอร์ด Ops ยังเปิดอยู่
คุณจะยังไม่เห็นข้อผิดพลาดของคิวรีที่นี่: แอปที่สุขภาพดีและมีข้อมูลแล้วไม่ทำให้ชนขีดจำกัด ความปลอดภัย และคำขอ 4xx ไม่เคยไปถึง ClickHouse ในโมดูล 07 ความผิดพลาดที่ฉีดเข้าไปจะทำให้ span clickhouse.query ที่มีข้อผิดพลาด (พร้อม error.category) สังเกตได้

สรุปปิดท้าย

ตอนนี้แอปสังเกตการณ์ได้แล้ว: trace และ log คิวรีของแบ็กเอนด์ถูกบันทึกใน ClickHouse และ สำรวจได้ใน ClickStack โปรไฟล์ container-logs ที่เป็นตัวเลือกเพิ่ม stdout จากตัวเขียนข้อมูล การเดินทางบนโฮสต์ Linux ที่รองรับ telemetry นั้นเป็นพื้นฐานสำหรับงาน AI SRE ต่อไป

สถานะปลายทาง

telemetry กำลังไหลเข้า ClickStack ไปต่อที่ 06 AI SRE เพื่อให้ agent ของคุณสร้างต่อยอดบนมัน