SSD Nodes Learn Hosting plans →
คู่มือ Matt Connorโดย Matt Connor

วิธี Self-host Langfuse บน VPS เพื่อติดตาม AI Agents

เรียนรู้วิธีติดตั้ง Langfuse บน VPS ของคุณเอง พร้อมตั้งค่า TLS, การจัดการ ClickHouse เพื่อป้องกันดิสก์เต็ม, การใช้ Image Tags ที่เสถียร และแนวทางการสำรองข้อมูลที่ใช้งานได้จริง

เหตุผลที่ต้องทำ Trace ให้กับ AI agent

คุณสามารถ self-host Langfuse เพื่อดูว่า agent ของคุณทำงานจริงอย่างไรในแต่ละรอบ Langfuse เป็นเครื่องมือ observability สำหรับ LLM (large language model) แบบ open source โดยจะบันทึกทุก prompt, ทุกการตอบกลับจากโมเดล, ทุกการเรียกใช้ tool และทุก token จากนั้นจะจัดกลุ่มข้อมูลเหล่านั้นไว้ภายใต้ trace เดียวที่คุณสามารถเปิดอ่านได้ การรันเครื่องมือนี้บน VPS ของคุณเองหมายความว่า prompt เหล่านั้นจะไม่ถูกส่งออกจากเซิร์ฟเวอร์ที่คุณควบคุม

เหตุผลที่ควรทำเรื่องนี้มีความชัดเจน คุณไม่สามารถแก้ไขปัญหาด้านต้นทุนหรือคุณภาพที่คุณมองไม่เห็นได้ ใบแจ้งหนี้จากผู้ให้บริการบอกคุณได้เพียงว่าวันอังคารมีค่าใช้จ่ายสูงกว่าวันจันทร์ถึง 4 เท่า แต่ trace จะบอกคุณว่า agent รอบไหนที่เป็นต้นเหตุ, prompt ใดที่ขยายตัวจนมีขนาดถึง 40,000 tokens และ loop การลองใหม่ (retry loop) รอบใดที่ทำงานซ้ำถึง 9 ครั้งก่อนจะยอมแพ้ ใบแจ้งหนี้ให้ตัวเลขแก่คุณ แต่ trace ให้โค้ดที่เป็นต้นกำเนิดของตัวเลขนั้น

มีคำศัพท์ 3 คำที่ใช้ตลอดคู่มือนี้ trace คือการทำงานตั้งแต่ต้นจนจบของ agent หนึ่งรอบ observation คือขั้นตอนหนึ่งภายในรอบการทำงานนั้น ได้แก่ span สำหรับโค้ดทั่วไป และ generation สำหรับการเรียกใช้งานโมเดล score คือตัวเลขที่แนบไปกับ trace ซึ่งได้จากการตรวจสอบโดยมนุษย์หรือตัวประเมินอัตโนมัติ Langfuse รองรับ OpenTelemetry (OTel) ซึ่งเป็นมาตรฐานกลางสำหรับ distributed tracing ดังนั้น instrumentation ที่คุณมีอยู่แล้วจึงสามารถเชื่อมต่อกับเครื่องมือนี้ได้

สิ่งที่ Langfuse ทำงานจริงเมื่อคุณ self-host

Langfuse v4 ไม่ได้มีเพียงคอนเทนเนอร์เดียว แต่ประกอบด้วยคอนเทนเนอร์แอปพลิเคชัน 2 ตัว และบริการจัดเก็บข้อมูล 4 ตัว ซึ่งหากรันบน VPS เครื่องเดียว ทั้ง 6 ตัวนี้จะทำงานอยู่บนเครื่องของคุณทั้งหมด

  • langfuse-web ให้บริการเว็บอินเทอร์เฟซและ ingestion API
  • langfuse-worker ทำหน้าที่จัดการคิวในเบื้องหลัง โดยจะประมวลผล ingestion batches คำนวณต้นทุน และรันงาน retention ประจำวัน
  • Postgres จัดเก็บข้อมูลธุรกรรม เช่น ผู้ใช้ องค์กร โปรเจกต์ API keys และ prompts
  • ClickHouse จัดเก็บข้อมูล trace เอง ซึ่งหมายถึง observations และ scores โดยเป็น column store ที่ออกแบบมาเพื่อการสืบค้นเชิงวิเคราะห์ ทำให้แดชบอร์ดสามารถตอบสนองได้อย่างรวดเร็วแม้จะมีข้อมูลนับร้อยล้านแถว
  • Redis ทำหน้าที่เป็นคิวและแคชที่อยู่ระหว่างเว็บและ worker
  • MinIO ให้บริการ object storage ที่รองรับ S3 บนเครื่องของคุณ โดยจะเก็บเหตุการณ์ขาเข้าดิบทั้งหมดรวมถึงสื่อต่างๆ ที่คุณแนบเข้ามา

Langfuse ได้ระบุทรัพยากรขั้นต่ำสำหรับแต่ละคอมโพเนนต์ที่ทำงาน โดยแผนภูมิด้านล่างแสดงถึง 3 ส่วนหลักที่ทำหน้าที่ประมวลผล

แผนภูมิLangfuse published minimum resources per component
ข้อมูลเบื้องหลังแผนภูมินี้
[
  {
    "label": "ClickHouse",
    "cpu_cores": 2,
    "memory_gib": 8
  },
  {
    "label": "Langfuse web",
    "cpu_cores": 2,
    "memory_gib": 4
  },
  {
    "label": "Langfuse worker",
    "cpu_cores": 2,
    "memory_gib": 4
  }
]

