> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logbrew.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Telemetry ứng dụng: log, trace và chỉ số

> So sánh log, trace, chỉ số, vấn đề và hành động sản phẩm. Chọn tín hiệu LogBrew phù hợp cho việc điều tra.

Telemetry là bằng chứng có cấu trúc mà ứng dụng gửi về hành vi của nó. Log ghi
lại các sự kiện được báo cáo. Trace nối các thao tác. Chỉ số đo các giá trị. Vấn
đề nhóm các lỗi. Hành động ghi lại hoạt động trong sản phẩm.

Các trường dự án, dịch vụ, môi trường, bản phát hành và thời gian cho biết phạm
vi của từng kết quả. Để biết SDK của bạn ghi nhận những tín hiệu nào, đọc
hướng dẫn [Tích hợp SDK](/vi/guides/sdk-ingestion).

## <span id="choose-the-correct-telemetry-data-type">Chọn tín hiệu</span>

| Tín hiệu | Dùng cho |
| - | - |
| Vấn đề | Lỗi lặp lại, chẳng hạn một ngoại lệ ở bước checkout xảy ra 18 lần. |
| Log | Một sự kiện mà ứng dụng đã báo cáo, chẳng hạn một lần thanh toán thất bại. |
| Trace | Các thao tác và thời lượng của một yêu cầu qua các dịch vụ đã gắn instrumentation. |
| Chỉ số | Một giá trị đo theo thời gian, chẳng hạn thời lượng yêu cầu hoặc số job đã hoàn tất. |
| Hành động | Hoạt động trong sản phẩm, chẳng hạn lượt xem trang, lượt xem màn hình hoặc tương tác. |

Bắt đầu điều tra lỗi từ vấn đề hoặc log. Dùng trace khả dụng để xem xét một lần
thực thi. Dùng xu hướng của chỉ số để xem xét khoảng thời gian rộng hơn. Về hoạt
động và tỷ lệ quay lại, đọc [Phân tích sản phẩm](/vi/concepts/product-analytics).

Chỉ ghi nhận những trường mà việc điều tra cần. Dùng tên dịch vụ, tên thao tác
và tên chỉ số ổn định. Không gửi thông tin xác thực, dữ liệu thanh toán hoặc
body thô của yêu cầu. Hướng dẫn
[Kiểm soát dữ liệu ghi nhận](/vi/guides/safe-capture) mô tả các cơ chế kiểm soát.

## Log

Log là một bản ghi từ ứng dụng tại một thời điểm. Một log hữu ích có:

* Thời điểm xảy ra sự kiện tại nguồn.
* Một mức độ nghiêm trọng chuẩn.
* Phạm vi dự án và dịch vụ.
* Môi trường và bản phát hành.
* Mã định danh trace và span khi log có ngữ cảnh trace đang hoạt động.
* Các thuộc tính nhỏ, có tên, mang ngữ cảnh của sự kiện.

Phản hồi log chứa các giá trị này trong `occurred_at`, `severity`,
`project_id`, `service_name`, `environment`, `release`, `trace_id`, `span_id`
và `attributes`. Đặt ngữ cảnh vào các thuộc tính có tên, không đặt vào nội dung
thông điệp.

Log từ nhiều dịch vụ hiển thị trong cùng một màn hình không có quan hệ trace với
nhau. Chỉ ngữ cảnh trace mới tạo ra quan hệ đó.

## Trace

Một trace chứa các span của một yêu cầu hoặc thao tác. Span gốc không có span
cha. Span con xác định span cha của nó. Mọi span trong một trace có cùng trace
ID và có span ID khác nhau. Xem
[Distributed tracing](/vi/concepts/distributed-tracing).

