Thiết lập Observability Cloud

hango luôn gửi trace, metric và log tới container Grafana LGTM chạy cục bộ. Nó cũng có thể gửi chúng tới Grafana Cloud và gửi trace tới Langfuse Cloud. Mỗi cloud được bật bằng một biến trong .env. Khi biến đó chưa được đặt, collector không gửi gì tới cloud đó.

Đích đến	Tín hiệu	Bật bởi	Gói miễn phí
lgtm cục bộ (`localhost:3000`)	trace, metric, log	luôn bật	không áp dụng
Grafana Cloud	trace, metric, log	`GRAFANA_CLOUD_INSTANCE_ID`	Free: 10k metric series, 50 GB log, 50 GB trace mỗi tháng, lưu 14 ngày
Langfuse Cloud	trace	`LANGFUSE_PUBLIC_KEY`	Hobby: 50k đơn vị mỗi tháng, lưu 30 ngày

Nội dung prompt, completion và tool luôn bị xóa trước khi dữ liệu tới lgtm hoặc Grafana Cloud. Langfuse chỉ nhận nội dung này trên những span mang hango.tenant.trace_llm_content=true (kiểu boolean). Span không có attribute đó sẽ bị lọc bỏ (các span mang nội dung xuất hiện ở giai đoạn 3).

Trước khi bắt đầu

cp .env.example .env

Điền giá trị bằng cách bỏ comment các dòng trong .env. Hãy để dòng ở dạng comment thay vì đặt giá trị rỗng. Collector coi giá trị rỗng là đã đặt, nên nó bỏ qua giá trị mặc định có sẵn và có thể không chịu khởi động với lỗi at least one endpoint must be specified.

Langfuse Cloud

Đăng ký tại cloud.langfuse.com (vùng EU) hoặc us.cloud.langfuse.com (vùng US). Dữ liệu nằm ở vùng bạn chọn.
Tạo một organization, rồi một project, ví dụ hango-dev.
Mở Settings của project, rồi API Keys, và tạo một cặp key. Sao chép public key (pk-lf-...) và secret key (sk-lf-...). Secret chỉ hiện một lần.

Trong .env, đặt:

LANGFUSE_BASE_URL=https://cloud.langfuse.com    # or https://us.cloud.langfuse.com
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...

Áp dụng thay đổi. Lệnh restart thường không đọc lại .env, nên hãy tạo lại collector:
```
docker compose up -d --force-recreate otelcol
```
Gửi một request bằng curl -i localhost:8080/readyz, rồi mở Tracing trong project Langfuse. Trace GET /readyz sẽ xuất hiện trong vòng một phút.

Grafana Cloud

Đăng ký tại grafana.com và tạo một stack. Tên stack trở thành <name>.grafana.net, và vùng bạn chọn là nơi lưu dữ liệu.
Trong portal của Grafana Cloud, mở stack của bạn và tìm ô OpenTelemetry. Chọn Configure.
Trang đó hiển thị OTLP endpoint (ví dụ https://otlp-gateway-prod-us-east-0.grafana.net/otlp) và instance ID (một con số). Tạo một API token ngay tại đó. Nó tạo ra một access policy token có quyền ghi metric, log và trace. Hãy sao chép lại, vì nó chỉ hiện một lần.

Trong .env, đặt:

GRAFANA_CLOUD_OTLP_ENDPOINT=https://otlp-gateway-prod-<region>.grafana.net/otlp
GRAFANA_CLOUD_INSTANCE_ID=123456
GRAFANA_CLOUD_API_TOKEN=glc_...

Tạo lại collector:

docker compose up -d --force-recreate otelcol

Gửi một request, sao chép X-Trace-Id của nó, và mở https://<name>.grafana.net/explore. Dùng data source trace của stack (tên dạng grafanacloud-<name>-traces) và dán trace id vào. Dùng data source log với {service_name="hango"} và data source metric với go_memory_used_bytes. Metric đến mỗi 10 giây.

Kiểm tra collector

docker compose logs otelcol | grep -E "Everything is ready|Exporting failed"

Log	Ý nghĩa	Cách sửa
`Everything is ready` và không có lỗi	Đang chạy tốt, hoặc một cloud đang tắt	Kiểm tra biến bật đã được bỏ comment trong `.env` chưa
`Exporting failed` từ `otlp_http/langfuse` với `HTTP Status Code 401`	Langfuse từ chối các key	Kiểm tra lại cả hai key và xem `LANGFUSE_BASE_URL` có khớp vùng của project không
`Exporting failed` từ `otlp_http/grafanacloud` với `HTTP Status Code 401`	Grafana Cloud từ chối instance ID hoặc token	Tạo lại token từ ô OpenTelemetry và chắc rằng ID thuộc cùng stack
`at least one endpoint must be specified`	Một biến endpoint được đặt nhưng rỗng	Comment dòng đó lại hoặc cho nó một giá trị

Công tắc hoạt động thế nào

Cấu hình collector không thể bật tắt một pipeline, nên mỗi cloud có một filter processor ở đầu các pipeline của nó. Với Grafana Cloud, điều kiện là "${env:GRAFANA_CLOUD_INSTANCE_ID:-}" == "". Khi biến chưa được đặt, điều kiện thành "" == "" và đúng với mọi phần tử, nên mọi thứ trên pipeline đó bị bỏ trước khi tới exporter. Khi biến đã được đặt, điều kiện sai và dữ liệu đi qua. Điều kiện chỉ dùng ID hoặc public key, nên token không bao giờ xuất hiện trong một biểu thức mà collector có thể ghi log. Xem deploy/otelcol/config.yaml.

Kiến trúc hệ thống Sơ đồ