Integrasi SDK untuk telemetri aplikasi

Instal paket SDK LogBrew untuk runtime Anda. SDK memformat peristiwa dan mengirimkannya. Panduan paket mencantumkan jenis peristiwa, batas, dan perilaku percobaan ulangnya. Lakukan langkah berikut untuk setiap integrasi:

Instal paket SDK untuk runtime Anda.
Simpan kunci ingest khusus proyek di luar source control.
Atur nilai layanan, lingkungan, dan rilis yang stabil.
Kirim satu peristiwa uji yang aman dari aplikasi.
Baca hasil pengiriman. Lalu temukan peristiwa itu di LogBrew.

Batch yang diterima berarti batch itu sudah sampai ke API LogBrew. Filter masih dapat menyembunyikan peristiwanya. Pilih proyek dan rentang waktu yang benar. Lalu cocokkan layanan, lingkungan, rilis, dan jenis sinyal. Sebelum mengaktifkan perekaman, pilih dan uji kolom yang disetujui. Untuk mengisi Analitik, ikuti Perekaman peristiwa produk.

Sinyal dan konteks bersama

Lima kartu pertama adalah sinyal. Rilis dan lingkungan adalah konteks untuk sinyal tersebut. Keduanya bukan jenis peristiwa tersendiri.

log

Pesan terstruktur dengan tingkat keparahan, sumber, waktu, dan konteks yang aman.

trace_span

Satu operasi yang diukur waktunya, terhubung ke trace-nya melalui ID trace dan ID span.

issue

Kegagalan yang terekam, tingkat keparahannya, dan detail error yang dikirim aplikasi.

action

Aksi di aplikasi Anda, dengan subjek, sesi, dan properti aman yang opsional.

metric

Satu pengukuran numerik dengan nama, jenis, nilai, satuan, dan temporalitas.

rilis dan lingkungan

Versi kode dan lingkungan yang dilampirkan ke peristiwa berikutnya dalam lingkup SDK yang sama.

Nilai tingkat keparahan

Gunakan info, warning, error, atau critical untuk log dan masalah. SDK dan runtime dapat mengirim alias seperti trace, debug, warn, atau fatal. LogBrew menormalkan alias yang diterima ke nilai kanonis.

Instalasi lewat package manager

Instal paket SDK untuk runtime yang mengirim telemetri. Gunakan konfigurasi SDK atau ingest khusus proyek dari LogBrew. Jangan gunakan nilai login akun sebagai konfigurasi SDK.

Runtime	Instalasi
JavaScript	`npm install @logbrew/sdk`
Browser	`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	`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	Tambahkan `https://github.com/LogBrewCo/sdk.git` melalui 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	Tambahkan `co.logbrew:logbrew-sdk:0.1.9` dari 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	Tetapkan versi `cpp/logbrew-cpp/v0.2.3` dengan `FetchContent` CMake.

Pelacakan permintaan Node.js

Untuk korelasi trace dengan root span di tingkat permintaan, gunakan @logbrew/sdk 0.1.16 atau yang lebih baru dan @logbrew/node 0.1.11 atau yang lebih baru. Express memerlukan @logbrew/express 0.1.5 atau yang lebih baru. Fastify dan NestJS memerlukan paket LogBrew masing-masing versi 0.1.6 atau yang lebih baru. Integrasi ini membuat atau melanjutkan satu span permintaan. Nama span memakai template rute yang cocok. Log, masalah, aksi, dan metrik di dalam permintaan mewarisi konteks trace dan span-nya. Paket yang lebih baru tidak menambahkan konteks ke peristiwa yang dikirim sebelum upgrade. Integrasi permintaan default tidak merekam body permintaan atau respons, string kueri, header sembarang, atau nilai traceparent mentah.

ASP.NET Core

CLI v0.1.55 atau yang lebih baru mendeteksi proyek .NET 10 yang memakai Microsoft.NET.Sdk.Web. Lihat pratinjau rencana penyiapan dari root proyek. Perintah ini tidak mengubah file Anda:

