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

# Integrasi SDK untuk telemetri aplikasi

> Pilih SDK LogBrew untuk runtime Anda. Konfigurasikan kunci ingest-nya. Kirim telemetri aplikasi dan temukan peristiwa uji di proyek Anda.

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:

1. Instal paket SDK untuk runtime Anda.
2. Simpan kunci ingest khusus proyek di luar source control.
3. Atur nilai layanan, lingkungan, dan rilis yang stabil.
4. Kirim satu peristiwa uji yang aman dari aplikasi.
5. 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](/id/guides/safe-capture). Untuk mengisi
Analitik, ikuti [Perekaman peristiwa produk](/id/guides/product-events).

## <span id="item-types">Sinyal dan konteks bersama</span>

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

<CardGroup cols={2}>
  <Card title="log" icon="file-text">
    Pesan terstruktur dengan tingkat keparahan, sumber, waktu, dan konteks yang aman.
  </Card>

  <Card title="trace_span" icon="route">
    Satu operasi yang diukur waktunya, terhubung ke trace-nya melalui ID trace dan ID span.
  </Card>

  <Card title="issue" icon="bug">
    Kegagalan yang terekam, tingkat keparahannya, dan detail error yang dikirim aplikasi.
  </Card>

  <Card title="action" icon="mouse-pointer-click">
    Aksi di aplikasi Anda, dengan subjek, sesi, dan properti aman yang opsional.
  </Card>

  <Card title="metric" icon="chart-line">
    Satu pengukuran numerik dengan nama, jenis, nilai, satuan, dan temporalitas.
  </Card>

  <Card title="rilis dan lingkungan" icon="tags">
    Versi kode dan lingkungan yang dilampirkan ke peristiwa berikutnya dalam lingkup SDK yang sama.
  </Card>
</CardGroup>

## 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](/id/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 | 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.10` 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:

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

Rencana untuk paket yang sudah dirilis menginstal integrasi host:

```bash theme={null}
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:

```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();
```

Tanpa `LOGBREW_SERVER_API_KEY`, kedua panggilan pendaftaran aman dan tidak
melakukan apa pun.
[Paket NuGet ASP.NET Core](https://www.nuget.org/packages/LogBrew.AspNetCore/0.1.2)
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:

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

Untuk Maven, tambahkan paket yang sudah dirilis:

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

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

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

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](https://central.sonatype.com/artifact/co.logbrew/logbrew-sdk/0.1.10)
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:

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

```cmake theme={null}
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:

```bash theme={null}
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](https://github.com/LogBrewCo/sdk/releases/tag/cpp/logbrew-cpp/v0.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](/id/guides/source-maps).
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](/id/guides/apple-crashes-and-hangs) untuk unggahan
dSYM dan simbolikasi yang di-host.

Untuk Flask, ikuti panduan [Flask](/id/guides/flask).

Untuk React Native dan Expo, ikuti panduan [React Native](/id/guides/react-native).
Panduan itu membahas kunci proyek, log uji yang aman, error pengiriman, dan
konfigurasi Expo Metro untuk source map produksi.

## <span id="javascript-queue-tracing">Pelacakan antrean JavaScript</span>

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.

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

## <span id="required-envelope-fields">Envelope native langsung</span>

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](/id/concepts/telemetry#severity-values).

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

```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 }
      }
    }
  ]
}
```

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:

```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'
```

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.

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

### Error

Kunci ingest yang tidak valid atau sudah dicabut mengembalikan `401`. Kunci
untuk proyek lain juga mengembalikan `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"
  }
}
```

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:

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

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](/id/reference/api-errors).

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


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