> ## 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.

# Tích hợp SDK để gửi telemetry ứng dụng

> Chọn SDK LogBrew cho runtime của bạn. Cấu hình khóa gửi dữ liệu. Gửi telemetry ứng dụng và tìm sự kiện thử trong dự án.

Cài đặt gói SDK LogBrew cho runtime của bạn. SDK định dạng sự kiện và gửi
chúng đi. Hướng dẫn của từng gói liệt kê các loại sự kiện, giới hạn và cách
thử lại của gói đó.

Làm các bước sau cho mỗi tích hợp:

1. Cài đặt gói SDK cho runtime của bạn.
2. Giữ khóa gửi dữ liệu theo phạm vi dự án bên ngoài hệ thống quản lý mã nguồn.
3. Đặt giá trị dịch vụ, môi trường và bản phát hành ổn định.
4. Gửi một sự kiện thử an toàn từ ứng dụng.
5. Đọc kết quả gửi. Sau đó tìm sự kiện trong LogBrew.

Một batch được chấp nhận nghĩa là batch đó đã đến API LogBrew. Bộ lọc vẫn có
thể ẩn các sự kiện của nó. Chọn đúng dự án và khoảng thời gian. Sau đó khớp
dịch vụ, môi trường, bản phát hành và loại tín hiệu.

Trước khi bật ghi nhận dữ liệu, [chọn và kiểm tra các trường đã duyệt](/vi/guides/safe-capture).
Để có dữ liệu cho Phân tích, làm theo [Ghi nhận sự kiện sản phẩm](/vi/guides/product-events).

## <span id="item-types">Tín hiệu và ngữ cảnh dùng chung</span>

Năm thẻ đầu tiên là tín hiệu. Bản phát hành và môi trường là ngữ cảnh cho các
tín hiệu đó. Chúng không phải một loại sự kiện riêng.

<CardGroup cols={2}>
  <Card title="log" icon="file-text">
    Một thông điệp có cấu trúc, kèm mức độ nghiêm trọng, nguồn, thời gian và
    ngữ cảnh an toàn.
  </Card>

  <Card title="trace_span" icon="route">
    Một thao tác có đo thời gian, liên kết với trace của nó qua trace ID và span
    ID.
  </Card>

  <Card title="issue" icon="bug">
    Một lỗi đã ghi nhận, mức độ nghiêm trọng của lỗi và chi tiết lỗi mà ứng
    dụng đã gửi.
  </Card>

  <Card title="action" icon="mouse-pointer-click">
    Một hành động trong ứng dụng của bạn, có thể kèm chủ thể, phiên và thuộc
    tính an toàn.
  </Card>

  <Card title="metric" icon="chart-line">
    Một phép đo dạng số có tên, loại, giá trị, đơn vị và temporality.
  </Card>

  <Card title="bản phát hành và môi trường" icon="tags">
    Phiên bản mã và môi trường được gắn vào các sự kiện gửi sau đó trong cùng
    phạm vi SDK.
  </Card>
</CardGroup>

## Giá trị mức độ nghiêm trọng

Dùng `info`, `warning`, `error` hoặc `critical` cho log và vấn đề. SDK và
runtime có thể gửi bí danh như `trace`, `debug`, `warn` hoặc `fatal`.
LogBrew chuẩn hóa các bí danh được chấp nhận về giá trị chuẩn.

## Cài đặt bằng trình quản lý gói

Cài đặt gói SDK cho runtime gửi telemetry. Dùng cấu hình SDK hoặc cấu hình gửi
dữ liệu theo phạm vi dự án từ LogBrew. Không dùng giá trị đăng nhập tài khoản
làm cấu hình SDK.