เฉพาะ ClickHouse เพียงตัวเดียวก็ต้องการหน่วยความจำ 8 GiB ส่วนคอนเทนเนอร์เว็บและ worker ต้องการตัวละ 4 GiB นี่คือค่าขั้นต่ำที่ระบุไว้สำหรับ 3 คอมโพเนนต์ในแผนภูมิ หน้าเดียวกันยังระบุว่า Postgres ต้องการ 4 GiB, Redis หรือ Valkey ต้องการ 1.5 GiB และ MinIO ต้องการ 4 GiB ดังนั้นค่าขั้นต่ำรวมของทั้ง 6 ตัวจึงอยู่ที่ 25.5 GiB คู่มือ Docker Compose ของโปรเจกต์แนะนำให้ใช้ CPU อย่างน้อย 4 คอร์, หน่วยความจำ 16 GiB และพื้นที่จัดเก็บข้อมูลประมาณ 100 GiB สำหรับเครื่องเดียว ซึ่งตัวเลขนี้ต่ำกว่าผลรวมของค่าขั้นต่ำของแต่ละคอมโพเนนต์ ดังนั้นให้ถือว่า 16 GiB คือค่าต่ำสุดที่เครื่องที่รัน Compose ร่วมกันต้องการ ไม่ใช่ค่าเผื่อสำหรับใช้งาน

อย่าพยายามรันบนแพลนขนาด 2 GiB เพราะ ClickHouse จะเริ่มทำงานและรับข้อมูลได้สักพัก จากนั้นจะหยุดทำงานระหว่างการทำ background merge เนื่องจากกระบวนการ merge จะโหลดข้อมูลส่วนใหญ่ของตารางลงในหน่วยความจำ คุณจะเห็น docker compose ps รายงานสถานะคอนเทนเนอร์ clickhouse เป็น restarting โดยมี dmesg แสดงข้อความเช่น Out of memory: Killed process 1234 (clickhouse-serv) และแดชบอร์ด Langfuse ทุกตัวจะส่งค่า 500 กลับมา หากภาระงานเบาลง ClickHouse จะปฏิเสธการสืบค้นและบันทึก log ว่า DB::Exception: Memory limit (total) exceeded ตัวเลข 16 คือจำนวนที่คุณควรวางแผนไว้ หาก VPS เครื่องเดียวกันต้องรันบริการอื่นด้วย ให้จัดสรรทรัพยากรแยกต่างหาก เพราะแม้แต่ stack ที่ค่อนข้างเบาอย่าง a self-hosted AFFiNE workspace ก็ต้องการหน่วยความจำของตัวเอง และ ClickHouse จะไม่คืนหน่วยความจำที่จองไว้ให้เด็ดขาด

การติดตั้ง Langfuse ด้วย Docker Compose

โคลน repository ลงมา สแต็ก การเชื่อมต่อ และ environment เริ่มต้นทั้งหมดอยู่ใน docker-compose.yml

git clone https://github.com/langfuse/langfuse.git
cd langfuse

ทุกค่าที่คุณต้องแก้ไขจะถูกทำเครื่องหมายไว้ด้วย # CHANGEME ในไฟล์นั้น ให้สร้าง secret สำหรับแอปพลิเคชันทั้งสามรายการก่อน

openssl rand -base64 32   # NEXTAUTH_SECRET
openssl rand -base64 32   # SALT
openssl rand -hex 32      # ENCRYPTION_KEY

ENCRYPTION_KEY ต้องเป็นค่าขนาด 256 บิตที่เขียนในรูปแบบเลขฐานสิบหก 64 ตัวอักษร ซึ่งเป็นสิ่งที่ openssl rand -hex 32 แสดงผลออกมา ค่านี้ใช้สำหรับเข้ารหัสข้อมูลสำคัญที่จัดเก็บไว้ รวมถึงคีย์ของผู้ให้บริการ LLM ใดๆ ที่คุณเก็บไว้ในอินสแตนซ์ หากคุณเปลี่ยนค่านี้หลังจากที่มีข้อมูลแล้ว ข้อมูลเหล่านั้นจะไม่สามารถถอดรหัสได้อีกต่อไป ดังนั้นให้ถือว่าค่านี้เป็นค่าถาวรตั้งแต่การบูตครั้งแรก ส่วน SALT ใช้สำหรับทำ hash ให้กับ Langfuse API keys ของคุณ ดังนั้นการเปลี่ยนค่านี้จะทำให้คีย์ทั้งหมดที่เอเจนต์ของคุณใช้งานอยู่ใช้งานไม่ได้ทันที

จากนั้นตั้งค่า POSTGRES_PASSWORD, CLICKHOUSE_PASSWORD, REDIS_AUTH และ MINIO_ROOT_PASSWORD รหัสผ่านของ MinIO จะปรากฏในสี่ตำแหน่ง ได้แก่ MINIO_ROOT_PASSWORD, LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY, LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY และ LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY หากคุณพลาดไปตำแหน่งหนึ่ง MinIO จะปฏิเสธไคลเอนต์นั้นด้วยข้อผิดพลาด SignatureDoesNotMatch ซึ่งจะปรากฏใน log ของ worker ในขณะที่หน้าเว็บอินเทอร์เฟซยังคงดูปกติ การเก็บค่าเหล่านี้ไว้ในไฟล์ env แทนที่จะเก็บไว้ในไฟล์ compose ที่ถูกติดตามโดย git เป็นรูปแบบที่อธิบายไว้ใน Docker Compose env files and secrets

กำหนดเวอร์ชันของอิมเมจ (Pin image tags) ก่อนเริ่มใช้งาน

ไฟล์ที่ให้มาใช้ docker.langfuse.com/langfuse/langfuse:4 และ docker.langfuse.com/langfuse/langfuse-worker:4 ซึ่งแท็กเหล่านี้มีการเปลี่ยนแปลงอยู่เสมอ Langfuse จะรันการ migration ของ Postgres และ ClickHouse โดยอัตโนมัติเมื่อเริ่มทำงาน ดังนั้นการรัน docker compose pull ตามปกติในอีกหลายเดือนต่อมา อาจกลายเป็นการ migration โครงสร้างฐานข้อมูลโดยไม่คาดคิดในฐานข้อมูลที่คุณไม่ได้สำรองข้อมูลไว้ในเช้าวันนั้น ให้กำหนดเวอร์ชันของทั้งสองรายการไว้ที่ release เดียวกันในไฟล์ docker-compose.override.yml ซึ่ง Compose จะนำไปรวมกับไฟล์หลัก เพื่อให้การรัน git pull ในภายหลังไม่ไปทับซ้อนกับการตั้งค่าของคุณ อิมเมจเดียวกันนี้ถูกเผยแพร่บน Docker Hub ซึ่งเป็นแหล่งที่ override ด้านล่างนี้ดึงข้อมูลมา

