Logs and Monitoring — Traffic Tools Ecosystem

Mục lục Toàn Diện

1. Tổng quan Kiến trúc & Nguyên lý Thiết kế

Vì hệ thống Traffic Tools quản lý cùng lúc 12+ Servers Worker, xoay hàng vạn lượt Proxy và tạo ra hàng triệu Click / Report Sessions mỗi ngày. Do đó, Logging Pipeline không được dựa trên CSDL SQL (để tránh bóp nghẹt I/O). Thay vào đó, nó được thiết kế thuần dựa trên file vật lý phân tán, được giám sát gián tiếp qua grep hoặc gửi HTTP streaming.

Ba nguyên lý thiết kế chính:

Zero-blocking: Cả Go API (Zap) lẫn Bun (CoreLogger) đều ghi bất đồng bộ (Async write), không cản trở tốc độ execution của goroutine hay event-loop.

Deterministic Layout: Tên thư mục phản ánh Channel: /logs/channel_name/YYYY-MM-DD/log.log. Giúp Dev dễ cô lập lỗi (ví dụ proxy log tách hẳn với system log).

Action Context Validation (Structured): Cấm in log theo dạng chuỗi + nối vào nhau. Buộc phải truyền qua Object/Interfaces.

2. Hệ thống Log Backend (API Golang)

Kiến trúc `go.uber.org/zap` & `loggerCache`

API (Go) gói package zap nổi tiếng. Thay vì mỗi luồng request gọi zap.New(), file pkg/logger/logger.go dùng Map Memory Cache và RWMutex để đảm bảo Thread-safe.

Chuẩn Format & Level Markers

Khi Dev chạy hàm logger.Error("some text"), hàm wrap sẽ tiêm vào LevelMarker độc quyền để công cụ parse (Filebeat/ELK) dễ tách data.

[LOG_LEVEL_ERROR] — Lỗi logic nghiệp vụ, Lỗi HTTP Timeout

[LOG_LEVEL_WARN] — Lỗi xoay proxy hụt, hoặc data tạm thời sai

[LOG_LEVEL_INFO] — Cronjob tick

[LOG_LEVEL_DEBUG] — Payload trace

Cách dùng `ErrorWithFields` trong Golang

API buộc Dev phải dùng hàm ErrorWithFields nếu muốn gắn error type apperror.AppError hoặc context. Code framework sẽ tự break context map[string]interface{} thành các Field của Zap (zap.Any), chèn tự động LOG_ERROR_CODE và gán prefix LOG_DATA:.

Kết quả in ra file sẽ như sau (rất gọn và parse JSON log mượt mà):

{"level":"error","time":"23/03/2026 10:15:30","caller":"task/service.go:42","msg":"[LOG_LEVEL_ERROR] Failed database query","LOG_ERROR_MESSAGE":"record not found","LOG_ERROR_CODE":"404_NOT_FOUND","LOG_DATA:task_id":"Tk_992"}

Audit Logs: User Activity & Task Result

Ngoài text log, API sử dụng 2 bảng MongoDB để Tracking các hành động quan trọng (như Audit Trail cho Admin UI):

Activity Log (activity_log module): Bất cứ ai thực hiện Thêm/Sửa/Xóa Dự án, Login, Thay đổi Key Proxy sẽ được lưu thành bản ghi: {user_id, action, target_type, module, user_agent, ip, timestamp}. Đây là UI "Lịch sử thao tác" trong Admin.

Task Log (task_log module): Khi 1 task Traffic fail, thay vì lưu chi tiết vào DB SQL nặng nề, nó tống gọn 1 dòng vào task_logs ở MongoDB: {task_id, err_reason, date, worker_id}.

3. Hệ thống Log Worker (Tools V2 - Bun/TS)

Khác với API Golang, Tools V2 điều khiển headless Chrome (Puppeteer) vốn dễ bị OutOfMemory, Crash. Do đó Log của Tools V2 phức tạp hơn rất nhiều.

Hierarchy & `CoreLogger` File Structure

Cấu trúc logger của Tools V2 là Dạng Cây (Tree-based). Log gốc (Root app) có hàm .child(service_name). Khi khởi tạo .child("ads_click"), log sẽ ghi vào thư mục con storage/log/ads_click/YYYY-MM-DD/info.log.

Cấu hình ENV tại tools_v2/.env:

LOG_LEVEL=info (Có thể set = debug nếu Dev muốn thấy DOM node Puppeteer)

LOG_WRITE_TO_FILE=true (Luôn luôn bật tại Prod để lưu trace)

LOG_DIR=storage/log

Tự động Nhóm Lỗi (`ErrorCategorizer`)