| Runtime | Cài đặt |
| - | - |
| JavaScript | `npm install @logbrew/sdk` |
| Trình duyệt | `npm install @logbrew/sdk @logbrew/browser` |
| Node.js | `npm install @logbrew/sdk @logbrew/node` |
| Express | `npm install @logbrew/sdk @logbrew/node @logbrew/express` |
| Fastify | `npm install @logbrew/sdk @logbrew/node @logbrew/fastify` |
| NestJS | `npm install @logbrew/sdk @logbrew/node @logbrew/nestjs` |
| React | `npm install @logbrew/sdk @logbrew/browser @logbrew/react` |
| Next.js | `npm install @logbrew/sdk @logbrew/node @logbrew/next` |
| Angular | `npm install @logbrew/sdk @logbrew/angular` |
| Vue | `npm install @logbrew/sdk @logbrew/vue` |
| Svelte | `npm install @logbrew/sdk @logbrew/browser @logbrew/svelte` |
| [React Native](/vi/guides/react-native) | `npm install @logbrew/sdk @logbrew/react-native` |
| Python | `python3 -m pip install logbrew-sdk` |
| FastAPI | `python3 -m pip install logbrew-fastapi` |
| Flask | `python3 -m pip install "logbrew-flask>=0.1.5,<0.2"` |
| Django | `python3 -m pip install logbrew-django` |
| Swift / Apple | Thêm `https://github.com/LogBrewCo/sdk.git` qua SwiftPM. |
| PHP | `composer require logbrew/sdk:^0.1.1` |
| Ruby | `gem install logbrew-sdk` |
| Go | `go get github.com/LogBrewCo/sdk/go/logbrew@latest` |
| Rust | `cargo add logbrew` |
| Java / Spring | Thêm `co.logbrew:logbrew-sdk:0.1.10` từ Maven Central. |
| .NET | `dotnet add package LogBrew --version 0.1.7` |
| ASP.NET Core | `dotnet add package LogBrew.AspNetCore --version 0.1.2` |
| C++ / CMake | Ghim `cpp/logbrew-cpp/v0.2.3` bằng `FetchContent` của CMake. |

### Trace yêu cầu trong Node.js

Để tương quan trace với span gốc của yêu cầu, dùng `@logbrew/sdk` 0.1.16 trở
lên và `@logbrew/node` 0.1.11 trở lên.

Express cần `@logbrew/express` 0.1.5 trở lên. Fastify và NestJS cần gói
LogBrew tương ứng từ 0.1.6 trở lên.

Các tích hợp này tạo hoặc tiếp nối một span yêu cầu. Tên span dùng mẫu route
khớp với yêu cầu. Log, vấn đề, hành động và chỉ số bên trong yêu cầu kế thừa
ngữ cảnh trace và span của yêu cầu đó. Gói mới hơn không bổ sung ngữ cảnh cho
các sự kiện đã gửi trước khi nâng cấp.

Tích hợp yêu cầu mặc định không ghi nhận nội dung yêu cầu hay phản hồi, query
string, header tùy ý hoặc giá trị `traceparent` thô.

### ASP.NET Core

CLI v0.1.55 trở lên phát hiện các dự án .NET 10 dùng
`Microsoft.NET.Sdk.Web`. Xem trước kế hoạch thiết lập từ thư mục gốc của dự án.
Lệnh này không thay đổi tệp của bạn:

```bash theme={null}
logbrew setup --json
```

Kế hoạch cài đặt bản tích hợp host đã phát hành:

```bash theme={null}
dotnet add package LogBrew.AspNetCore --version 0.1.2
```

Đặt `LOGBREW_SERVER_API_KEY`, `LOGBREW_SERVICE_NAME`,
`LOGBREW_ENVIRONMENT` và `LOGBREW_RELEASE` bên ngoài hệ thống quản lý mã
nguồn. Đăng ký LogBrew với host và đặt middleware của LogBrew sau phần routing:

```csharp theme={null}
using LogBrew;

var builder = WebApplication.CreateBuilder(args);
builder.AddLogBrew();

var app = builder.Build();
app.UseRouting();
app.UseLogBrew();
app.MapGet("/", () => "ok");
app.Run();
```