services:
  langfuse-web:
    image: docker.io/langfuse/langfuse:4.72.0
  langfuse-worker:
    image: docker.io/langfuse/langfuse-worker:4.72.0

เวอร์ชัน 4.3.1 เป็นเวอร์ชัน 4.3 ล่าสุด ณ เดือนสิงหาคม 2026 หลังจากนั้นมีการออก release ใหม่ๆ อย่างรวดเร็ว และ v4.56.0 เป็นเวอร์ชันล่าสุดบน GitHub ณ วันที่ 11 ตุลาคม 2026 ส่วน override ด้านบนใช้ v4.72.0 ซึ่งเป็นเวอร์ชันล่าสุดบน GitHub ณ วันที่ 31 ตุลาคม 2026 ให้ตรวจสอบหน้า GitHub releases ของโปรเจกต์ กำหนดเวอร์ชันที่เป็นปัจจุบันในวันที่คุณติดตั้ง แล้วจึงค่อยอัปเดตเวอร์ชันอย่างระมัดระวัง อิมเมจสำหรับจัดเก็บข้อมูลบางรายการในไฟล์หลักก็ควรได้รับการจัดการในลักษณะเดียวกัน เพราะแท็กของอิมเมจเหล่านั้นมีการเปลี่ยนแปลงเช่นกัน postgres:17 (ค่าเริ่มต้นของตัวแปร POSTGRES_VERSION) และ redis:7 จะตามหลังเวอร์ชันหลัก ไฟล์หลักในปัจจุบันใช้แท็กเวอร์ชันที่ระบุชัดเจนสำหรับ docker.io/clickhouse/clickhouse-server เพื่อล็อกเวอร์ชันของ ClickHouse กฎนี้ไม่ได้จำกัดเฉพาะ Langfuse เท่านั้น: a self-hosted openGym workout tracker รันสแต็กเพียงบางส่วนของระบบนี้และยังคงต้องการการระบุ git tag ที่ชัดเจน เพราะทุกสิ่งที่ทำการ migration ฐานข้อมูลของตัวเองเมื่อเริ่มทำงาน สามารถเปลี่ยนการ pull ตามปกติให้กลายเป็นการเปลี่ยนแปลงโครงสร้างฐานข้อมูลได้

เริ่มการทำงานของระบบ

docker compose up -d
docker compose ps
docker compose logs -f langfuse-worker

การบูตครั้งแรกจะรันการ migration ดังนั้นควรเผื่อเวลาสองถึงสามนาทีก่อนที่ระบบจะตอบสนอง คอนเทนเนอร์เว็บจะบันทึก log Ready เมื่อระบบพร้อมใช้งาน docker compose ps ควรแสดงรายการบริการหกรายการในสถานะ running หากคอนเทนเนอร์มีการรีสตาร์ทวนซ้ำ ให้ตรวจสอบ log เพื่อหาสาเหตุ การ migration ของ ClickHouse จะถูกนำไปใช้เมื่อคอนเทนเนอร์เว็บเริ่มทำงาน ดังนั้นหากค่า CLICKHOUSE_MIGRATION_URL ไม่ถูกต้อง ข้อผิดพลาดจะแสดงใน docker compose logs langfuse-web ไม่ใช่ใน log ของ worker ที่คุณกำลังติดตามอยู่ ตัวแปรนั้นใช้โปรโตคอลเนทีฟของ ClickHouse บนพอร์ต 9000 ไม่ใช่พอร์ต HTTP 8123 และการชี้ไปที่ 8123 จะทำให้การ migration ตอนเริ่มทำงานของคอนเทนเนอร์เว็บล้มเหลว ส่วน worker จะรันการ migration เบื้องหลังที่ช้ากว่า ดังนั้น log ของ worker จึงเป็นที่ที่รายงานข้อผิดพลาดเหล่านั้น

ตรวจสอบสถานะความพร้อมจากตัวเซิร์ฟเวอร์เอง

curl -s "http://localhost:3000/api/public/health?failIfDatabaseUnavailable=true"
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/api/public/ready

การเรียก /api/public/health แบบปกติจะพิสูจน์ได้เพียงว่ากระบวนการ API ยังทำงานอยู่เท่านั้น เนื่องจากโดยค่าเริ่มต้นมันไม่ได้ตรวจสอบฐานข้อมูล รูปแบบ failIfDatabaseUnavailable=true คือรูปแบบที่ควรใช้สำหรับเครื่องมือตรวจสอบ (monitor) โดยจะส่งค่า 503 กลับมาเมื่อไม่สามารถเข้าถึงฐานข้อมูลได้ ส่วน /api/public/ready จะส่งค่า 200 กลับมาเมื่อคอนเทนเนอร์เว็บพร้อมรับ traffic และส่งค่า 500 เมื่อได้รับคำสั่งให้ปิดตัวลง ทั้งสองรายการเป็นการตรวจสอบ HTTP ปกติ ดังนั้น an Uptime Kuma status page สามารถเฝ้าติดตามและแจ้งเตือนคุณได้หากสแต็กหยุดทำงานก่อนที่เอเจนต์ของคุณจะพบปัญหา

วาง TLS ไว้ด้านหน้าและปิดพอร์ตที่ไม่จำเป็น

ไฟล์ compose ที่มาพร้อมกับซอฟต์แวร์จะเปิดพอร์ต 3000:3000 สำหรับคอนเทนเนอร์เว็บ และ 9090:9000 สำหรับ MinIO โดยทั้งคู่จะผูกกับทุกอินเทอร์เฟซ หากเซิร์ฟเวอร์ของคุณมี Public IP หมายความว่าใครก็ตามที่สแกนพอร์ต 3000 จะเข้าถึงหน้าลงทะเบียนของคุณได้ และใครที่สแกนพอร์ต 9090 จะสามารถสื่อสารกับ bucket ที่เก็บข้อมูลดิบของคุณได้โดยตรง

