Tự host Superlog: footprint, Docker và giới hạn thực tế
Tìm hiểu Superlog cài gì trên VPS: Postgres, ClickHouse, OpenTelemetry collector và 4 Node service, cùng cách pin commit khi repo chưa có release tag.
Những gì việc tự host Superlog thực sự cài đặt
Để tự host Superlog, bạn clone repository, khởi động Postgres, ClickHouse và một OpenTelemetry collector bằng Docker Compose, chạy một lần database migration, sau đó khởi động 4 Node service từ source. Ứng dụng của bạn gửi trace, log và metric OTLP (giao thức OpenTelemetry) đến một intake port. Superlog fingerprint chúng, nhóm các bản ghi lặp lại thành một incident duy nhất, rồi default community agent runner ghi lại bản tóm tắt incident cục bộ. Quá trình cài đặt mất một buổi chiều. Footprint và các giới hạn thực tế là những phần đáng đọc trước khi bắt đầu.
Superlog được cấp phép theo Apache 2.0 và nằm tại github.com/superloglabs/superlog. Tính đến ngày 13 October 2026, dự án có khoảng 1.5k star, khoảng 490 commit trên main và hoàn toàn không có release tag. Hãy tự pin một commit thay vì chạy bất kỳ phiên bản nào mà main đang trỏ tới vào buổi sáng bạn clone repository.
Superlog trả lời được điều gì mà Uptime Kuma và Langfuse không trả lời được
Các công cụ monitoring tự host nhìn bên ngoài có vẻ thay thế cho nhau. Thực tế không phải vậy, và chọn sai công cụ sẽ làm tốn tài nguyên server mà không đem lại lợi ích.
- Uptime Kuma kiểm tra các endpoint của bạn từ bên ngoài và trả lời một câu hỏi: dịch vụ có đang hoạt động không.
- Zabbix theo dõi host và service trên Ubuntu 24.04, gồm CPU, memory, disk và trạng thái service theo các ngưỡng bạn đặt.
- Langfuse trace các lệnh gọi LLM, ghi lại prompt, model, token, độ trễ và chi phí của từng lệnh gọi.
- Superlog nhận telemetry mà các service thông thường của bạn đã phát ra, rồi chuyển các lỗi lặp lại thành incident.
Superlog trả lời một câu hỏi khác: có thứ gì đó bị lỗi, vậy lỗi gì và tại sao. Superlog không tập trung vào các lệnh gọi LLM và không kiểm tra hệ thống của bạn từ bên ngoài. Nó ingest OTLP từ code ứng dụng thông thường của bạn và đặt một agent vào bước triage. Đây cũng là bước kiểm tra đầu tiên mà người trực on-call sẽ thực hiện.
Điểm khác biệt quan trọng đối với ngân sách VPS là storage. Superlog có column store vì telemetry được ghi một lần, sau đó được truy vấn theo khoảng thời gian trên hàng triệu row. Đây là mục đích của ClickHouse, còn Postgres thì không phù hợp. Postgres vẫn nằm trong stack để lưu dữ liệu quan hệ nhỏ: project, user, incident và ingest key.
docker compose up -d thực sự khởi động những gì?
Ba container, và không container nào là Superlog. Điều này thường gây bất ngờ cho những người mong đợi cài đặt chỉ bằng một lệnh.
postgres:16, được publish trên cổng 5434 của hostclickhouse/clickhouse-server:26.1, dùng cổng 8123 cho HTTP và 9000 cho native protocolotel/opentelemetry-collector-contrib:0.150.1, dùng cổng 4317 cho gRPC và 4318 cho OTLP qua HTTP
Các ứng dụng Superlog chạy trên host từ source và được khởi động bởi pnpm dev. Tính đến ngày 13 October 2026, repository không có compose file dành cho production. Vì vậy, để chạy lâu dài, bạn cần tự tạo các systemd unit hoặc dùng các Dockerfile riêng cho từng app có sẵn trong cây source. Các app api, worker và proxy đều có script start để một unit gọi bọc bên ngoài. Web app không có script này. Đây là một app Vite, nên bạn build nó bằng script build rồi phục vụ output dưới dạng static files từ nginx hoặc Caddy, hoặc chạy script preview của nó, tức là vite preview.
Hãy ghi nhớ đường đi của một span, vì mỗi lỗi bên dưới đều là lỗi xảy ra tại một bước trong đường đi đó. App của bạn gửi OTLP đến Superlog intake proxy. Proxy xác thực request bằng ingest key của bạn, gắn project id vào request rồi chuyển tiếp đến collector. Collector loại bỏ mọi thuộc tính superlog.* mà client cố gắng tự đặt, thêm superlog.project_id lấy từ header do proxy cung cấp, gom batch rồi ghi dữ liệu vào ClickHouse. Web app và API đọc telemetry từ ClickHouse, còn mọi dữ liệu khác được đọc từ Postgres.
Việc loại bỏ thuộc tính này là một cơ chế kiểm soát multi-tenancy thực sự, không phải phần trang trí. Nếu không có cơ chế đó, bất kỳ ai có một ingest key hợp lệ đều có thể tự đặt superlog.project_id và ghi dữ liệu vào project khác.
Cần VPS có cấu hình bao nhiêu?
Với lưu lượng ingest thấp, hãy dự trù 4 vCPU, 8 GB RAM và 40 GB SSD cho một node duy nhất. Đây là mức tối thiểu để lập kế hoạch, không phải số đo thực tế. Hãy dùng nó làm cấu hình ban đầu và đối chiếu với lưu lượng của bạn.
RAM được dùng cho 4 nhóm chính. ClickHouse được thiết kế cho các máy có nhiều RAM và các giá trị mặc định cũng giả định như vậy. Postgres 16 không cần nhiều RAM trong trường hợp này vì nó chỉ lưu metadata, không lưu telemetry. Collector cũng không cần nhiều RAM. 4 tiến trình Node gồm một Vite development server và 3 tiến trình tsx watch. Hãy đo mức sử dụng RAM trên chính máy của bạn.
Disk là vấn đề khó nhận thấy hơn. pnpm install trong monorepo này kéo về AWS SDK, một ClickHouse client, OpenTelemetry SDK và một React toolchain trước khi bạn ingest một span nào. Sau đó ClickHouse tiếp tục tăng theo lưu lượng. Hãy đo cả 2 yếu tố:
df -h /
free -m
docker stats --no-stream
docker compose exec clickhouse clickhouse-client --database superlog --query "SELECT table, formatReadableSize(sum(bytes_on_disk)) AS size FROM system.parts WHERE active AND database = 'superlog' GROUP BY table ORDER BY sum(bytes_on_disk) DESC"Tải gây ảnh hưởng lớn nhất là các đợt tăng đột biến: một lần deploy lỗi tạo ra hàng nghìn error giống nhau mỗi phút. Fingerprinting gộp các error đó thành một incident để người đọc dễ theo dõi, nhưng ClickHouse vẫn ghi từng row bên dưới.
Bạn tự quyết định thời gian lưu dữ liệu. ClickHouse exporter của collector tạo các table, otel_traces, otel_logs và một table cho mỗi loại metric. Exporter chỉ áp dụng thời gian tự xóa dữ liệu nếu config trong infra/collector/config.yaml đặt giá trị này. Không có dữ liệu nào tự hết hạn, nên một tháng có lưu lượng cao có thể làm đầy disk nếu bạn không lập kế hoạch lưu trữ.
Cài đặt từ commit đã cố định
git clone https://github.com/superloglabs/superlog.git
cd superlog
git tag -l
git log -1 --format='%H %cs %s'git tag -l không in gì là kết quả đúng tính đến ngày 13 October 2026. Chọn commit bạn đã kiểm thử và giữ nguyên commit đó:
git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1eTiếp theo là toolchain:
node -v
corepack enable
corepack prepare pnpm@9.12.0 --activate
pnpm -vpackage.json khai báo engines.node là >=20.0.0 và packageManager là pnpm@9.12.0. Node version không tương thích không tự động khiến quá trình cài đặt dừng lại: việc kiểm tra engine phụ thuộc vào cấu hình, và pnpm 9.12.0 có nhánh cảnh báo khi engineStrict bị tắt. Gói nodejs trong kho Ubuntu 24.04 cũ hơn version 20, nên hãy cài Node 20 hoặc mới hơn từ NodeSource hoặc nvm. Repository có một .nvmrc, vì vậy nvm use sẽ chọn version được chỉ định nếu bạn dùng nvm.
pnpm install
docker compose up -d
docker compose psHãy chờ health check thay vì coi up -d là dấu hiệu service đã sẵn sàng. Postgres và ClickHouse đều khai báo health check trong compose file:
curl -sS http://127.0.0.1:8123/ping
pg_isready -h 127.0.0.1 -p 5434 -U postgresClickHouse phản hồi tại Ok. và pg_isready phản hồi tại accepting connections. Connection refused trên 8123 nghĩa là container vẫn đang khởi động hoặc đã bị dừng. docker compose logs clickhouse cho biết trường hợp nào xảy ra, còn docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled báo true khi kernel đã kill container do thiếu memory. Điều này cho thấy máy quá nhỏ, không phải cấu hình của bạn bị sai.
Tiếp theo là migration và các ứng dụng:
pnpm --filter @superlog/db db:migrate
pnpm devLưu ý port: 5434, không phải 5432. Compose file publish Postgres trên 5434 để không xung đột với Postgres đã cài trên host, và các file .env.example của app cũng dùng port này, với DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog. Nếu trỏ migration đến 5432 trên máy đã chạy Postgres, bạn có thể gặp connection refused hoặc nghiêm trọng hơn là migration được áp dụng vào nhầm database.
pnpm dev chạy turbo run dev. Lệnh này khởi động script dev của từng app thông qua Turborepo, gồm api, web, worker và proxy, đồng thời trộn output của chúng trong cùng một terminal. Repository có Procfile liệt kê cùng 4 process và ghi output của từng process vào tmp/logs/. Hãy khởi động bằng Procfile runner như overmind hoặc foreman thay cho pnpm dev nếu bạn muốn tail -f tmp/logs/proxy.log là nơi theo dõi ingest. README đặt web app trên http://localhost:5173, API trên http://localhost:4100 và OTLP intake trên http://localhost:4101.
Hãy xác nhận process thực sự đã bind port nào trước khi trỏ thành phần khác vào đó:
ss -lntp | grep -E '4000|4100|4101|5173'
curl -sS http://127.0.0.1:4101/healthĐiều này sẽ quan trọng ở bước sau. Proxy đọc port của chính nó từ biến môi trường PORT và dùng 4000 nếu PORT chưa được đặt. apps/proxy/.env.example mà proxy load cũng đặt PORT=4000, dù README liệt kê intake trên 4101 (cả hai đều được kiểm tra ngày 13 October 2026). Hãy dùng port mà ss hiển thị. Các ví dụ bên dưới dùng 4101, nên thay bằng 4000 nếu đó là port đã bind. Một systemd unit do bạn tự viết sẽ không tự đặt giá trị nào trừ khi bạn thêm PORT vào unit. Vì vậy, exporter trỏ đến 4101 trong khi proxy đang listen trên 4000 sẽ fail với connection refused và không cung cấp thêm manh mối nào.
Gửi một trace, tạo một lỗi, xem một incident
Tạo một project trong web app và sao chép ingest key của project đó. Intake xác thực mọi request bằng key này, vì vậy telemetry được gửi mà không có key sẽ không bao giờ đến ClickHouse.
Trỏ bất kỳ OpenTelemetry SDK nào đến intake bằng các biến môi trường tiêu chuẩn:
export OTEL_SERVICE_NAME=checkout-api
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4101
export OTEL_EXPORTER_OTLP_HEADERS='x-api-key=YOUR_INGEST_KEY'Intake đọc key từ header x-api-key và cũng chấp nhận authorization: bearer YOUR_INGEST_KEY nếu exporter của bạn dễ cấu hình theo cách đó hơn. Intake phục vụ 3 path OTLP tiêu chuẩn là /v1/traces, /v1/logs và /v1/metrics, cùng với /health.
Có một lỗi dễ mắc cần nói rõ. OTEL_EXPORTER_OTLP_ENDPOINT là base URL và SDK sẽ nối signal path vào đó. Các biến dành riêng cho từng signal như OTEL_EXPORTER_OTLP_TRACES_ENDPOINT được dùng nguyên văn, không nối thêm path. Nếu đặt biến dành riêng cho signal thành http://127.0.0.1:4101 thì mọi lần export sẽ gửi đến /. Đây không phải route, nên không có dữ liệu nào đến nơi và SDK ghi log export failure trong khi app của bạn vẫn có vẻ hoạt động bình thường.
Với một service Node, không cần thêm code cũng đủ để xác nhận pipeline:
npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
node --require @opentelemetry/auto-instrumentations-node/register server.jsBây giờ cố ý làm hỏng một thứ. Bất kỳ route nào phát sinh exception đều được:
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/boomKiểm tra các chặng theo thứ tự, vì khoảng trống đầu tiên cho biết chặng nào đã fail:
tail -n 50 tmp/logs/proxy.log
docker compose exec clickhouse clickhouse-client --database superlog --query 'SELECT count() FROM otel_traces'Nếu số lượng trong otel_traces tăng nhưng web app trống, đó là project mismatch. Hãy kiểm tra ingest key thuộc project nào. Nếu số lượng không đổi nhưng proxy log có hoạt động, vấn đề nằm ở collector hoặc bước ghi vào ClickHouse; hãy đọc docker compose logs collector. Nếu proxy log hoàn toàn không có hoạt động, exporter chưa đến được intake: sai port, sai path hoặc key bị từ chối.
Trong web app, các failure lặp lại này xuất hiện dưới dạng một incident thay vì một row cho mỗi request. Superlog tạo fingerprint cho các signal đến và nhóm những signal khớp nhau. Nhờ đó, inbox chứa 4,000 lỗi giống hệt nhau được gom thành một page duy nhất. Community agent runner mặc định sau đó ghi một bản tóm tắt incident cục bộ cho nhóm đó.
Một cuộc điều tra dùng model cần được cấu hình model provider và agent runner tương thích; runner cộng đồng mặc định sẽ ghi một bản tóm tắt cục bộ. Hãy lấy tên các biến đó từ file .env.example bên trong thư mục của từng app thuộc commit bạn đã pin, thay vì lấy từ bất kỳ tài liệu bên ngoài nào, vì chúng thay đổi theo main. Điều tương tự cũng áp dụng cho các integration GitHub và Sentry. Mỗi integration có tài liệu setup riêng tại docs/github-app-setup.md và docs/sentry-app-setup.md, còn webhook payload được mô tả tại docs/webhooks.md.
Giữ endpoint tiếp nhận ở chế độ private và chỉ cho agent quyền read
Docker mặc định publish các cổng của container trên 0.0.0.0, và các cổng này bypass ufw. Docker định tuyến traffic của container trong bảng nat, nên packet gửi đến một cổng đã publish bị chuyển hướng trước khi đến các chain INPUT và OUTPUT, nơi chứa rule của ufw. Vì vậy ufw không thể xử lý traffic này. Trên VPS có public IP, file compose mặc định publish ClickHouse HTTP trên cổng 8123 và Postgres trên cổng 5434, khiến Internet có thể truy cập chúng. Credential trong file đó là giá trị mặc định cho môi trường development: user ClickHouse là default với password trống, còn Postgres dùng postgres làm cả user và password.
Bind các cổng đó vào loopback. Mỗi cổng được publish trong file compose lấy phía host từ một biến môi trường, nên chỉ cần tạo file .env ở thư mục gốc của repository:
POSTGRES_HOST_PORT=127.0.0.1:5434
CLICKHOUSE_HTTP_HOST_PORT=127.0.0.1:8123
CLICKHOUSE_TCP_HOST_PORT=127.0.0.1:9000
COLLECTOR_GRPC_HOST_PORT=127.0.0.1:4317
COLLECTOR_HTTP_HOST_PORT=127.0.0.1:4318Xác minh kết quả trước khi tin cậy cấu hình, sau đó recreate các container:
docker compose config
docker compose up -d
ss -lntp | grep -E '5434|8123|9000|4317|4318'docker compose config in ra file đã được resolve, nên bạn có thể đọc 127.0.0.1:5434:5432 thay vì đoán. Khi đó ss phải hiển thị 127.0.0.1:5434 và không được hiển thị 0.0.0.0:5434. Chỉ khai báo lại ports trong file override của Compose sẽ giữ cả hai binding khi IP của host khác nhau; Compose 2.24.4 trở lên hỗ trợ ports: !override để thay thế cả list.
Endpoint tiếp nhận cũng cần được bảo vệ tương tự. Ingest key được gửi trong header, nên cần có TLS (transport layer security) ở phía trước: terminate TLS bằng nginx hoặc Caddy trước proxy, hoặc giữ ingest trong private network hay một tunnel WireGuard. Web app trên cổng 5173 là Vite development server và hoàn toàn không nên public ra Internet.
Tiếp theo là chính agent. Điểm chính Superlog đưa ra là agent sẽ điều tra và đề xuất cách khắc phục; từ quan trọng là “đề xuất”. Hãy giữ agent ở chế độ read only đối với production cho đến khi bạn đã theo dõi nó xử lý một vài incident thực tế. GitHub App chỉ có quyền read không thể push fix branch hoặc mở pull request: hướng dẫn thiết lập yêu cầu quyền write cho Contents và Pull requests trong workflow đó, cùng quyền write cho Issues để đăng comment. Agent đọc telemetry và ghi patch là hữu ích. Agent có thể restart service là một mức rủi ro khác, và bạn nên chủ động quyết định việc này thay vì nhận mặc định. Chi phí cũng cần được cân nhắc tương tự khi cấu hình runner dùng model: hãy lập ngân sách cho chi phí agent trên VPS trước khi trỏ nó vào hệ thống production nhiều log và sự kiện, đồng thời ghi lại những gì agent thực sự đã làm để pull request bất ngờ luôn có audit trail đi kèm.
Các lỗi bạn sẽ gặp và chuỗi thông báo dùng để xác định chúng
ERR_PNPM_UNSUPPORTED_ENGINEtrong lúcpnpm installnghĩa là yêu cầu của engine không tương thích. pnpm 9.12.0 kiểm tra cả yêu cầu của Node và pnpm; đọc phiên bản yêu cầu và phiên bản hiện tại trong lỗi, sau đó kiểm tranode -vvàpnpm -v.ECONNREFUSED 127.0.0.1:5434trong lúc migration nghĩa là compose stack chưa chạy, hoặcDATABASE_URLđang trỏ đến sai port.- Kiểm tra việc ClickHouse restart bằng
docker compose logs clickhouse, sau đó kiểm tra container để xác nhậnOOMKilledđang ở trạng tháitrue. - Exporter báo thành công nhưng web app vẫn trống thường có nghĩa là dữ liệu đã đi thẳng đến collector tại 4318, bỏ qua bước gắn project mà proxy thực hiện.
- Lỗi connection refused trên 4101 thường có nghĩa là proxy đang listen trên 4000, đây là port mà code của nó dùng làm giá trị fallback và cũng là port được
.env.examplethiết lập. ĐặtPORTmột cách rõ ràng trong unit file hoặc.envcủa app. docker compose pshiển thị0.0.0.0:8123nghĩa là các binding trên loopback chưa có hiệu lực. Chạydocker compose configvà đọc các port đã được resolve.
Flawless, HyperProbe và vị trí của Superlog
Danh mục này còn mới, và các công cụ khác nhau ở phạm vi mà agent được phép can thiệp. Repository Flawless hiện giới thiệu CISRE, một nền tảng AI SRE (site reliability engineering) cho Kubernetes và hạ tầng cloud, theo giấy phép PolyForm Noncommercial. HyperProbe đặt probe bên trong một process đang chạy để thu thập trạng thái biến, rồi cung cấp trạng thái đó cho assistant qua MCP (model context protocol); tài liệu của công cụ cũng hướng dẫn self-hosting bằng Docker Compose và license key.
Superlog nằm giữa hai công cụ này. Nó tự quản lý toàn bộ pipeline, từ tiếp nhận OTLP đến lưu trữ trong ClickHouse, đồng thời đặt agent ở bước triage thay vì bước fix. Đây chính là lý do self-hosting Superlog là một quyết định về hạ tầng, không phải chỉ chạy một container rồi quên đi. Khi chạy Superlog, bạn đang vận hành một column store, và nó cần được chăm sóc như mọi database khác mà bạn sở hữu.
FAQ
Superlog self-host cần bao nhiêu RAM?
Dự trù 8 GB RAM, 4 vCPU và 40 GB disk cho một node với lưu lượng ingest thấp. Stack gồm Postgres, ClickHouse, một OpenTelemetry collector và 4 tiến trình Node; ClickHouse cũng cần thêm headroom. Hãy đo các chỉ số thực tế của bạn bằng docker stats --no-stream và free -m thay vì tin vào bất kỳ con số nào được công bố, kể cả con số trong tài liệu này.
Tôi cần trỏ OTLP exporter vào cổng nào?
Hãy trỏ vào intake proxy của Superlog, được README cấu hình trên http://localhost:4101. Proxy này cung cấp /v1/traces, /v1/logs và /v1/metrics, đồng thời xác thực bằng ingest key của project lấy từ header x-api-key hoặc header authorization: bearer. Cổng 4318 là nơi OpenTelemetry collector bên dưới lắng nghe. Export trực tiếp đến đó sẽ bỏ qua proxy, trong khi proxy là thành phần gắn project id vào dữ liệu. Proxy dùng cổng 4000 khi PORT chưa được thiết lập. .env.example cũng đặt cổng là 4000, vì vậy hãy chạy ss -lntp và xác nhận process đã bind vào cổng nào trước khi mặc định dùng 4101.
Superlog có thay thế được Uptime Kuma hoặc Zabbix không?
Không. Uptime Kuma kiểm tra một endpoint có phản hồi từ bên ngoài network của bạn hay không. Zabbix theo dõi metric của host và service theo các threshold bạn đặt. Superlog nhận trace, log và metric do ứng dụng phát ra, rồi nhóm các lỗi lặp lại thành incident. Hãy dùng thêm một external uptime probe, vì một probe chạy ở nơi khác vẫn có thể báo cáo khi chính máy chủ chứa telemetry pipeline của bạn bị dừng.
Superlog agent có thể thay đổi hệ thống production của tôi không?
Chỉ khi bạn cấp quyền cho nó. Community runner mặc định ghi lại bản tóm tắt incident cục bộ. Các investigation runtime khác phụ thuộc vào runner bạn cấu hình. Hãy giới hạn credential production ở quyền đọc. Việc mở pull request cần quyền ghi GitHub riêng cho branch và pull request. Hãy xem quyền ghi vào production là một quyết định riêng cần cân nhắc. Agent có thể restart service có mức rủi ro và cam kết lớn hơn nhiều so với agent chỉ đọc telemetry và tạo patch để review.
Tôi nên pin một commit hay theo dõi main?
Hãy pin một commit. Tính đến 13 October 2026, repository chưa có release tag. Ghi lại SHA bạn đã test, deploy đúng commit đó và đọc diff trước khi nâng cấp. git log --oneline <old-sha>..main là phần review. Các file .env.example theo từng app là nơi đầu tiên cần kiểm tra để tìm các biến mới bắt buộc sau mỗi lần bump.