Tham chiếu endpoint OTLP
Đường dẫn, xác thực, Content-Type, nén, mã phản hồi, Retry-After và giới hạn của mỗi request OTLP/HTTP gửi tới Belvador.
Belvador nhận traces, logs và metrics OpenTelemetry qua OTLP/HTTP, theo đặc tả OTLP 1.x. Exporter nào làm đúng đặc tả đều dùng được; trang này liệt kê đường dẫn, quy tắc và giới hạn của Belvador.
Endpoint#
https://ingest.belvador.dev/otlp/<project-id>Khi bạn đặt OTEL_EXPORTER_OTLP_ENDPOINT, exporter tự thêm /v1/traces, /v1/logs và /v1/metrics. Nếu bạn dùng biến riêng cho từng loại (OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT), hãy ghi URL đầy đủ có cả /v1/traces, /v1/logs hoặc /v1/metrics. Metrics cần khoá đã tích Metrics (Metrics).
Xác thực#
Authorization: Bearer <ingest key>Khoá (bvi_…) được tạo ở Cài đặt project → Khoá ingest, thuộc về một project và ghi rõ các loại dữ liệu được gửi. Request mang header Origin của trình duyệt bị từ chối, nên khoá lỡ nằm trong code front-end cũng vô dụng với người tìm thấy nó. Thu hồi khoá có hiệu lực trong vòng 60 giây.
Định dạng#
| Chấp nhận | |
|---|---|
| Phương thức | POST |
Content-Type | application/x-protobuf (nên dùng) hoặc application/json |
Content-Encoding | không nén hoặc gzip |
| Kênh truyền | Chỉ HTTPS; không nhận gRPC trực tiếp — hãy dùng Collector |
Phản hồi#
| Mã | Nghĩa là | Exporter nên |
|---|---|---|
| 200 | Đã nhận và lưu bền ở edge (thân trả về rỗng). | Không làm gì. Bản ghi vẫn có thể bị node bỏ sau đó — xem Mức dùng. |
| 400 | Thân không phải OTLP hợp lệ. | Không gửi lại; sửa exporter. |
| 401 | Thiếu khoá, khoá sai định dạng hoặc đã thu hồi. | Không gửi lại; kiểm OTEL_EXPORTER_OTLP_HEADERS. |
| 403 | Khoá không thuộc project này, thiếu quyền signal (ví dụ chưa tích Metrics), gọi từ trình duyệt, hoặc workspace đang tạm dừng nhận. | Không gửi lại; dùng khoá đúng project/signal ở máy chủ. |
| 404 | Đường dẫn không tồn tại. | Không gửi lại; endpoint kết thúc bằng /otlp/<project-id>, exporter tự thêm /v1/traces, /v1/logs, /v1/metrics. |
| 413 | Thân lớn hơn 4 MiB (đã nén). | Giảm kích thước batch. |
| 415 | Content-Type hoặc Content-Encoding không hỗ trợ. | Dùng http/protobuf hoặc http/json, nén gzip hoặc không nén. |
| 429 | Vượt tốc độ hoặc hạn mức tháng. | Gửi lại sau Retry-After (thường 1 s). |
| 503 | Edge tạm không nhận (bộ đệm của node đầy, sự cố tạm thời). | Gửi lại sau Retry-After (30 s). |
Phản hồi thành công có thân rỗng ({} với JSON). Belvador không trả số đếm partial success của OTLP: 200 nghĩa là request đã được lưu bền ở edge, sau đó node kiểm từng bản ghi. Bản ghi bị bỏ được đếm theo lý do ở Cài đặt project → Traces, logs và metrics đã nhận (ý nghĩa từng lý do).
429 và 503 có Retry-After. Exporter chuẩn gửi lại các mã này, cùng 502 và 504, với thời gian chờ tăng dần; exporter có sẵn của Deno thì không (chi tiết).
Giới hạn#
| Giới hạn | Giá trị |
|---|---|
| Thân request (đã nén) | 4 MiB |
| Thân sau giải nén | 16 MiB |
| Tỉ lệ nén tối đa | 32× |
| Bản ghi mỗi request | 8192 |
| Thuộc tính mỗi span/log/resource | 128 |
| Độ dài khoá thuộc tính | 256 byte |
| Giá trị chuỗi của thuộc tính | 16 KiB |
| Thân log | 64 KiB |
| Event / link mỗi span | 128 / 128 |
| Thời điểm nhận được | 7 ngày trước đến 5 phút sau |
Giá trị vượt giới hạn thuộc tính và thân log bị cắt và kết thúc bằng …[truncated]; thuộc tính vượt số lượng bị bỏ. Cả hai đều được đếm, phần còn lại của bản ghi vẫn được giữ.
Thuộc tính resource Belvador đọc#
| Thuộc tính | Dùng cho |
|---|---|
service.name | Dịch vụ trong Traces, Logs và tab Kết nối (mỗi project liệt kê theo tên tối đa 200 dịch vụ) |
deployment.environment.name | Bộ lọc môi trường; nếu không có tên mới thì đọc deployment.environment |
telemetry.sdk.name, telemetry.sdk.language, telemetry.sdk.version | Cột SDK của Bằng chứng theo tín hiệu |
belvador.verification_id (trên span hoặc log) | Đánh dấu một lần kiểm kết nối |
Thấy chỗ sai hoặc thiếu? Gửi cho chúng tôi: hello@belvador.dev