กฎของไฟร์วอลล์เพียงอย่างเดียวไม่สามารถปิดพอร์ตเหล่านี้ได้ เนื่องจาก Docker จะเขียนกฎ DNAT ลงในตาราง nat ของตัวเอง ซึ่งกฎเหล่านี้จะถูกประเมินก่อนที่กฎ filter ของ ufw จะได้รับแพ็กเก็ต ดังนั้น ufw deny 3000 จึงทำให้พอร์ตที่เปิดไว้ยังคงเข้าถึงได้จากภายนอก ปัญหานี้เกิดขึ้นบ่อยจนมีคู่มือเฉพาะทาง: เหตุใดพอร์ตที่เปิดโดย Docker จึงข้ามการทำงานของ ufw ให้เปลี่ยนไปผูกกับ loopback ในไฟล์ override ของคุณแทน โดยใช้ !override ร่วมกับ Docker Compose เวอร์ชัน 2.24.4 ขึ้นไปเพื่อแทนที่พอร์ตที่เปิดไว้เดิม เนื่องจากการระบุรายการพอร์ตแบบปกติจะเป็นการรวมเข้ากับค่าเดิม

services:
  langfuse-web:
    ports: !override
      - "127.0.0.1:3000:3000"
    environment:
      NEXTAUTH_URL: https://langfuse.example.com
  minio:
    ports: !override
      - "127.0.0.1:9090:9000"
      - "127.0.0.1:9091:9001"

NEXTAUTH_URL ต้องเป็นที่อยู่สาธารณะที่ถูกต้องรวมถึง scheme ด้วย เพราะขั้นตอนการล็อกอินจะสร้าง callback URL จากค่านี้ หากคุณปล่อยให้เป็น http://localhost:3000 ในขณะที่อยู่หลัง HTTPS proxy กระบวนการตรวจสอบสิทธิ์จะส่งเบราว์เซอร์ไปยังที่อยู่ที่เข้าถึงไม่ได้

จากนั้นให้ชี้ reverse proxy ไปที่ 127.0.0.1:3000 และให้ proxy เป็นผู้จัดการ certificate สำหรับ Traefik ที่อยู่ในโปรเจกต์ Compose เดียวกัน ให้กำหนดเส้นทางไปยัง langfuse-web:3000 ผ่านเครือข่ายภายในของ Compose โดยใช้ labels ตามที่ระบุไว้ใน การรันหลายแอปหลัง Traefik reverse proxy ตัวเดียว Caddy สามารถทำงานเดียวกันได้โดยใช้การตั้งค่าเพียงสองบรรทัดหาก Langfuse เป็นบริการเดียวบนเครื่อง ตรวจสอบความถูกต้องด้วย curl -sI https://langfuse.example.com/api/public/ready จากนั้นยืนยันจากเครื่องอื่นว่า curl http://YOUR_IP:3000 ไม่สามารถเชื่อมต่อได้

มีข้อควรระวังสำหรับ MinIO คือ Langfuse จะแจกจ่าย presigned URL ที่ชี้ไปยัง S3 endpoint นั้น ทั้งสำหรับ SDK ที่อัปโหลดสื่อและเบราว์เซอร์ของคุณที่โหลดข้อมูล ดังนั้นหากคุณใช้ multi-modal traces ที่มีรูปภาพหรือเสียง การตั้งค่า MinIO ให้ฟังเฉพาะ loopback จะทำให้ไฟล์แนบเหล่านั้นไม่สามารถอัปโหลดจากเครื่องอื่นหรือโหลดในเบราว์เซอร์ของคุณได้ โปรดอ่านหน้าการตั้งค่า blob storage ก่อนที่จะทำ proxy เพราะ endpoint ที่เขียนลงใน presigned URL หรือ LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT จะต้องตรงกับสิ่งที่คุณเผยแพร่ออกไป ส่วนข้อมูลที่เป็นข้อความธรรมดา (plain text traces) จะไม่ได้รับผลกระทบ

สร้างบัญชีของคุณในการเข้าใช้งานครั้งแรก จากนั้นจำกัดสิทธิ์การเข้าถึงให้เป็นของคุณเพียงผู้เดียว ตั้งค่า AUTH_DISABLE_SIGNUP=true หลังจากสร้างบัญชีเรียบร้อยแล้ว เพื่อป้องกันไม่ให้คนแปลกหน้าที่เข้าถึงหน้าเว็บสามารถลงทะเบียนได้ นอกจากนี้ Langfuse ยังมี LANGFUSE_ALLOWED_ORGANIZATION_CREATORS ซึ่งจำกัดสิทธิ์ผู้ที่สามารถสร้างองค์กรได้ แต่ฟีเจอร์นี้เป็นส่วนหนึ่งของ Enterprise Edition และจะมีผลต่อเมื่อมี license key เท่านั้น หากคุณกำลังใช้งาน Authentik ในฐานะ identity provider ของคุณเอง อยู่แล้ว Langfuse รองรับการเชื่อมต่อ OIDC มาตรฐาน ทำให้บัญชีผู้ใช้สามารถจัดการร่วมกับแอปอื่นๆ ของคุณได้ แทนที่จะต้องเก็บรหัสผ่านแยกไว้ในรายการที่เครื่องนี้เครื่องเดียวเท่านั้นที่รู้จัก

ส่งข้อมูล trace รายการแรกของคุณ

สร้างโปรเจกต์ในเว็บอินเทอร์เฟซ แล้วคัดลอก public key และ secret key จากการตั้งค่าโปรเจกต์ Python SDK จะอ่านค่าจาก environment variable 3 ตัว

export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://langfuse.example.com"

LANGFUSE_BASE_URL คือชื่อตัวแปรใน SDK v4 ซึ่งเปิดตัวในเดือนมีนาคม 2026 โค้ดและคู่มือรุ่นเก่าจะใช้ LANGFUSE_HOST หาก trace ของคุณไปปรากฏที่ Langfuse Cloud แทนที่จะเป็นเซิร์ฟเวอร์ของคุณ สาเหตุเกิดจากการไม่ได้ตั้งค่า base URL เนื่องจากค่าเริ่มต้นจะชี้ไปยัง instance ที่โฮสต์ไว้