Nếu không có `LOGBREW_SERVER_API_KEY`, cả hai lệnh gọi đăng ký đều an toàn và
không làm gì. [Gói NuGet ASP.NET Core](https://www.nuget.org/packages/LogBrew.AspNetCore/0.1.2)
xác định bản tích hợp host đã phát hành. Hướng dẫn công khai của gói đề cập
vòng đời host, ghi nhận yêu cầu, ghi nhận vấn đề, giới hạn quyền riêng tư và
cách khôi phục.

### Java với Maven hoặc Gradle

CLI v0.1.54 trở lên phát hiện `pom.xml`, `build.gradle` và
`build.gradle.kts`. Xem trước kế hoạch thiết lập từ thư mục gốc của dự án. Lệnh
này không thay đổi tệp của bạn:

```bash theme={null}
logbrew setup --json
```

Với Maven, thêm gói đã phát hành:

```xml theme={null}
<dependency>
  <groupId>co.logbrew</groupId>
  <artifactId>logbrew-sdk</artifactId>
  <version>0.1.10</version>
</dependency>
```

Với Gradle Kotlin DSL, thêm cùng artifact (tệp bản dựng) đó từ Maven Central:

```kotlin theme={null}
implementation("co.logbrew:logbrew-sdk:0.1.10")
```

Dùng Java 11 trở lên.

Ứng dụng Spring Boot 3 và 4 có thể cung cấp một bean `LogBrewClient` do ứng
dụng sở hữu. Bean này bật các tích hợp tùy chọn cho yêu cầu, ngoại lệ, HTTP
client, JDBC và cache.

Ghi nhận Spring Kafka chỉ bật khi bạn chủ động đặt
`logbrew.kafka.enabled=true`. Tính năng này dùng dependency Spring Kafka và
bean client sẵn có của ứng dụng.

[Artifact Java SDK trên Maven Central](https://central.sonatype.com/artifact/co.logbrew/logbrew-sdk/0.1.10)
xác định gói đã phát hành. Hướng dẫn công khai của gói đề cập việc gửi HTTP có
giới hạn, tắt ứng dụng, ghi log, cấu hình Spring, tương quan Kafka và giới hạn
quyền riêng tư.

### C++ với CMake

C++ SDK cần C++17 và CMake 3.16 trở lên. CLI v0.1.39 trở lên phát hiện
`CMakeLists.txt` ở thư mục gốc. Chạy `logbrew setup --json` để xem trước kế
hoạch thiết lập này mà không thay đổi tệp của bạn:

```cmake theme={null}
include(FetchContent)
FetchContent_Declare(
  logbrew
  GIT_REPOSITORY https://github.com/LogBrewCo/sdk.git
  GIT_TAG cpp/logbrew-cpp/v0.2.3
  GIT_SHALLOW TRUE
  SOURCE_SUBDIR cpp/logbrew-cpp
)
FetchContent_MakeAvailable(logbrew)

target_link_libraries(your_app PRIVATE LogBrew::LogBrew)
```

Target lõi không phụ thuộc thư viện nào. Để gửi batch qua transport libcurl tùy
chọn, thay lệnh gọi `FetchContent_MakeAvailable` cuối cùng và lệnh liên kết
target ở trên bằng:

```cmake theme={null}
set(LOGBREW_BUILD_HTTP_TRANSPORT ON CACHE BOOL "" FORCE)
FetchContent_MakeAvailable(logbrew)
target_link_libraries(your_app PRIVATE LogBrew::HttpTransport)
```

Cấu hình ứng dụng. Sau đó build ứng dụng để kiểm tra phiên bản SDK đã chọn:

```bash theme={null}
cmake -S . -B build &&
cmake --build build
```

Với các bản dựng không tải được monorepo SDK, dùng asset
`logbrew-cpp-0.2.3.tar.gz` dành riêng cho gói C++ từ
[bản phát hành C++ 0.2.3](https://github.com/LogBrewCo/sdk/releases/tag/cpp/logbrew-cpp/v0.2.3).
Gói sau khi giải nén hỗ trợ `cmake --install` và
`find_package(LogBrew 0.2.3 CONFIG REQUIRED)`. Hướng dẫn của gói đề cập ngữ
cảnh có kiểu, bằng chứng vấn đề, sự kiện span, chỉ số, hành động và việc gửi
HTTP.

### Source map JavaScript

Với bản dựng Vite, làm theo [Source map JavaScript](/vi/guides/source-maps).
Hướng dẫn này đề cập plugin, khóa artifact, các bước kiểm tra tải lên và một
vấn đề mới hiển thị vị trí trong mã nguồn gốc.

### Apple, Flask và React Native

Dùng product Swift `LogBrew` cho telemetry. Chỉ thêm `LogBrewCrash` khi cần
ghi nhận crash hoặc treo trên Apple. Làm theo
[Crash và treo trên Apple](/vi/guides/apple-crashes-and-hangs) để tải
dSYM lên và dùng tính năng symbolicate do LogBrew thực hiện.

Với Flask, làm theo hướng dẫn [Flask](/vi/guides/flask).

Với React Native và Expo, làm theo [React Native](/vi/guides/react-native).
Hướng dẫn này đề cập khóa dự án, một log thử an toàn, lỗi gửi dữ liệu và cấu
hình Expo Metro cho source map production.

## <span id="javascript-queue-tracing">Trace hàng đợi trong JavaScript</span>

Các tích hợp hàng đợi cho Node là các gói npm riêng. Cài đặt các gói JavaScript
cơ bản của LogBrew, gói tích hợp, và client hàng đợi hoặc broker mà ứng dụng
của bạn đang dùng.

| Hàng đợi hoặc broker | Cài đặt |
| - | - |
| BullMQ | `npm install @logbrew/sdk @logbrew/node @logbrew/bullmq bullmq` |
| KafkaJS | `npm install @logbrew/sdk @logbrew/node @logbrew/kafkajs kafkajs` |
| RabbitMQ / amqplib | `npm install @logbrew/sdk @logbrew/node @logbrew/amqplib amqplib` |
| Amazon SQS | `npm install @logbrew/sdk @logbrew/node @logbrew/aws-sqs @aws-sdk/client-sqs` |

Dùng các gói này để tương quan trace một cách tường minh, do ứng dụng kiểm
soát, quanh các lệnh gọi hàng đợi mà bạn chọn. LogBrew không sở hữu kết nối
broker của bạn, không tạo hàng đợi, và mặc định không patch toàn cục mọi
client.

<Warning>
  Không đưa payload hàng đợi, header thông điệp tùy ý, URL broker và giá trị
  bearer của phiên hoặc tài khoản vào cấu hình SDK. Dùng cấu hình gửi dữ liệu
  phía máy chủ theo phạm vi dự án từ LogBrew.
</Warning>

## <span id="required-envelope-fields">Gửi trực tiếp envelope gốc</span>

Chỉ dùng `POST /api/telemetry/ingest` cho client tùy chỉnh mà không SDK LogBrew
công khai nào hỗ trợ. SDK công khai dùng định dạng batch riêng. Endpoint này
không nhận định dạng đó.

Gửi 1 đến 512 mục trong một envelope gốc. Mọi mục trong một envelope dùng chung
dự án, dịch vụ, bản phát hành, môi trường và ngữ cảnh trace tùy chọn.

| Trường | Bắt buộc | Ghi chú |
| - | - | - |
| `project_id` | Có | UUID của dự án LogBrew. Phải khớp với dự án của khóa gửi dữ liệu. |
| `environment` | Có | Môi trường triển khai. Tối đa 64 ký tự, không có khoảng trắng, `/` hoặc `\`. Giá trị `None` bị từ chối. |
| `release` | Có | Phiên bản mã. Tối đa 200 ký tự, không có `/`, `\`, tab hoặc ký tự xuống dòng. Không được là `.` hoặc `..`. |
| `service_name` | Có | Tên logic của dịch vụ, chẳng hạn `checkout-api`. Không được để trống. |
| `sdk_name` | Có | Định danh của SDK hoặc client tùy chỉnh. |
| `sdk_version` | Có | Phiên bản của SDK hoặc client tùy chỉnh. |
| `items` | Có | 1 đến 512 mục `log`, `trace_span`, `issue` hoặc `action`. |
| `trace_id` | Không | Trace ID dùng chung cho các mục có tương quan trong envelope. Bắt buộc khi một mục có `span_id`. |

### Các trường của mục

Mỗi mục có `type` và một đối tượng `data`. Mục log dùng `level`. Mục vấn đề
dùng `severity`. Cả hai nhận các giá trị trong [Giá trị mức độ nghiêm trọng](/vi/concepts/telemetry#severity-values).

| Trường của mục | Áp dụng cho | Ghi chú |
| - | - | - |
| `id` | Mọi mục | ID sự kiện tùy chọn do client đặt. 1 đến 200 ký tự, không trùng trong envelope. |
| `span_id` | `log`, `issue`, `action` | Tùy chọn. 16 ký tự thập lục phân, không phải toàn số 0. Envelope phải có `trace_id`. |
| `name` | `action` | Bắt buộc. Tối đa 64 byte UTF-8. Không được bắt đầu bằng `$`, không được bắt đầu hoặc kết thúc bằng khoảng trắng, và không được chứa ký tự điều khiển hay ký tự định dạng ẩn. |

Gửi `id` cho mỗi mục khi client của bạn có thể thử lại. Khi một lần thử lại gửi
lại mục đã được chấp nhận với cùng `id` và cùng nội dung, LogBrew không lưu mục
đó thêm lần nữa. Phản hồi tính mục đó vào `already_accepted`.

### Yêu cầu mẫu

Lưu JSON dưới đây thành `telemetry-envelope.json`. Thay ID dự án mẫu bằng đúng
ID dự án của khóa gửi dữ liệu. Đặt các dấu thời gian thành thời gian UTC hiện
tại của sự kiện thử. Dùng giá trị dịch vụ và bản phát hành của riêng bạn.

```json telemetry-envelope.json theme={null}
{
  "project_id": "11111111-1111-4111-8111-111111111111",
  "environment": "production",
  "release": "api@1.2.3",
  "service_name": "checkout-api",
  "sdk_name": "custom-native-client",
  "sdk_version": "1.0.0",
  "items": [
    {
      "type": "log",
      "data": {
        "id": "evt_example_log_0001",
        "level": "warning",
        "message": "checkout retry scheduled",
        "source": "runtime",
        "attributes": { "route": "/checkout" },
        "occurred_at": "2026-06-01T12:00:00Z"
      }
    },
    {
      "type": "action",
      "data": {
        "id": "evt_example_action_0001",
        "name": "checkout_failed",
        "distinct_id": "user_123",
        "session_id": "session_456",
        "occurred_at": "2026-06-01T12:00:00Z",
        "properties": { "cart_total": 4200 }
      }
    }
  ]
}
```

Nạp giá trị khóa gửi dữ liệu theo phạm vi dự án vào `LOGBREW_INGEST_BEARER` qua
cấu hình được bảo vệ của bạn. Không in giá trị này ra và không dùng thông tin xác
thực tài khoản. Lệnh sau gửi tệp một lần. Lệnh cần curl 7.76.0 trở lên:

```bash theme={null}
: "${LOGBREW_INGEST_BEARER:?load the project-scoped ingest key}" &&
curl --fail-with-body --silent --show-error \
  "https://api.logbrew.co/api/telemetry/ingest" \
  -H "Authorization: Bearer $LOGBREW_INGEST_BEARER" \
  -H "Content-Type: application/json" \
  --data-binary @telemetry-envelope.json \
  --write-out '\nHTTP %{http_code}\n'
```

Đọc trạng thái HTTP và nội dung phản hồi. `--fail-with-body` giữ lại nội dung
lỗi và trả về mã thoát khác 0 khi có lỗi HTTP. Lỗi mạng hoặc hết thời gian chờ
không cho biết LogBrew đã chấp nhận yêu cầu hay chưa. Chỉ gửi lại cùng tệp khi
các mục có giá trị `id`. Nếu không có giá trị `id`, lần gửi thứ hai có thể lưu
các mục hai lần.

### Phản hồi

Yêu cầu thành công trả về `200` kèm số mục mới theo từng luồng.
`already_accepted` đếm các mục mà một yêu cầu trước đó đã gửi thành công.

```json theme={null}
{
  "issues": 0,
  "logs": 1,
  "trace_spans": 0,
  "actions": 1,
  "already_accepted": 0,
  "next": "review accepted telemetry in logs, issues, traces, actions, or live feed",
  "next_action": {
    "code": "review_ingested_telemetry",
    "target": "telemetry_reads"
  }
}
```

### Lỗi

Khóa gửi dữ liệu không hợp lệ hoặc đã bị thu hồi trả về `401`. Khóa của một dự
án khác cũng trả về `401`:

```json theme={null}
{
  "error": "Invalid ingest key",
  "code": "ingest_key_invalid",
  "next": "create a project-scoped ingest key, then retry ingestion with that key",
  "next_action": {
    "code": "configure_ingest_key",
    "target": "project_ingest_key"
  }
}
```

Dùng khóa gửi dữ liệu theo phạm vi dự án. Không thay nó bằng thông tin xác
thực tài khoản. Khóa artifact không gửi được telemetry.

Envelope vi phạm quy tắc của một trường sẽ trả về `422` với mã
`validation_failed`. Trường `error` nêu tên quy tắc. Trường `next` cho biết
cách sửa yêu cầu. Ví dụ, `"items": []` trả về:

```json theme={null}
{
  "error": "native telemetry envelope cannot be empty",
  "code": "validation_failed",
  "next": "send at least one native telemetry item",
  "next_action": {
    "code": "fix_request",
    "target": "request"
  }
}
```

Không gửi envelope khi không có sự kiện nào. Envelope có hơn 512 mục trả về
`422` với lỗi `native telemetry envelope exceeds the item limit`. Chia thành
các batch có tối đa 512 mục. Giữ dự án và ngữ cảnh dùng chung trong mỗi batch.

Với hạn mức sử dụng, giới hạn tốc độ và lỗi dịch vụ, làm theo `code` được trả
về trong [Lỗi API](/vi/reference/api-errors).

<Tip>
  Đặt bản phát hành và môi trường trong phần thiết lập SDK. Tạo hoặc tiếp nối
  ngữ cảnh trace cho mỗi thao tác. Không dùng lại một trace ID cho các công việc
  không liên quan.
</Tip>


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