Vì Puppeteer trả về rất nhiều Exception dị thường, Tools V2 cung cấp file src/utils/logger/error-categorizer.ts. Nhiệm vụ của nó là nhìn vào Message text và tự gạch chân lỗi:

ErrorGroup.NETWORK: Tức là lỗi ECONNREFUSED, ETIMEDOUT

\to

Thường xảy ra do Proxy đứt. Quyết định: Cắm lại Proxy đổi IP. Tích cờ retryable = true.

ErrorGroup.DATABASE: Mất kết nối Mongoose. Chờ DB sống lại.

ErrorGroup.VALIDATION: Format sai do cấu hình Admin. Quyết định: Thả bom Task này làm Failed luôn, hủy Retry (retryable = false).

Structured Logging cho APIs & OpenAI GPT

StructuredLogger trong Bun có các Helper Method dành riêng cho các thành phần tốn tiền (Billing):
1. ChatGPT Logging (logGptPrompt):
Ghi nhận đầy đủ Prompt và kết quả trả về của OpenAI. Phục vụ việc Audit lại AI lỡ trả về text vớ vẩn trong Email Report:

2. Webhook & API Calls Logging (logApiCall / logWebhook): Theo dõi các Request POST Push/Pull traffic về Core API Golang. Nếu statusCode = 502, sẽ tự phân loại lỗi thành SERVER_ERROR.

Theo dõi luồng Browser Manager (`Puppeteer`)

Kênh log quan trọng bậc nhất là browser_manager. Bất cứ khi nào:

browserManager.launch()

browserManager.close()

browserManager.checkMemoryLimit()
Đều được in vào channel này. Khi bị crash do nghẽn RAM, file browser_manager/error.log sẽ cho biết Page URL cuối cùng là gì.

4. Monitoring System — Giám sát Sức khỏe

Traffic Tools không dùng Grafana / Prometheus (vì muốn hệ thống tinh gọn không cài quá nhiều phần mềm bên thứ 3). Thay vào đó, nó tận dụng HTTP API + SQL để dựng Monitoring.

Công cụ Monitor Hệ điều hành (Tools V2 `/api/monitor`)

Tất cả Server Worker chạy Tools V2 đề phơi ra Endpoint GET /api/monitor. Endpoint dùng Native lib OS của Bun/Node:

CPU: Tính % Load qua os.loadavg() chia cho tổng số Cấu hình lõi os.cpus().

RAM: Lấy os.totalmem() - os.freemem() chuyển đổi ra GB/MB cho Admin biết Server này còn dư RAM để mở thêm Cửa sổ Puppeteer không.

DISK: Đọc Bun.file("/").stat() kiểm tra dung lượng còn trống. Phải trên 1GB để Chrome có chỗ lưu Cache.

APP LIMITS: Trả về số phiên Chrome đang chạy (browserManager.sessionsCount) vs BROWSER_LIMIT.

Logic Tính RAM, Disk, CPU Load Average

Báo cáo Hiệu năng Server hàng giờ (API)

Golang xử lý Job mạnh mẽ: SCHEDULE_SERVER_HOURLY_REPORT
Hàng giờ (00:00, 01:00,...), Go Cron sẽ lướt bảng Task trong 1 tiếng vừa qua, group theo server_ip.

Đếm Task_Success.

Đếm Task_Fail.

Lưu vào MySQL table server_hourly_report.
Nhờ thế, nếu Server A tỷ lệ Fail là 90%, Server B tỷ lệ Fail là 5% (cùng 1 Task), ta biết ngay Server A đã hỏng Proxy Pool hoặc Core Network.

Tracking trạng thái Project (Project Dead)

Golang có Cronjob thần thánh: SCHEDULE_CHECK_PROJECT_DEAD (chạy mỗi 5 phút).

Query các Project đang Status = RUNNING.

Truy xuất bảng Project_Detail lấy thời điểm Traffic cuối cùng hoàn thành.

Nếu quá (PROJECT_DEAD_TIME_MINUTES = 30 phút) mà không có thêm traffic

\to

Tự Set status thành DEAD.

Bắn Notification về Đội trưởng điều hành qua Telegram/Mattermost đi vào sửa target link/keyword.

5. Cảnh báo & Alerts System

Kiến trúc Alert của hệ thống nằm ở API Golang module Telegram Handler pkg/telegram.

Ma trận Thông báo Telegram (Error, Report, General)

Hệ thống tạo 1 Bot duy nhất bằng TELEGRAM_BOT_TOKEN, nhưng điều tiết tin nhắn nhúng vào 3 Channel ID khác nhau nhằm chống Spam người dùng.

