# 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

```text
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](https://belvador.dev/vi/docs/otel/metrics)).

## Xác thực

```text
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](https://belvador.dev/vi/docs/otel/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](https://belvador.dev/vi/docs/otel/troubleshooting#nhan-200-nhung-thieu-ban-ghi)).

`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](https://belvador.dev/vi/docs/otel/deno#gioi-han-khong-gui-lai)).

## 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](https://belvador.dev/vi/docs/otel/quickstart#4-kiem-ket-noi) |