Skip to main content
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. Để có dữ liệu cho Phân tích, làm theo Ghi nhận sự kiện sản phẩm.

Tín hiệu và ngữ cảnh dùng chung

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.

log

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.

trace_span

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.

issue

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.

action

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.

metric

Một phép đo dạng số có tên, loại, giá trị, đơn vị và temporality.

bản phát hành và môi trường

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.

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.

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:
Kế hoạch cài đặt bản tích hợp host đã phát hành:
Đặ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:
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 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:
Với Maven, thêm gói đã phát hành:
Với Gradle Kotlin DSL, thêm cùng artifact (tệp bản dựng) đó từ Maven Central:
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 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:
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:
Cấu hình ứng dụng. Sau đó build ứng dụng để kiểm tra phiên bản SDK đã chọn:
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. 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. 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 để 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. Với React Native và Expo, làm theo 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.

Trace hàng đợi trong JavaScript

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

Gửi trực tiếp envelope gốc

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.

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. 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.
telemetry-envelope.json
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:
Đọ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.

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:
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ề:
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.
Đặ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.