Kênh ENV ID	Đối Tượng Nhận	Kích hoạt khi	Trích đoạn Payload Code
`TELEGRAM_CHAT_ID`	Leader / Quản lý	Dự án Dead, hoặc Đổi Cấu hình, Start/Stop Bot.	`msg := fmt.Sprintf("⚠️ Dự án %s đã chết (Không traffic trong %v phút)", name, min)`
`TELEGRAM_CHAT_ERROR_ID`	DevOps Team	Crash hệ thống, Lỗi kết nối MongoDB, Cạn kiệt nguồn ZingProxy.	Chạy hàm `telegram.SendErrorAlert(err, "MongoDB Connection", ip)`
`TELEGRAM_CHAT_REPORT_ID`	Sales / Kế toán	Tổng kết traffic ngày.	File đính kèm CSV. Export hàm Excel qua Bot API `sendDocument`.

Luồng kết nối Mattermost Webhook

Trường hợp Mạng nội bộ chặn Telegram (Server chính phủ, Tập đoàn), hệ thống có phương án B với biến ENV MATTERMOST_API_URL & MATTERMOST_CHANNEL_ID.
Tương đương cơ chế JSON Webhook:

Lịch gửi Báo cáo tự động bằng MATTERMOST_SCHEDULE (Default 0 0 9 * * * = Sáng 9h hằng ngày).

Kích hoạt bắn POST Request đính kèm File Binary multipart/form-data Excel Data (Data: Traffic tổng chốt ngày).

6. Cẩm nang Trace Log & Troubleshooting Giải quyết Lỗi

Để giải quyết một lỗi phức tạp lây lan từ Tools V2 lên API. Ta làm theo SOP (Standard Operating Procedure) sau:

Case Study: Khách khóc vì Traffic Ads không click được.

Bước 1: Tìm Task ID bị lỗi

Mở Admin UI

\to

Vào mục Task Logs.

Filter Project ID đang phàn nàn

\to

Filter Trạng thái "Thất bại/Fail". Copy một Task ID_123 cụ thể.

Bước 2: Tìm gốc Worker xử lý

Nhìn cột "Worker IP" trên Dashboard ứng với Task đó (ví dụ Worker 11.0.3.45).

Bước 3: Mổ Log Puppeteer (Tools V2)

Mở file tools_v2/storage/log/task/2026-x-x/error.log.

Dùng lệnh CLI Grep:
grep "Task ID_123" storage/log/task/2026-x-x/error.log

Bạn sẽ thấy Log Structure ghi rõ ERROR TYPE:
{"errorCategory": "VALIDATION_ERROR", "errorMessage": "Cannot find element matching selector #ad-banner"}.

\to

Lỗi là do Dev FrontEnd của Domain đích đã đổi tên Class/ID của thẻ Quảng Cáo. Hệ thống DOM Puppeteer click hụt. Quá nhàn để Fix!

Case Study: Proxy xoay bị kẹt đứng System

Mở Log API Go: tail -f logs/system/2026-03-23/log.log | grep LOG_LEVEL_ERROR

Bạn thấy: LOG_DATA:provider="ZingProxy" LOG_ERROR_CODE:"401".

\to

Lỗi báo Token ZingProxy hết hạn hoặc hết tiền trong ví ZingProxy. Xử lý lập tức nạp tiền! Không cần Trace code.

Rules for Developer Khi Ghi Log:

❌ KHÔNG ĐƯỢC: logger.info("Hoàn thành task " + taskId + " với rank " + rank)

\to

Hư string matching.

✅ BẮT BUỘC DÙNG: logger.info("Hoàn thành task", { task_id: taskId, rank: rank })

\to

ElasticSearch Index được giá trị mảng.

Logs and Monitoring

Logs and Monitoring — Traffic Tools Ecosystem#

Mục lục Toàn Diện#

1. Tổng quan Kiến trúc & Nguyên lý Thiết kế#

2. Hệ thống Log Backend (API Golang)#

Kiến trúc go.uber.org/zap & loggerCache#

Chuẩn Format & Level Markers#

Cách dùng ErrorWithFields trong Golang#

Audit Logs: User Activity & Task Result#

3. Hệ thống Log Worker (Tools V2 - Bun/TS)#

Hierarchy & CoreLogger File Structure#

Tự động Nhóm Lỗi (ErrorCategorizer)#

Structured Logging cho APIs & OpenAI GPT#

Theo dõi luồng Browser Manager (Puppeteer)#

4. Monitoring System — Giám sát Sức khỏe#

Công cụ Monitor Hệ điều hành (Tools V2 /api/monitor)#

Logic Tính RAM, Disk, CPU Load Average#

Báo cáo Hiệu năng Server hàng giờ (API)#

Tracking trạng thái Project (Project Dead)#

5. Cảnh báo & Alerts System#

Ma trận Thông báo Telegram (Error, Report, General)#

Luồng kết nối Mattermost Webhook#

6. Cẩm nang Trace Log & Troubleshooting Giải quyết Lỗi#