Python SDK v5 ในปัจจุบันต้องการ Python 3.11 ขึ้นไป และ Langfuse v4.59.0 ขึ้นไปสำหรับเวอร์ชัน self-hosted ซึ่งเซิร์ฟเวอร์ที่ระบุไว้ด้านบนนั้นรองรับข้อกำหนดนี้แล้ว

pip install langfuse opentelemetry-instrumentation-anthropic anthropic
import os
from anthropic import Anthropic
from langfuse import get_client, observe
from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor

AnthropicInstrumentor().instrument()
langfuse = get_client()
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

@observe(as_type="tool")
def lookup_order(order_id: str) -> str:
    return f"order {order_id}: shipped"

@observe()
def handle_request(question: str) -> str:
    context = lookup_order("A-1042")
    message = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=512,
        messages=[{"role": "user", "content": f"{context}\n\n{question}"}],
    )
    return message.content[0].text

if __name__ == "__main__":
    assert langfuse.auth_check()
    print(handle_request("Where is my order?"))
    langfuse.flush()

decorator @observe จะเปิดการสังเกตการณ์ (observation) ครอบฟังก์ชันนั้นไว้ โดยจะบันทึกอาร์กิวเมนต์และค่าที่ส่งกลับมา พร้อมทั้งจัดลำดับให้อยู่ภายใต้การสังเกตการณ์ที่กำลังทำงานอยู่ ส่วน AnthropicInstrumentor คือเครื่องมือ OpenTelemetry สำหรับ Anthropic client ซึ่งจะเปลี่ยนการเรียกใช้ messages.create แต่ละครั้งให้กลายเป็น generation ที่บันทึกชื่อโมเดล, ปริมาณการใช้ token และค่า latency โดยที่คุณไม่ต้องแก้ไขโค้ดที่จุดเรียกใช้งาน

การเรียกใช้ 2 คำสั่งนี้จะช่วยตรวจสอบความถูกต้องให้คุณ langfuse.auth_check() จะส่งค่า False หาก key ไม่ถูกต้องหรือ base URL ผิดพลาด ซึ่งช่วยประหยัดเวลาได้ดีกว่าการมานั่งสงสัยว่าทำไม dashboard ถึงว่างเปล่า ส่วน langfuse.flush() จะรอจนกว่า span ที่อยู่ในคิวจะถูกส่งออกไปจนหมด กระบวนการที่ทำงานสั้นๆ จำเป็นต้องใช้คำสั่งนี้ เพราะ SDK จะทำการ batch ข้อมูลในเบื้องหลัง หากสคริปต์จบการทำงานทันที ข้อมูลที่ยังไม่ได้ส่งใน batch จะสูญหายไป หากทั้งทีมต้องการส่ง trace แทนที่จะใช้สคริปต์แยกกัน ให้ตั้งค่าตัวแปรทั้ง 3 ตัวไว้ที่ gateway ที่ agent ของทุกคนใช้งานอยู่ แทนที่จะตั้งค่าใน shell ของแต่ละคน ซึ่งเป็นวิธีที่ a self-hosted OneCLI harness ใช้เพื่อให้การรันของเพื่อนร่วมงานทุกคนถูกบันทึกข้อมูลไว้ ในขณะที่ key ยังคงถูกเก็บไว้ในที่เดียว

เหตุใด ClickHouse ถึงมีขนาดเพิ่มขึ้นเรื่อยๆ

Traces เป็นข้อมูลที่มีอัตราการเติบโตเร็วที่สุดในบรรดาข้อมูลที่ผู้ใช้ส่วนใหญ่โฮสต์เอง ทุกครั้งที่ agent ทำงานจะมีการเขียนข้อมูล 1 แถวต่อหนึ่งขั้นตอน และมีการจัดเก็บข้อมูล input และ output แบบเต็มรูปแบบ ดังนั้น agent ที่มีการโต้ตอบบ่อยและมี prompt ขนาดยาวจะสร้างปริมาณข้อมูลต่อวันมากกว่าแอปพลิเคชันที่มันกำลังตรวจสอบอยู่หลายเท่า หากปล่อยไว้ ClickHouse จะเต็มดิสก์ และเมื่อดิสก์เต็มจะทำให้การนำเข้าข้อมูลหยุดชะงักทันทีแทนที่จะเป็นการลดความเร็วลง

การเติบโตนี้เกิดจากสองส่วนแยกกัน ซึ่งต้องใช้วิธีแก้ไขที่แตกต่างกัน

ส่วนแรกคือข้อมูล trace ของคุณเอง วิธีแก้ไขคือการตั้งค่า retention ในอินสแตนซ์ที่โฮสต์เอง การกำหนดระยะเวลาเก็บรักษาข้อมูลเป็นฟีเจอร์ของ Enterprise Edition ซึ่งต้องใช้ license key หากไม่มี Langfuse จะเก็บข้อมูล traces, observations, scores และ media ไว้โดยไม่มีกำหนด ดังนั้นควรจัดสรรขนาดดิสก์ให้เหมาะสมและพึ่งพาการแจ้งเตือนดิสก์ที่ระบุไว้ท้ายส่วนนี้ หากมี license แล้ว เจ้าของโปรเจกต์และผู้ดูแลระบบสามารถเปิดการตั้งค่าโปรเจกต์และกำหนดระยะเวลาเก็บรักษาข้อมูลเป็นจำนวนวันได้ Langfuse รองรับระยะเวลาขั้นต่ำที่ 3 วัน จากนั้นจะมีงานที่ทำงานทุกคืนเพื่อคัดเลือก traces, observations, scores และ media assets ที่เก่ากว่าช่วงเวลาดังกล่าวและลบออกจาก ClickHouse และ blob storage ยกเว้น media ที่เชื่อมโยงกับรายการใน dataset ที่ถูกบันทึกไว้ งานนี้ต้องการสิทธิ์ DeleteObject บน bucket ซึ่งข้อมูลรับรองระดับ root ของ MinIO ในไฟล์ compose เริ่มต้นมีสิทธิ์นี้อยู่แล้ว การลบข้อมูลเป็นการถาวร ดังนั้นหากคุณต้องการประวัติข้อมูลระยะยาว ให้ตั้งค่าการส่งออกข้อมูลไปยัง blob storage ไว้ก่อน อย่าเขียนคำสั่ง TTL ลงบนตารางของ Langfuse เองโดยตรง เพราะงาน retention คือสิ่งที่ทำให้ ClickHouse และ bucket ทำงานสอดคล้องกัน และการใช้ TTL ด้วยตนเองจะลบข้อมูลเพียงฝั่งเดียวเท่านั้น