Log, vấn đề, hành động hoặc chỉ số được gửi khi không có ngữ cảnh trace đang
hoạt động sẽ nhận một trace ghi nhận. Trace đó chỉ chứa span ghi nhận. Nó không
cho thấy đường đi của yêu cầu. Xem
[Span ghi nhận](/vi/concepts/distributed-tracing#capture-spans).

## <span id="read-the-metric-value">Chỉ số</span>

Chỉ số ghi lại một giá trị đo theo thời gian. Đọc mỗi chỉ số cùng với tên, đơn
vị, chiều dữ liệu (dimension), dự án, khoảng thời gian và khoảng gộp của nó.
LogBrew chọn `value` của từng điểm dựa trên `kind` và `temporality` của chỉ số:

| Quy ước chỉ số | `aggregation.code` | `value` của điểm |
| - | - | - |
| `gauge` với `instant` | `gauge_last` | Trạng thái cuối cùng trong khoảng gộp, chẳng hạn độ sâu hàng đợi. |
| `counter` với `delta` | `delta_sum` | Tổng các thay đổi trong khoảng gộp, chẳng hạn số job đã hoàn tất. |
| `histogram` với `delta` | `distribution_p95` | Phân vị thứ 95 ước tính, chẳng hạn thời lượng yêu cầu. |
| Một luồng `cumulative` | `raw_cumulative_last` | Tổng thô cuối cùng. Đây không phải là tốc độ. |
| Cặp giá trị khác | `raw_last` | Mẫu thô cuối cùng. |

Ví dụ, 3 mẫu delta counter có giá trị `2`, `3` và `5` trong một khoảng gộp cho ra
điểm có `value` là `10` và `sample_count` là `3`. Với 3 mẫu gauge có cùng các giá
trị đó, theo đúng thứ tự đó, điểm có `value` là `5`. Giá trị p95 không phải là
giá trị trung bình. Khoảng 95% số quan sát đã ghi nhỏ hơn hoặc bằng giá trị này.

Với `status: "ready"`, có thể dùng phép tổng hợp đã suy ra. Với
`status: "limited"`, đọc `aggregation.limitation` và chỉ dùng các giá trị thô.
Không cộng dồn gauge hoặc luồng cumulative. Một khoảng gộp không có điểm nào
không có nghĩa là đã đo được giá trị 0. Về các trường truy vấn, đọc
[Bộ lọc truy vấn](/vi/reference/telemetry-api-filters).

`GET /api/telemetry/metrics/series` trả về các điểm này. Endpoint này bắt buộc
có `project_id`, `name` và `since`. Mỗi chuỗi có một `identity` gồm `kind`,
`unit` và `temporality`. Các chuỗi có identity khác nhau được giữ riêng. Mỗi điểm
cũng có thể chứa:

| Trường | Ý nghĩa |
| - | - |
| `min`, `max`, `average` | Khoảng giá trị và giá trị trung bình của các mẫu trong khoảng gộp. |
| `p50`, `p95`, `p99` | Phân vị ước tính cho histogram. |
| `rate_per_second` | Tổng delta counter chia cho độ dài khoảng gộp. |
| `trace_exemplars` | Các trace ID được lấy mẫu từ khoảng gộp. Mở một trace để xem xét một yêu cầu trong khoảng gộp đó. |

`coverage.truncated` là `true` khi `series_limit` đã lược bỏ các chuỗi có lưu
lượng thấp hơn. Để so sánh một khoảng thời gian của chỉ số với khoảng liền trước
có cùng độ dài, chạy:

```bash theme={null}
logbrew explain metric '<metric-name>' --project '<project-id>' --since 24h --json
```

## Vấn đề

Vấn đề nhóm các lỗi lặp lại theo một fingerprint ổn định. Mỗi vấn đề có mức độ
nghiêm trọng, trạng thái, số lần xảy ra, thời điểm lần đầu xuất hiện và thời
điểm lần cuối xuất hiện. Chi tiết vấn đề có thể có thêm chuỗi ngoại lệ, khung
ngăn xếp (stack frame), breadcrumb, log liên quan và quan hệ trace.

`last_seen_at` là lần xảy ra mới nhất trong nhóm. Lần xảy ra mà bạn chọn có thể
cũ hơn. Đọc cả hai thời điểm.

`status` của vấn đề là `unresolved`, `resolved` hoặc `archived`. Phản hồi API
phiên bản 1 hiển thị `archived` thành `ignored`. Phản hồi phiên bản 2 và 3 có
thêm `priority` (`high`, `medium` hoặc `low`) và `priority_source`. Phiên bản 3
có thêm `assignee`. Xem
[Giá trị trạng thái](/vi/guides/issue-workflow#status-values) và
[Mức ưu tiên](/vi/guides/issue-workflow#priority).

## Hành động

Hành động ghi lại hoạt động trong sản phẩm. Phân loại được hỗ trợ sẽ đánh dấu
hành động là lượt xem trang, lượt xem màn hình hoặc tương tác. Tên sự kiện không tự
xác định phân loại. Dùng
[Ghi nhận sự kiện sản phẩm](/vi/guides/product-events) để thêm ngữ cảnh này.

Phiên không phải là người dùng. Chủ thể ẩn danh không phải là người dùng đã định
danh.

## <span id="shared-fields">Trường dùng chung</span>

| Trường | Công dụng |
| - | - |
| `project_id` | Sở hữu telemetry và kiểm soát ranh giới đọc. |
| `service_name` | Xác định ứng dụng hoặc dịch vụ đã gửi tín hiệu. |
| `environment` | Tách dữ liệu production, staging, preview và local. |
| `release` | Xác định phiên bản mã đã triển khai. |
| `occurred_at` | Cho biết thời điểm tại nguồn của một log hoặc hành động. Span dùng `started_at`. |
| `trace_id` | Liên kết các tín hiệu được ghi nhận trong cùng ngữ cảnh trace. |
| `span_id` | Xác định span mà tín hiệu thuộc về trong trace của nó. |

## <span id="severity-values">Giá trị mức độ nghiêm trọng</span>

| Giá trị chuẩn | Bí danh đầu vào được chấp nhận |
| - | - |
| `info` | `trace`, `debug`, `info` |
| `warning` | `warn`, `warning` |
| `error` | `error` |
| `critical` | `fatal`, `critical` |

LogBrew chấp nhận các bí danh này làm đầu vào, không phân biệt chữ hoa chữ
thường. API, CLI và sự kiện trực tiếp dùng các giá trị chuẩn. Giá trị mức độ
nghiêm trọng không xác định sẽ bị từ chối. Mức độ nghiêm trọng là mức khẩn cấp
đã được ghi lại. Nó không cho thấy tác động kinh doanh hay nguyên nhân gốc.

Người dùng có thể đổi mức độ nghiêm trọng hiển thị của một vấn đề hoặc một log.
Khi đó, phản hồi có đối tượng `triage` chứa `effective_severity`. Trường
`severity` giữ giá trị đã ghi nhận.

## Đọc trực tiếp và đọc snapshot

`logbrew read` trả về một snapshot (dữ liệu tại thời điểm đọc) cho dự án, khoảng
thời gian và bộ lọc đã chọn. Chạy lại lệnh để đọc sự kiện mới. `logbrew watch`
truyền liên tục log, vấn đề và hành động mới khi kết nối còn mở. Lệnh này không
truyền trace hay chỉ số. Lỗi kết nối không cho thấy dự án trống.

## <span id="evidence-quality-and-trace-lifecycle">Trạng thái bằng chứng</span>

Phản hồi giữ riêng các trạng thái sau: đã ghi nhận, chưa ghi nhận, đã che, bị cắt
bớt và không khả dụng. Bằng chứng trace có 4 trạng thái: `available`,
`not_linked`, `not_found` và `unavailable`. Xem trang
[Tổng quan](/vi/introduction#follow-exact-relationships) để biết ý nghĩa
của chúng, và
[Giới hạn của bằng chứng](/vi/introduction#read-evidence-states-before-drawing-a-conclusion)
để biết các trường về độ bao phủ. SDK mới hơn không thêm trường vào các sự kiện
mà nó đã gửi trước đó.

## <span id="a-practical-investigation">Điều tra một dự án</span>

<Steps>
  <Step title="Tìm vấn đề chưa giải quyết">
    ```bash theme={null}
    logbrew read issues --project '<project-id>' --status unresolved --since 24h --json
    ```
  </Step>

  <Step title="Đọc một vấn đề">
    Lệnh này đọc lịch sử vấn đề được giữ lại. Bộ lọc `--since` của danh sách
    không áp dụng ở đây.

    ```bash theme={null}
    logbrew investigate issue '<issue-id>' --json
    ```
  </Step>

  <Step title="Mở trace khả dụng">
    Chỉ dùng trace ID khi lần xảy ra đã chọn có trả về trace ID.

    ```bash theme={null}
    logbrew read trace '<trace-id>' --project '<project-id>' --json
    ```
  </Step>

  <Step title="Đọc bằng chứng liên quan">
    Lọc log, hành động và chỉ số theo cùng dự án, dịch vụ, môi trường và bản
    phát hành. Không liên kết các tín hiệu chỉ dựa vào thời gian.
  </Step>
</Steps>

Về các trường trong phản hồi, đọc [Telemetry API](/vi/reference/telemetry-api) và
[Định dạng phản hồi](/vi/reference/telemetry-response-shapes).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.