logbrew setup --json

Rencana untuk paket yang sudah dirilis menginstal integrasi host:

dotnet add package LogBrew.AspNetCore --version 0.1.2

Atur LOGBREW_SERVER_API_KEY, LOGBREW_SERVICE_NAME, LOGBREW_ENVIRONMENT, dan LOGBREW_RELEASE di luar source control. Daftarkan LogBrew ke host dan letakkan middleware-nya setelah routing:

using LogBrew;

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

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

Tanpa LOGBREW_SERVER_API_KEY, kedua panggilan pendaftaran aman dan tidak melakukan apa pun. Paket NuGet ASP.NET Core menunjukkan integrasi host yang sudah dirilis. Panduan paket publiknya membahas siklus hidup host, perekaman permintaan, perekaman masalah, batas privasi, dan pemulihan.

Java dengan Maven atau Gradle

CLI v0.1.54 atau yang lebih baru mendeteksi pom.xml, build.gradle, dan build.gradle.kts. Lihat pratinjau rencana penyiapan dari root proyek. Perintah ini tidak mengubah file Anda:

logbrew setup --json

Untuk Maven, tambahkan paket yang sudah dirilis:

<dependency>
  <groupId>co.logbrew</groupId>
  <artifactId>logbrew-sdk</artifactId>
  <version>0.1.9</version>
</dependency>

Untuk Gradle Kotlin DSL, tambahkan artefak Maven Central yang sama:

implementation("co.logbrew:logbrew-sdk:0.1.9")

Gunakan Java 11 atau yang lebih baru. Aplikasi Spring Boot 3 dan 4 dapat mengekspos bean LogBrewClient milik aplikasi. Bean ini mengaktifkan integrasi opsional untuk permintaan, exception, klien HTTP, JDBC, dan cache. Perekaman Spring Kafka harus diaktifkan secara eksplisit dengan logbrew.kafka.enabled=true. Perekaman ini memakai dependensi Spring Kafka dan bean klien yang sudah ada di aplikasi. Artefak Java SDK di Maven Central menunjukkan paket yang sudah dirilis. Panduan publiknya membahas pengiriman HTTP yang dibatasi, shutdown, logging, konfigurasi Spring, korelasi Kafka, dan batas privasi.

C++ dengan CMake

SDK C++ memerlukan C++17 dan CMake 3.16 atau yang lebih baru. CLI v0.1.39 atau yang lebih baru mendeteksi CMakeLists.txt di root. Jalankan logbrew setup --json untuk melihat pratinjau rencana penyiapan ini tanpa mengubah file Anda:

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 inti tidak memiliki dependensi. Untuk mengirim batch melalui transport libcurl yang opsional, ganti panggilan FetchContent_MakeAvailable terakhir dan target link di atas dengan:

set(LOGBREW_BUILD_HTTP_TRANSPORT ON CACHE BOOL "" FORCE)
FetchContent_MakeAvailable(logbrew)
target_link_libraries(your_app PRIVATE LogBrew::HttpTransport)

Konfigurasikan aplikasi. Lalu build aplikasi untuk menguji versi SDK yang dipilih:

cmake -S . -B build &&
cmake --build build

Untuk build yang tidak dapat mengambil monorepo SDK, gunakan aset khusus logbrew-cpp-0.2.3.tar.gz dari rilis C++ 0.2.3. Paket yang sudah diekstrak mendukung cmake --install dan find_package(LogBrew 0.2.3 CONFIG REQUIRED). Panduan paketnya membahas konteks bertipe, bukti masalah, peristiwa span, metrik, aksi, dan pengiriman HTTP.

Source map JavaScript

Untuk build Vite, ikuti Source map JavaScript. Panduan itu membahas plugin, kunci artefak, pemeriksaan unggahan, dan masalah baru dengan lokasi sumber asli.