ให้เลือกช่วงเวลาตามการใช้งานจริงของคุณ การตรวจสอบต้นทุนและคุณภาพมักทำกับข้อมูลที่ย้อนหลังไปไม่กี่วัน ไม่ใช่ข้อมูลที่เก่าเป็นเดือน ระยะเวลา 30 วันเป็นจุดเริ่มต้นที่เหมาะสมสำหรับทีมขนาดเล็ก และ 14 วันก็เพียงพอหากคุณเปิดดู trace เฉพาะตอนที่มีปัญหาเกิดขึ้นเท่านั้น

ส่วนที่สองคือตาราง system log ของ ClickHouse เอง ซึ่งมักทำให้ผู้ใช้ประหลาดใจเพราะดิสก์ยังคงมีขนาดเพิ่มขึ้นแม้จะตั้งค่า retention แล้ว ClickHouse จะเขียน trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log และ latency_log เพื่อใช้ในการวินิจฉัยระบบของตนเอง โดยไม่มีการตั้งค่า TTL มาให้ และ Langfuse ก็ไม่เคยอ่านข้อมูลเหล่านี้ ให้ตรวจสอบก่อนว่าพื้นที่ดิสก์ถูกใช้ไปกับส่วนใด

SELECT table, formatReadableSize(size) AS size, rows FROM (
    SELECT table, database, sum(bytes) AS size, sum(rows) AS rows
    FROM system.parts
    WHERE active
    GROUP BY table, database
    ORDER BY size DESC
)

รันคำสั่งด้วย docker compose exec clickhouse clickhouse-client --password "$CLICKHOUSE_PASSWORD" หากตารางระบบอยู่ในอันดับต้นๆ ของการใช้พื้นที่ ให้ปิดการใช้งานด้วย config overlay เนื่องจาก ClickHouse จะรวมไฟล์ทั้งหมดใน /etc/clickhouse-server/config.d/ เข้ากับ config หลักเมื่อเริ่มต้นระบบ

<clickhouse>
    <trace_log remove="1"/>
    <text_log remove="1"/>
    <opentelemetry_span_log remove="1"/>
    <asynchronous_metric_log remove="1"/>
    <metric_log remove="1"/>
    <latency_log remove="1"/>
</clickhouse>

Mount ไฟล์ดังกล่าวและรีสตาร์ท ClickHouse

services:
  clickhouse:
    volumes:
      - ./clickhouse-config.d/system-logs.xml:/etc/clickhouse-server/config.d/system-logs.xml:ro

การดำเนินการนี้จะหยุดการเขียนข้อมูลใหม่ แถวข้อมูลที่อยู่บนดิสก์แล้วจะยังคงอยู่ ดังนั้นให้เรียกคืนพื้นที่ด้วยคำสั่ง DROP TABLE IF EXISTS system.trace_log และทำเช่นเดียวกันกับแต่ละตารางที่คุณลบออก หากคุณต้องการเก็บข้อมูลการวินิจฉัยไว้ ทางเลือกอื่นคือการตั้งค่า TTL ที่เข้มงวดในแต่ละตารางแทนการใช้ remove="1" ซึ่งระบุไว้ในเอกสารการขยายระบบของ Langfuse คำสั่ง TTL เหล่านั้นจะมีผลเฉพาะเมื่อมีการสร้างตารางระบบขึ้นใหม่ ดังนั้นสำหรับการติดตั้งที่มีอยู่แล้ว เอกสารชุดเดียวกันจะแนะนำขั้นตอนการปรับปรุงตารางให้รองรับ TTL

มีอีกหนึ่งตารางที่ควรทราบคือ blob_storage_file_log ซึ่งติดตามไฟล์เหตุการณ์ที่อัปโหลดไปยัง bucket ของคุณ หากคุณตั้งค่านโยบาย lifecycle บน bucket ไว้ด้วย ให้กำหนด TTL ให้กับตารางนี้ให้ตรงกัน เพื่อไม่ให้ข้อมูลทั้งสองฝั่งคลาดเคลื่อนกัน

ALTER TABLE blob_storage_file_log MODIFY TTL created_at + INTERVAL 30 DAY DELETE;

ตั้งค่าการแจ้งเตือน df -h บนดิสก์ข้อมูลไว้ด้วย Traces ไม่ได้เติบโตอย่างสม่ำเสมอ แต่จะเพิ่มขึ้นในวันที่คุณปล่อย agent ตัวใหม่ และสัญญาณแรกของเรื่องนี้ไม่ควรเป็นการที่ระบบนำเข้าข้อมูลล้มเหลว

การสำรองข้อมูล Postgres และ ClickHouse

การสำรองข้อมูล Langfuse ประกอบด้วย 3 ส่วน Postgres เก็บข้อมูลผู้ใช้ องค์กร โปรเจกต์ และ API keys ส่วน ClickHouse เก็บข้อมูล traces และ MinIO เก็บข้อมูลเหตุการณ์ดิบ (raw events) หากกู้คืนเฉพาะ Postgres คุณจะเข้าสู่ระบบได้แต่ไม่มีประวัติการใช้งาน หากกู้คืนเฉพาะ ClickHouse คุณจะมีประวัติแต่ไม่มีใครเข้าสู่ระบบเพื่อดูข้อมูลได้ การแยกส่วนนี้ไม่ใช่เรื่องเฉพาะของ Langfuse แต่เป็นลักษณะเดียวกับ ระบบสนับสนุน Chatwoot แบบ self-hosted ซึ่งหากสำรองข้อมูล Postgres โดยไม่มีไดเรกทอรี uploads จะทำให้กู้คืนบทสนทนาได้แต่ไฟล์แนบทั้งหมดจะสูญหาย

Postgres ใช้คำสั่ง pg_dump ซึ่งเป็นวิธีที่เอกสารของ Langfuse แนะนำสำหรับการติดตั้งแบบ Docker

