Không thấy traces hoặc logs: cách tìm nguyên nhân

Theo từng triệu chứng: không có dữ liệu, 401/403, 413, 429, có root mà thiếu span con, log không gắn trace, dev chạy mà production trống.

Bản Markdown

Trong bài này

Không thấy gì cả
Exporter báo lỗi HTTP
Nhận 200 nhưng thiếu bản ghi
Có span gốc nhưng thiếu span con
Có log nhưng không gắn với trace
Chạy ở dev, production trống

Đi theo triệu chứng bạn thấy. Phần lớn vấn đề hiện ở một trong ba chỗ: đầu ra của chính app (lỗi exporter), tab Kết nối của project, và Cài đặt project → Traces, logs và metrics đã nhận, nơi liệt kê phần bị bỏ và lý do.

Không thấy gì cả#

Bộ lọc. Traces mở ở một giờ gần nhất và Logs ở 15 phút gần nhất, theo môi trường bạn chọn lần trước. Mở rộng khoảng thời gian và chọn Mọi môi trường.
Tên dịch vụ. Kiểm OTEL_SERVICE_NAME — thiếu thì hiện là unknown_service (một số SDK thêm tên tiến trình phía sau).
Exporter chưa từng chạy. Với Node.js ES modules là thiếu loader hook (Node.js); với Python là app không được chạy qua opentelemetry-instrument; với Go là setupOTel chưa được gọi trước khi server chạy.
Tiến trình thoát trước. Script và job ngắn phải gửi nốt trước khi thoát — xem ghi chú tắt tiến trình ở từng trang cài đặt.
Lấy mẫu. OTEL_TRACES_SAMPLER_ARG=0.01 chỉ giữ một trace trong một trăm; đặt 1 khi thử.
Sức khoẻ node. Nếu node đang tắt, traces và logs chờ ở edge tối đa 15 phút và hiện ra khi node kết nối lại; quá thời gian đó chúng bị bỏ là Hết hạn trong bộ đệm. Fleet cho biết trạng thái node.

Sau đó bấm Kiểm kết nối OTLP ở tab Kết nối: nếu kiểm đạt mà dữ liệu của app vẫn không tới, vấn đề nằm ở phần cài trong app, không phải đường truyền.

Exporter báo lỗi HTTP#

Mã	Nguyên nhân thường gặp	Cách sửa
`401`	Thiếu khoá, gõ sai hoặc đã thu hồi; hoặc `Bearer` và khoá không cách nhau bằng `%20` trong `OTEL_EXPORTER_OTLP_HEADERS`	Chép lại khối biến ở Cài đặt → Khoá ingest
`403`	Khoá của project khác, khoá chưa tích Traces, Logs hay Metrics, hoặc request đến từ trình duyệt	Dùng khoá phía máy chủ của đúng project, đúng loại dữ liệu
`404`	Sai đường dẫn	Endpoint phải kết thúc bằng `/otlp/<project-id>`; exporter tự thêm `/v1/traces`, `/v1/logs` và `/v1/metrics`
`413`	Một lô lớn hơn 4 MiB	Giảm cỡ lô (`OTEL_BSP_MAX_EXPORT_BATCH_SIZE`, `OTEL_BLRP_MAX_EXPORT_BATCH_SIZE`)
`415`	Định dạng không hỗ trợ	Dùng `http/protobuf` hoặc `http/json`; gRPC cần một Collector phía trước
`429`	Hết hạn mức tháng, hoặc gửi quá nhanh	Xem thẻ: hạn mức đặt lại hằng tháng, giới hạn tốc độ hết sau vài giây; exporter tự gửi lại
`503`	Edge tạm thời không nhận, hoặc node tắt quá lâu	Exporter gửi lại sau `Retry-After`; xem Fleet

Mọi mã và giới hạn: Tham chiếu OTLP.

Nhận `200` nhưng thiếu bản ghi#

200 nghĩa là edge đã lưu bền request; sau đó node kiểm từng bản ghi. Bản ghi nó không giữ được được đếm trong Traces, logs và metrics đã nhận → Bị bỏ trong 30 ngày, theo lý do:

Lý do	Nghĩa là
Sai định dạng	Bản ghi không đúng định dạng OTLP
Thời điểm nằm ngoài khoảng cho phép	Cũ hơn 7 ngày hoặc ở tương lai — kiểm đồng hồ máy gửi
Ngoài phạm vi của khoá	Khoá không cho phép loại dữ liệu hoặc môi trường này
Bị bỏ bớt thuộc tính / Giá trị bị cắt ngắn	Quá nhiều thuộc tính, hoặc giá trị vượt giới hạn; phần còn lại của bản ghi vẫn được giữ
Hết hạn trong bộ đệm	Chờ ở edge quá 15 phút trong lúc node tắt
Bị xoá sớm (ổ đĩa node đầy)	Loại dữ liệu vượt phần ổ đĩa của nó; ngày cũ bị xoá trước hạn lưu
Loại metric không hỗ trợ	Điểm OTLP Summary, không được lưu — hãy xuất histogram thay thế
Vượt giới hạn chuỗi	Chuỗi hoặc tên metric mới vượt giới hạn của node — xem giới hạn metrics

Có span gốc nhưng thiếu span con#

Instrumentation được nạp sau các thư viện nó cần vá. Với Node.js, cờ register phải nằm trên dòng lệnh (hoặc NODE_OPTIONS), không import ở giữa code; với ES modules thì cần cả loader hook. Với Python, chạy qua opentelemetry-instrument và cài gói instrumentation của thư viện đó. Một số thư viện không có instrumentation nào — phần việc của chúng hiện là thời gian bên trong span cha.

Có log nhưng không gắn với trace#

Lệnh ghi log chạy ngoài context của request. Với Go, dùng các hàm …Context với context của request. Với Node.js, dùng logger đã được nối (Pino, Bunyan, Winston kèm transport) thay vì console.log. Logger chỉ chèn trace ID vào chữ của thông điệp thì không nối được — ID phải là trường của bản ghi log, việc mà các cầu nối làm.

Chạy ở dev, production trống#

Production hay dùng lệnh khởi động khác (thiếu cờ hoặc opentelemetry-instrument), tên môi trường khác, hoặc khoá khác. So Bằng chứng theo tín hiệu ở tab Kết nối cho cả hai môi trường — nó cho biết dịch vụ, SDK và lần cuối thấy của từng bên.

Thấy chỗ sai hoặc thiếu? Gửi cho chúng tôi: hello@belvador.dev