Metrics bằng OpenTelemetry

Traces cho thấy một request, logs cho thấy code đã ghi gì. Metrics cho thấy một con số theo thời gian: số request mỗi giây, bộ nhớ đang dùng, số job đang chờ trong hàng đợi, số kết nối còn trống trong pool. Belvador nhận metrics từ SDK OpenTelemetry chuẩn và Collector qua OTLP/HTTP, lưu một điểm mỗi phút trên node của chính bạn, rồi cho bạn vẽ biểu đồ và đặt cảnh báo.

Metrics mặc định tắt. Chúng tốn request và có hạn mức tháng riêng, nên bạn bật ở chỗ nào cần.

Bật metrics#

1. Ingest key. Ở Cài đặt project → Ingest key, tích Metrics cho khoá mà dịch vụ đang dùng (hoặc tạo khoá mới có quyền này). Khoá không có quyền này nhận 403.

2. Exporter. Trong bộ biến chuẩn, bật exporter metric:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.belvador.dev/otlp/<project-id>export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobufexport OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20<your-ingest-key>export OTEL_TRACES_EXPORTER=otlpexport OTEL_LOGS_EXPORTER=otlpexport OTEL_METRICS_EXPORTER=otlpexport OTEL_METRIC_EXPORT_INTERVAL=60000export OTEL_SERVICE_NAME=my-serviceexport OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production

Xuất mỗi phút một lần (60 giây): Belvador giữ một điểm mỗi phút, xuất dày hơn chỉ thêm request. Cả hai kiểu temporality đều được — cumulative (mặc định của mọi SDK) và delta.

3. Node của bạn lưu metrics từ agent 0.1.37 trở lên; node tự cập nhật. Trước đó, metrics chờ ở edge, được mã hoá bằng khoá của node, và được giao sau khi cập nhật.

Đã kiểm ngày 2026-10-27 với otelcol-contrib 0.163.1, telemetrygen v0.163.0: traces đạt, logs đạt, metrics đạt.

Lượt chạy Collector gửi một metric cho mỗi loại bên dưới rồi đọc lại từ node. SDK OpenTelemetry gửi cùng định dạng OTLP, nhưng Belvador chưa chạy exporter metric của chúng, nên chúng chưa được đánh dấu đã kiểm cho metrics. Công thức cho metrics máy chủ, hàng đợi, nghiệp vụ và Supabase: Công thức metrics.

Những gì được lưu#

Điểm Summary không được lưu; chúng được đếm là Loại metric không hỗ trợ (mọi SDK hiện nay xuất histogram thay thế). Bộ đếm cumulative được đổi thành phần tăng mỗi phút trên node; bộ đếm khởi động lại (sau một lần deploy) đếm tiếp từ giá trị mới thay vì hiện một cú giảm âm.

Xem metrics#

Trang Metrics liệt kê các metric project đã gửi, kèm loại, đơn vị và số chuỗi. Chọn một metric, rồi:

• Phép tổng hợp — avg, sum, min, max, count, rate (mỗi giây, cho bộ đếm và histogram), hoặc p50/p90/p95/p99 (histogram). Bộ đếm mở với rate, histogram với p95, mức với trung bình.

• Bộ lọc — tối đa 5 điều kiện thuộc tính, giống ở Traces và Logs.

• Nhóm theo — tối đa 2 khoá thuộc tính; mỗi bộ giá trị là một đường trên biểu đồ (vẽ 50 nhóm đầu).

• Bước — từ một điểm mỗi phút tới một điểm mỗi ngày. Một truy vấn bao tối đa 7 ngày và 10,000 điểm.

Điểm histogram có exemplar khi SDK ghi chúng: trace của một request trong bucket đó. Bấm vào để mở trace.

Giới hạn giữ chi phí dễ đoán#

Một chuỗi (series) là một tên metric với một bộ giá trị thuộc tính. Số chuỗi mới là thứ tốn đĩa và bộ nhớ, nên node giới hạn nó:

Điểm của chuỗi mới vượt giới hạn không được lưu và được đếm là Vượt giới hạn chuỗi; chuỗi đã có vẫn chạy bình thường, và trang Metrics nêu tên các metric chạm giới hạn. Nguyên nhân thường gặp là một thuộc tính có giá trị không giới hạn — user id, mã đơn hàng, URL đầy đủ. Để chúng ở span và log, còn metric chỉ dùng thuộc tính ít giá trị (http.route, không phải URL).

Trang Metrics cho thấy node đang giữ bao nhiêu chuỗi và tên so với giới hạn; thời gian lưu và lượng mỗi tháng nằm ở Cài đặt project → Traces, logs và metrics đã nhận.

Quyền riêng tư#

Thuộc tính metric đi qua cùng quy tắc quyền riêng tư với thuộc tính span trước khi tạo chuỗi: thuộc tính bị bỏ không bao giờ thành một phần của chuỗi, thuộc tính bị băm thì nhóm theo giá trị băm. Giá trị chỉ nằm trên node của bạn. Cơ sở dữ liệu của Belvador chỉ nhận số đếm và dung lượng mỗi ngày, không bao giờ nhận tên, giá trị hay giá trị thuộc tính.

Cảnh báo theo metric#

Tạo monitor Metric ở Monitor → Tạo monitor, hoặc bấm Tạo monitor trên trang Metrics để mang truy vấn đang xem sang. Monitor tổng hợp một metric trong một cửa sổ (ví dụ p95 của http.server.request.duration trong 5 phút trên 0,8 giây) và cảnh báo khi vượt trên, dưới hoặc ra ngoài một khoảng. Khi có nhóm theo, mỗi bộ giá trị được xét riêng, nên một route chậm cảnh báo mà không kéo theo các route khác. Xem Monitor theo tín hiệu.

Từ API hoặc AI agent#

GET /v1/metrics/names, GET /v1/metrics/series và GET /v1/metrics/query đọc cùng dữ liệu với token có metrics:read; tool MCP query_metrics liệt kê metric khi không có tên và truy vấn một metric khi có tên. Xem tham chiếu API và MCP.

Những gì không có#

• Không có metrics từ trình duyệt. Ingest key là bí mật; web vitals sẽ đến sau qua SDK trình duyệt, không qua OTLP.

• Không có endpoint Prometheus. Prometheus và các nguồn khác được Collector đọc rồi chuyển tiếp dạng OTLP.

• Không lưu dài hạn. Điểm được giữ theo thời gian lưu của gói ở độ phân giải một phút; không có thu gọn dữ liệu để giữ nhiều năm.