docker compose exec -T postgres pg_dump -U postgres postgres \
  | gzip > langfuse-pg-$(date +%F).sql.gz

ClickHouse ต้องใช้ความระมัดระวังมากกว่า เนื่องจากไดเรกทอรีข้อมูลที่คัดลอกขณะที่ระบบกำลังทำ merges จะไม่ได้ข้อมูลสำรองที่สอดคล้องกัน วิธีที่ง่ายที่สุดสำหรับเซิร์ฟเวอร์เครื่องเดียวคือการหยุด container แล้วทำ archive ของ volume นั้น

docker compose stop clickhouse
docker volume ls | grep clickhouse
docker run --rm -v langfuse_langfuse_clickhouse_data:/data -v "$PWD":/backup alpine \
  tar czf /backup/langfuse-ch-$(date +%F).tar.gz -C /data .
docker compose start clickhouse

ให้ใช้ชื่อ volume ที่ได้จาก docker volume ls อย่าใช้ชื่อที่เขียนไว้ในไฟล์ YAML ไฟล์ดังกล่าวระบุชื่อ langfuse_clickhouse_data แต่ Compose จะเติมชื่อโปรเจกต์นำหน้า ดังนั้นหากคุณ clone ในไดเรกทอรีชื่อ langfuse จะได้ชื่อเป็น langfuse_langfuse_clickhouse_data หากระบุผิด docker run จะสร้าง volume ใหม่ที่ว่างเปล่าโดยไม่มีการแจ้งเตือน และไฟล์ archive ของคุณจะไม่มีข้อมูลใดๆ

Langfuse อัปโหลดข้อมูลเหตุการณ์ดิบไปยัง bucket ในทุกคำขอ ingestion และจะอ่านซ้ำเพื่อลองใหม่หากงาน ingestion ล้มเหลว ดังนั้นการหยุด ClickHouse ในช่วงสั้นๆ หมายความว่า worker จะลองทำงานใหม่หลังจากนั้น ควรดำเนินการในช่วงที่มีผู้ใช้งานน้อยและใช้เวลาให้สั้นที่สุด สำหรับ instance ที่มีงานหนาแน่น คำสั่ง BACKUP DATABASE default TO S3(...) ของ ClickHouse เองสามารถเขียนข้อมูลสำรองที่สอดคล้องกันได้โดยไม่ต้องหยุดเซิร์ฟเวอร์ MinIO เป็นส่วนที่ 3 ซึ่งสามารถใช้ mc mirror หรือการทำ replication ของ MinIO ไปยัง bucket นอกเซิร์ฟเวอร์เพื่อสำรองข้อมูล ไม่ว่าคุณจะใช้วิธีใด ต้องนำข้อมูลออกจากเซิร์ฟเวอร์ ซึ่งเป็นหน้าที่ของ การสำรองข้อมูลด้วย restic แบบเข้ารหัสบน VPS

Redis ทำหน้าที่เก็บคิวและแคช การสูญเสียข้อมูลส่วนนี้จะทำให้งานที่อยู่ในคิวหายไป แม้ว่าไฟล์เหตุการณ์ดิบจะยังคงอยู่ใน bucket ก็ตาม

ข้อควรระวังเรื่องความสอดคล้องของข้อมูลเป็นเรื่องจริงและต้องระบุให้ชัดเจน Postgres และ ClickHouse ถูกสำรองข้อมูลในช่วงเวลาที่ต่างกัน ดังนั้นการกู้คืนอาจทำให้เกิดแถวข้อมูลโปรเจกต์ที่ไม่มี traces หรือ traces ที่เป็นของโปรเจกต์ที่ไม่มีอยู่จริง Langfuse สามารถรองรับสถานการณ์นี้ได้ แต่ควรสำรองข้อมูลทั้งสองส่วนในช่วงเวลาที่ใกล้เคียงกันและในช่วงที่มีการใช้งานน้อย Bucket ที่เก็บเหตุการณ์คือตาข่ายนิรภัยที่แท้จริง เพราะ Langfuse จะอัปโหลดข้อมูลเหตุการณ์ดิบไว้ที่นั่นในทุกคำขอ ingestion

ควรทดสอบการกู้คืนลงใน stack สำรองอย่างน้อยหนึ่งครั้ง นี่คือวิธีที่คุณจะพบข้อผิดพลาดเรื่องชื่อ volume ในตอนนี้ แทนที่จะไปพบในระหว่างที่ระบบล่มจริง

สิ่งที่ควรตรวจสอบเป็นอันดับแรก

มีสี่สิ่งที่ควรให้ความสำคัญในช่วงสัปดาห์แรก

  • ต้นทุนต่อหนึ่ง trace. Langfuse คำนวณต้นทุนจากชื่อโมเดลและการใช้งาน token ดังนั้นให้เรียงลำดับ trace ตามต้นทุนและอ่าน trace ที่มีราคาสูงที่สุดตั้งแต่ต้นจนจบ คำตอบมักจะเป็น prompt ที่ขยายตัวขึ้น เช่น การวางเอกสารทั้งฉบับลงใน context หรือประวัติการสนทนาที่ไม่มีการตัดทอน เมื่อคุณเห็นปัญหาแล้ว การควบคุมต้นทุนของ AI agent จะกลายเป็นงานด้านวิศวกรรมแทนที่จะเป็นการคาดเดา
  • การแบ่งสัดส่วนการใช้งาน token ระหว่าง input และ output. Input token มีจำนวนมากและราคาถูก ส่วน output token มีจำนวนน้อยและราคาสูง ในขณะที่ cached input มีราคาถูกลงไปอีก การคำนวณแบบเดียวกันนี้ถูกอธิบายไว้ใน วิธีการนับ token ของ Claude Code และสามารถนำไปประยุกต์ใช้กับ agent ใดก็ตามที่คุณเขียนขึ้นเอง
  • เปอร์เซ็นไทล์ของ Latency. ค่ามัธยฐานมักจะปิดบังปัญหาที่แท้จริง ค่า p95 และ p99 คือจุดที่เกิดปัญหา timeout และภายในลูปของ agent การเรียกใช้เครื่องมือที่ล่าช้าที่ระดับ p95 จะถูกทวีคูณตามจำนวนรอบการทำงาน
  • การเรียกใช้เครื่องมือที่ล้มเหลว. กรองข้อมูลการสังเกตการณ์ด้วยระดับ ERROR เครื่องมือที่ล้มเหลว 5% ของเวลาทั้งหมดอาจมองไม่เห็นในอัตราความสำเร็จโดยรวม แต่จะเห็นได้ชัดเจนใน trace ซึ่งคุณจะเห็นโมเดลพยายามทำซ้ำและสิ้นเปลือง token ไปกับการแก้ไขปัญหาดังกล่าว

