# Gửi traces và logs đầu tiên

> Tạo khoá ingest, đặt biến môi trường OTEL_* chuẩn, chạy app với instrumentation của runtime và kiểm kết nối OTLP từ trong Belvador.

Ba bước: một khoá, bộ biến OpenTelemetry chuẩn, và instrumentation của runtime. Không có đoạn code riêng của Belvador nào ở đây — SDK OpenTelemetry hay Collector nào xuất OTLP/HTTP cũng làm giống nhau.

## 1. Tạo khoá ingest

Mở project, vào **Cài đặt → Khoá ingest → Tạo khoá ingest**. Đặt tên (ví dụ tên dịch vụ hoặc máy), tích **Traces** và **Logs**, và nếu muốn thì giới hạn vào một số môi trường — bản ghi của môi trường khác khi đó bị bỏ.

Khoá bắt đầu bằng `bvi_` và chỉ hiện **một lần**. Đây là bí mật chỉ dùng để gửi dữ liệu: giữ nó trong biến môi trường hoặc kho bí mật của máy chủ, không bao giờ đặt trong code chạy trên trình duyệt (edge từ chối request đến từ trình duyệt). Mỗi project có tối đa 10 khoá ở gói mặc định; thu hồi một khoá sẽ chặn mọi nơi gửi dùng nó trong vòng 60 giây.

## 2. Đặt các biến chuẩn

Mọi SDK OpenTelemetry đều đọc các biến này. Thay `<project-id>` và chỗ giữ khoá; thẻ **Khoá ingest** hiện sẵn khối này với project ID của bạn.

```bash
export OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.belvador.dev/otlp/<project-id>
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20<your-ingest-key>
export OTEL_TRACES_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=none
export OTEL_SERVICE_NAME=my-service
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production
```

- `OTEL_SERVICE_NAME` là tên dịch vụ trong Traces, Logs và tab **Kết nối**. Mỗi thứ triển khai riêng dùng một tên.
- `deployment.environment.name` là môi trường (`production`, `staging`, …) — cùng ý nghĩa với môi trường của lỗi, nên bộ lọc khớp nhau.
- Giá trị header được mã hoá phần trăm (`%20` là dấu cách sau `Bearer`), như đặc tả OpenTelemetry yêu cầu với biến này.
- Metrics tắt ở đây vì có hạn mức tháng riêng. Muốn gửi, xem [Metrics](https://belvador.dev/vi/docs/otel/metrics#bat-metrics).

## 3. Chạy với instrumentation của runtime

| Runtime | Cần thêm |
|---|---|
| [Node.js](https://belvador.dev/vi/docs/otel/node) | Ba gói và một cờ `--require` (CommonJS) hoặc `--import` (ES modules) |
| [Python](https://belvador.dev/vi/docs/otel/python) | `opentelemetry-distro`, rồi chạy app qua `opentelemetry-instrument` |
| [Go](https://belvador.dev/vi/docs/otel/go) | Một hàm setup, `otelhttp` và `otelslog` |
| [Java](https://belvador.dev/vi/docs/otel/java) | OpenTelemetry Java agent qua `-javaagent` |
| [Deno](https://belvador.dev/vi/docs/otel/deno) | `OTEL_DENO=true` |
| Ngôn ngữ khác | Cho app gửi tới một [Collector](https://belvador.dev/vi/docs/otel/collector) cạnh nó, Collector chuyển tiếp |

Sau đó gửi một request qua app. Traces hiện trong **Traces** và logs trong **Logs** sau vài giây; exporter gom dữ liệu vài giây rồi mới gửi.

## 4. Kiểm kết nối

Mở tab **Kết nối** của project. **Bằng chứng theo tín hiệu** cho biết traces và logs được thấy lần cuối khi nào, từ dịch vụ và SDK nào. Để chứng minh trọn đường đi, bấm **Kiểm kết nối OTLP**:

1. Belvador hiện một lệnh `curl` có mã đánh dấu mới. Chạy nó từ máy nào ra được internet, thay chỗ giữ khoá bằng khoá ingest của bạn. Lệnh gửi một span và một log mang thuộc tính `belvador.verification_id`.
2. Bảng theo dõi từng bước: **Đã gửi từ máy của bạn → Edge của Belvador đã nhận → Node của bạn đã lưu biên nhận → Đọc lại được từ node**.

SDK của bạn cũng làm được như vậy: span hay log nào có thuộc tính `belvador.verification_id` bằng mã đánh dấu đều được tính. Kiểm đạt chứng minh khoá này, project này, môi trường này tới được node vào lúc đó — không chứng nhận runtime, cũng không chứng minh mọi dịch vụ đã được gắn instrumentation.

## Nếu không thấy gì

Bắt đầu từ [Sửa lỗi kết nối](https://belvador.dev/vi/docs/otel/troubleshooting). Nguyên nhân hay gặp nhất là khoảng thời gian hoặc bộ lọc môi trường sai, khoá chưa tích **Traces** hay **Logs**, và tiến trình thoát trước khi exporter kịp gửi.