Apple, Flask, dan React Native

Gunakan produk Swift LogBrew untuk telemetri. Tambahkan LogBrewCrash hanya untuk merekam crash atau hang Apple. Ikuti panduan Crash dan hang Apple untuk unggahan dSYM dan simbolikasi yang di-host. Untuk Flask, ikuti panduan Flask. Untuk React Native dan Expo, ikuti panduan React Native. Panduan itu membahas kunci proyek, log uji yang aman, error pengiriman, dan konfigurasi Expo Metro untuk source map produksi.

Pelacakan antrean JavaScript

Integrasi antrean Node adalah paket npm terpisah. Instal paket JavaScript dasar LogBrew, paket integrasi, dan klien antrean atau broker yang sudah dipakai aplikasi Anda.

Antrean atau broker	Instalasi
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`

Gunakan paket ini untuk korelasi trace yang eksplisit dan dikendalikan aplikasi di sekitar panggilan antrean yang Anda pilih. Secara default, LogBrew tidak mengambil alih koneksi broker Anda, tidak membuat antrean, dan tidak mem-patch setiap klien secara global.

Jangan masukkan payload antrean, header pesan sembarang, URL broker, serta nilai bearer sesi atau akun ke konfigurasi SDK. Gunakan konfigurasi ingest server khusus proyek dari LogBrew.

Envelope native langsung

Gunakan POST /api/telemetry/ingest hanya untuk klien kustom yang tidak didukung SDK LogBrew publik mana pun. SDK publik memakai format batch-nya sendiri. Endpoint ini tidak menerima format tersebut. Kirim 1 sampai 512 item dalam satu envelope native. Semua item dalam satu envelope berbagi proyek, layanan, rilis, lingkungan, dan konteks trace opsional yang sama.

Kolom	Wajib	Catatan
`project_id`	Ya	UUID untuk proyek LogBrew. Harus cocok dengan proyek kunci ingest.
`environment`	Ya	Lingkungan deployment. Maksimal 64 karakter, tanpa whitespace, `/`, atau `\`. Nilai `None` ditolak.
`release`	Ya	Versi kode. Maksimal 200 karakter, tanpa `/`, `\`, tab, atau baris baru. Nilainya tidak boleh `.` atau `..`.
`service_name`	Ya	Nama layanan logis, misalnya `checkout-api`. Tidak boleh kosong.
`sdk_name`	Ya	Pengenal SDK atau klien kustom.
`sdk_version`	Ya	Versi SDK atau klien kustom.
`items`	Ya	1 sampai 512 item `log`, `trace_span`, `issue`, atau `action`.
`trace_id`	Tidak	ID trace yang dipakai bersama oleh item envelope yang berkorelasi. Wajib jika item memiliki `span_id`.

Kolom item

Setiap item memiliki type dan objek data. Item log memakai level. Item masalah memakai severity. Keduanya menerima nilai di Nilai tingkat keparahan.

Kolom item	Berlaku untuk	Catatan
`id`	Semua item	ID peristiwa klien yang opsional. 1 sampai 200 karakter, unik dalam envelope.
`span_id`	`log`, `issue`, `action`	Opsional. 16 karakter heksadesimal, tidak boleh nol semua. Envelope harus memiliki `trace_id`.
`name`	`action`	Wajib. Maksimal 64 byte UTF-8. Tidak boleh diawali `$`, tidak boleh diawali atau diakhiri whitespace, dan tidak boleh berisi karakter kontrol atau karakter format yang tidak terlihat.

Kirim id untuk setiap item jika klien Anda dapat mencoba lagi. Jika percobaan ulang mengirim lagi item yang sudah diterima dengan id dan isi yang sama, LogBrew tidak menyimpannya lagi. Respons menghitung item itu di already_accepted.

Contoh permintaan

Simpan JSON di bawah sebagai telemetry-envelope.json. Ganti contoh ID proyek dengan ID proyek yang persis untuk kunci ingest Anda. Atur stempel waktu ke waktu UTC saat ini untuk peristiwa uji. Gunakan nilai layanan dan rilis Anda sendiri.

telemetry-envelope.json

{
  "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 }
      }
    }
  ]
}

Muat nilai ingest khusus proyek ke LOGBREW_INGEST_BEARER melalui konfigurasi Anda yang terlindungi. Jangan mencetaknya dan jangan memakai kredensial akun. Perintah berikut mengirim file satu kali. Perintah ini memerlukan curl 7.76.0 atau yang lebih baru:

: "${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'

Baca status HTTP dan body-nya. --fail-with-body mempertahankan body error dan mengembalikan status keluar bukan nol untuk error HTTP. Kegagalan jaringan atau timeout tidak memberi tahu Anda apakah LogBrew menerima permintaan. Kirim file yang sama lagi hanya jika item-itemnya memiliki nilai id. Tanpa nilai id, pengiriman kedua dapat menyimpan item dua kali.

Respons

Permintaan yang berhasil mengembalikan 200 dengan jumlah item baru per stream. already_accepted menghitung item yang sudah dikirim oleh permintaan sebelumnya.

{
  "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"
  }
}

Error

Kunci ingest yang tidak valid atau sudah dicabut mengembalikan 401. Kunci untuk proyek lain juga mengembalikan 401:

{
  "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"
  }
}

Gunakan kunci ingest khusus proyek. Jangan menggantinya dengan kredensial akun. Kunci artefak tidak dapat mengirim telemetri. Envelope yang melanggar aturan kolom mengembalikan 422 dengan kode validation_failed. Kolom error menyebutkan aturannya. Kolom next menjelaskan cara memperbaiki permintaan. Misalnya, "items": [] mengembalikan:

{
  "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"
  }
}

Jangan kirim envelope jika tidak ada peristiwa. Envelope dengan lebih dari 512 item mengembalikan 422 dengan error native telemetry envelope exceeds the item limit. Pecah menjadi beberapa batch berisi maksimal 512 item. Pertahankan proyek dan konteks bersama di setiap batch. Untuk batas penggunaan, batas laju, dan kegagalan layanan, ikuti code yang dikembalikan di Error API.

Atur rilis dan lingkungan saat penyiapan SDK. Buat atau lanjutkan konteks trace untuk setiap operasi. Jangan pakai ulang satu ID trace untuk pekerjaan yang tidak terkait.

Mulai

Konsep

Instal dan kirim

Investigasi

CLI dan agen

Dukungan

Integrasi SDK untuk telemetri aplikasi

Sinyal dan konteks bersama

log

trace_span

issue

action

metric

rilis dan lingkungan

Nilai tingkat keparahan

Instalasi lewat package manager

Pelacakan permintaan Node.js

ASP.NET Core

Java dengan Maven atau Gradle

C++ dengan CMake

Source map JavaScript

Apple, Flask, dan React Native

Pelacakan antrean JavaScript

Envelope native langsung

Kolom item

Contoh permintaan

Respons

Error

​Sinyal dan konteks bersama

log

trace_span

issue

action

metric

rilis dan lingkungan

​Nilai tingkat keparahan

​Instalasi lewat package manager

​Pelacakan permintaan Node.js

​ASP.NET Core

​Java dengan Maven atau Gradle

​C++ dengan CMake

​Source map JavaScript

​Apple, Flask, dan React Native

​Pelacakan antrean JavaScript

​Envelope native langsung

​Kolom item

​Contoh permintaan

​Respons

​Error

Sinyal dan konteks bersama

Nilai tingkat keparahan

Instalasi lewat package manager

Pelacakan permintaan Node.js

ASP.NET Core

Java dengan Maven atau Gradle

C++ dengan CMake

Source map JavaScript

Apple, Flask, dan React Native

Pelacakan antrean JavaScript

Envelope native langsung

Kolom item

Contoh permintaan

Respons

Error