กำหนดระยะเวลาการเก็บรักษาข้อมูลและเลือก dashboard ที่คุณจะตรวจสอบเป็นประจำทุกสัปดาห์ในวันเดียวกับที่คุณ deploy ระบบ เครื่องมือ observability ที่ไม่มีใครเปิดดู ก็เป็นเพียงฐานข้อมูลที่ทำให้ disk เต็มเท่านั้น

FAQ

Langfuse แบบ self-hosted ต้องการหน่วยความจำเท่าใด

ควรเตรียม CPU 4 คอร์ และหน่วยความจำ 16 GiB ตามที่คู่มือ Docker Compose ของ Langfuse แนะนำสำหรับ virtual machine หนึ่งเครื่อง พร้อมพื้นที่จัดเก็บข้อมูลประมาณ 100 GiB ข้อกำหนดขั้นต่ำของแต่ละคอมโพเนนต์ที่ระบุไว้คือ 8 GiB สำหรับ ClickHouse และ 4 GiB สำหรับคอนเทนเนอร์ web และ worker ตามลำดับ หน้าเดียวกันยังระบุว่าต้องใช้ 4 GiB สำหรับ Postgres, 1.5 GiB สำหรับ Redis และ 4 GiB สำหรับ MinIO ซึ่งรวมทั้ง 6 รายการแล้วจะอยู่ที่ 25.5 GiB ซึ่งมากกว่าคำแนะนำ 16 GiB ของ Compose

ทำไมดิสก์ของ ClickHouse ถึงเต็มอยู่เรื่อยๆ ทั้งที่ตั้งค่า data retention แล้ว

การตั้งค่า retention ครอบคลุมเฉพาะข้อมูลของ Langfuse เท่านั้น ClickHouse จะเขียนตารางวินิจฉัยแยกต่างหาก ได้แก่ trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log และ latency_log ซึ่งไม่มีการตั้งค่า TTL มาให้ ให้รัน query system.parts โดยจัดกลุ่มตามชื่อตารางเพื่อดูว่าตารางใดมีขนาดใหญ่ที่สุด จากนั้นให้ปิดการใช้งานตารางที่ไม่จำเป็นด้วยรายการ remove="1" ในไฟล์ภายใต้ /etc/clickhouse-server/config.d/ แล้วรีสตาร์ท ClickHouse จากนั้นจึงลบตารางที่มีอยู่ทิ้งเพื่อคืนพื้นที่ที่ถูกใช้งานไป

ระยะเวลาเก็บรักษาข้อมูลขั้นต่ำใน Langfuse คือเท่าใด

สามวัน การตั้งค่า retention จะทำแยกตามโปรเจกต์ในการตั้งค่าโปรเจกต์ หรือผ่าน Organization Management API โดยจะมีงานที่ทำงานทุกคืนเพื่อลบ trace, observation, score และ media asset ที่เก่ากว่าระยะเวลาที่กำหนดออกจากทั้ง ClickHouse และ blob storage ยกเว้น media ที่เชื่อมโยงกับรายการใน dataset ที่บันทึกไว้ สำหรับ instance แบบ self-hosted ฟีเจอร์นี้เป็นส่วนหนึ่งของ Enterprise Edition ซึ่งต้องใช้ license key หากไม่มี license ข้อมูลจะถูกเก็บไว้โดยไม่มีกำหนด การลบข้อมูลไม่สามารถย้อนกลับได้ ดังนั้นควรตั้งค่าการส่งออกข้อมูลไปยัง blob storage ไว้ก่อนหากต้องการเก็บประวัติย้อนหลังเกินกว่าช่วงเวลาดังกล่าว

จำเป็นต้องสำรองข้อมูลทั้ง Postgres และ ClickHouse หรือไม่

จำเป็น เพราะทั้งสองส่วนเก็บข้อมูลต่างกัน Postgres เก็บข้อมูลผู้ใช้, องค์กร, โปรเจกต์ และ API key ส่วน ClickHouse เก็บข้อมูล trace หากกู้คืนเฉพาะ Postgres คุณจะได้ instance ที่ล็อกอินได้แต่ไม่มีข้อมูลใดๆ อยู่เลย นอกจากนี้ควรสำรองข้อมูลใน MinIO bucket ด้วย เนื่องจากเป็นที่เก็บ raw event ที่ Langfuse บันทึกไว้ทันทีที่ได้รับ ซึ่งถือเป็นแหล่งข้อมูลที่ใกล้เคียงกับแหล่งข้อมูลหลัก (source of truth) มากที่สุดใน stack นี้

สามารถเชื่อมต่อ OpenTelemetry ที่มีอยู่เข้ากับ Langfuse แบบ self-hosted ได้หรือไม่

ได้ Langfuse v4 และ SDK ปัจจุบันถูกสร้างขึ้นบน OpenTelemetry และเครื่องมือวัด (instrumentation) ของ Anthropic และ OpenAI OTel สามารถส่งข้อมูลตรงมาที่นี่ได้ สำหรับ Python ให้รัน pip install langfuse opentelemetry-instrumentation-anthropic, เรียกใช้ AnthropicInstrumentor().instrument() หนึ่งครั้งตอนเริ่มต้นระบบ และตั้งค่า LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY และ LANGFUSE_BASE_URL ไปยัง host ของคุณเอง จากนั้นตรวจสอบด้วย langfuse.auth_check() ก่อนที่จะเริ่มหาสาเหตุหาก dashboard ไม่แสดงข้อมูล

บทความนี้มีประโยชน์หรือไม่