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

# SDK-Integration für Anwendungstelemetrie

> Wählen Sie ein LogBrew-SDK für Ihre Laufzeit, und konfigurieren Sie den Ingest-Schlüssel. Senden Sie Telemetrie, und finden Sie das Testereignis im Projekt.

Installieren Sie das LogBrew-SDK-Paket für Ihre Laufzeit. Das SDK formatiert
Ereignisse und stellt sie zu. Der Leitfaden des Pakets nennt seine
Ereignistypen, Limits und sein Verhalten bei Wiederholungen.

Führen Sie diese Schritte für jede Integration aus:

1. Installieren Sie das SDK-Paket für Ihre Laufzeit.
2. Halten Sie den projektbezogenen Ingest-Schlüssel aus der
   Versionsverwaltung heraus.
3. Legen Sie stabile Werte für Dienst, Umgebung und Release fest.
4. Senden Sie ein sicheres Testereignis aus der Anwendung.
5. Lesen Sie das Ergebnis der Zustellung. Suchen Sie das Ereignis dann in
   LogBrew.

Ein angenommener Batch hat die LogBrew-API erreicht. Filter können seine
Ereignisse trotzdem ausblenden. Wählen Sie das richtige Projekt und den
richtigen Zeitraum. Gleichen Sie dann Dienst, Umgebung, Release und Signaltyp
ab.

Bevor Sie die Erfassung aktivieren,
[wählen und testen Sie freigegebene Felder](/de/guides/safe-capture).
Um Analysen mit Daten zu füllen, folgen Sie
[Produktereignisse erfassen](/de/guides/product-events).

## <span id="item-types">Signale und gemeinsamer Kontext</span>

Die ersten fünf Karten sind Signale. Release und Umgebung sind Kontext für
diese Signale. Sie sind kein eigener Ereignistyp.

<CardGroup cols={2}>
  <Card title="log" icon="file-text">
    Eine strukturierte Nachricht mit Schweregrad, Quelle, Zeit und sicherem
    Kontext.
  </Card>

  <Card title="trace_span" icon="route">
    Eine zeitlich gemessene Operation, die über Trace- und Span-IDs mit ihrem
    Trace verknüpft ist.
  </Card>

  <Card title="issue" icon="bug">
    Ein erfasster Fehler, sein Schweregrad und die Fehlerdetails, die die App
    gesendet hat.
  </Card>

  <Card title="action" icon="mouse-pointer-click">
    Eine Aktion in Ihrer App, optional mit Subjekt, Sitzung und sicheren
    Eigenschaften.
  </Card>

  <Card title="metric" icon="chart-line">
    Ein numerischer Messwert mit Name, Art, Wert, Einheit und Temporalität.
  </Card>

  <Card title="release und environment" icon="tags">
    Die Codeversion und die Umgebung, die an spätere Ereignisse im selben
    SDK-Bereich angehängt werden.
  </Card>
</CardGroup>

## Werte für den Schweregrad

Verwenden Sie für Logs und Issues `info`, `warning`, `error` oder `critical`.
SDKs und Laufzeiten können Aliasse wie `trace`, `debug`, `warn` oder `fatal`
senden. LogBrew normalisiert angenommene Aliasse auf die kanonischen Werte.

## Installation per Paketmanager

Installieren Sie das SDK-Paket für die Laufzeit, die Telemetrie sendet.
Verwenden Sie die projektbezogene SDK- oder Ingest-Konfiguration von LogBrew.
Verwenden Sie keine Zugangsdaten Ihres Kontos als SDK-Konfiguration.

| Laufzeit | Installation |
| - | - |
| 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](/de/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 | Fügen Sie `https://github.com/LogBrewCo/sdk.git` über SwiftPM hinzu. |
| 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 | Fügen Sie `co.logbrew:logbrew-sdk:0.1.10` aus Maven Central hinzu. |
| .NET | `dotnet add package LogBrew --version 0.1.7` |
| ASP.NET Core | `dotnet add package LogBrew.AspNetCore --version 0.1.2` |
| C++ / CMake | Pinnen Sie `cpp/logbrew-cpp/v0.2.3` mit CMake `FetchContent`. |

### Anfrage-Tracing in Node.js

Für die Trace-Korrelation mit der Anfrage als Root verwenden Sie
`@logbrew/sdk` 0.1.16 oder neuer und `@logbrew/node` 0.1.11 oder neuer.

Express braucht `@logbrew/express` 0.1.5 oder neuer. Fastify und NestJS
brauchen ihr LogBrew-Paket in Version 0.1.6 oder neuer.

Diese Integrationen erstellen einen Anfrage-Span oder setzen ihn fort. Der
Name des Spans verwendet die passende Routenvorlage. Logs, Issues, Aktionen
und Metriken innerhalb der Anfrage erben ihren Trace- und Span-Kontext. Ein
neueres Paket fügt Ereignissen, die vor dem Update gesendet wurden, keinen
Kontext hinzu.

Die Standard-Integration für Anfragen erfasst keine Anfrage- oder
Antwort-Bodys, keine Query-Strings, keine beliebigen Header und keine rohen
`traceparent`-Werte.

### ASP.NET Core

CLI v0.1.55 oder neuer erkennt .NET-10-Projekte, die `Microsoft.NET.Sdk.Web`
verwenden. Sehen Sie sich den Einrichtungsplan im Stammverzeichnis des
Projekts an. Dieser Befehl ändert Ihre Dateien nicht:

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

Der veröffentlichte Plan installiert die Host-Integration:

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

Legen Sie `LOGBREW_SERVER_API_KEY`, `LOGBREW_SERVICE_NAME`,
`LOGBREW_ENVIRONMENT` und `LOGBREW_RELEASE` außerhalb der Versionsverwaltung
fest. Registrieren Sie LogBrew beim Host, und setzen Sie die Middleware hinter
das 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();
```

Ohne `LOGBREW_SERVER_API_KEY` tun beide Registrierungsaufrufe gefahrlos
nichts. Das
[ASP.NET-Core-NuGet-Paket](https://www.nuget.org/packages/LogBrew.AspNetCore/0.1.2)
bezeichnet die veröffentlichte Host-Integration. Sein öffentlicher
Paketleitfaden beschreibt Host-Lebenszyklus, Erfassung von Anfragen und
Issues, Datenschutzgrenzen und Wiederherstellung.

### Java mit Maven oder Gradle

CLI v0.1.54 oder neuer erkennt `pom.xml`, `build.gradle` und
`build.gradle.kts`. Sehen Sie sich den Einrichtungsplan im Stammverzeichnis
des Projekts an. Dieser Befehl ändert Ihre Dateien nicht:

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

Für Maven fügen Sie das veröffentlichte Paket hinzu:

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

Für die Gradle Kotlin DSL fügen Sie dasselbe Artefakt aus Maven Central hinzu:

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

Verwenden Sie Java 11 oder neuer.

Anwendungen mit Spring Boot 3 und 4 können eine eigene `LogBrewClient`-Bean
bereitstellen. Sie aktiviert optionale Integrationen für Anfragen, Ausnahmen,
HTTP-Clients, JDBC und Caches.

Die Erfassung für Spring Kafka müssen Sie ausdrücklich mit
`logbrew.kafka.enabled=true` einschalten. Sie nutzt die vorhandene
Spring-Kafka-Abhängigkeit und die Client-Bean der Anwendung.

Das
[Java-SDK-Artefakt in Maven Central](https://central.sonatype.com/artifact/co.logbrew/logbrew-sdk/0.1.10)
bezeichnet das veröffentlichte Paket. Sein öffentlicher Leitfaden beschreibt
begrenzte HTTP-Zustellung, Herunterfahren, Logging, Spring-Konfiguration,
Kafka-Korrelation und Datenschutzgrenzen.

### C++ mit CMake

Das C++-SDK braucht C++17 und CMake 3.16 oder neuer. CLI v0.1.39 oder neuer
erkennt eine `CMakeLists.txt` im Stammverzeichnis. Führen Sie
`logbrew setup --json` aus, um diesen Einrichtungsplan anzusehen, ohne Ihre
Dateien zu ändern:

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

Das Kern-Target hat keine Abhängigkeiten. Um Batches über den optionalen
libcurl-Transport zu senden, ersetzen Sie den letzten Aufruf von
`FetchContent_MakeAvailable` und das Target-Linking oben durch:

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

Konfigurieren Sie die Anwendung. Bauen Sie sie dann, um die gewählte
SDK-Version zu testen:

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

Für Builds, die das SDK-Monorepo nicht abrufen können, verwenden Sie das
eigene Asset `logbrew-cpp-0.2.3.tar.gz` aus dem
[Release C++ 0.2.3](https://github.com/LogBrewCo/sdk/releases/tag/cpp/logbrew-cpp/v0.2.3).
Das entpackte Paket unterstützt `cmake --install` und
`find_package(LogBrew 0.2.3 CONFIG REQUIRED)`. Sein Paketleitfaden beschreibt
typisierten Kontext, Issue-Belege, Span-Ereignisse, Metriken, Aktionen und
HTTP-Zustellung.

### JavaScript-Source-Maps

Für Vite-Builds folgen Sie [JavaScript-Source-Maps](/de/guides/source-maps).
Der Leitfaden beschreibt das Plugin, den Artefakt-Schlüssel, die Prüfungen beim
Hochladen und ein neues Issue mit den ursprünglichen Stellen im Quellcode.

### Apple, Flask und React Native

Verwenden Sie für Telemetrie das Swift-Produkt `LogBrew`. Fügen Sie
`LogBrewCrash` nur hinzu, um Abstürze oder Hänger auf Apple-Geräten zu
erfassen. Für das Hochladen von dSYM-Dateien und die gehostete Symbolisierung
folgen Sie [Apple-Abstürze und Hänger erfassen](/de/guides/apple-crashes-and-hangs).

Für Flask folgen Sie [Flask einrichten](/de/guides/flask).

Für React Native und Expo folgen Sie [React Native](/de/guides/react-native).
Der Leitfaden beschreibt den Projektschlüssel, ein sicheres Test-Log,
Zustellfehler und die Expo-Metro-Konfiguration für Source Maps in
Produktion.

## <span id="javascript-queue-tracing">Queue-Tracing in JavaScript</span>

Queue-Integrationen für Node sind eigene npm-Pakete. Installieren Sie die
LogBrew-Basispakete für JavaScript, das Integrationspaket und den Queue- oder
Broker-Client, den Ihre App bereits nutzt.

| Queue oder Broker | Installation |
| - | - |
| 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` |

Verwenden Sie diese Pakete für eine ausdrückliche Trace-Korrelation, die Ihre
App selbst steuert, rund um die Queue-Aufrufe, die Sie auswählen. LogBrew
übernimmt nicht Ihre Broker-Verbindung, erstellt keine Queues und patcht
standardmäßig nicht global jeden Client.

<Warning>
  Halten Sie Queue-Payloads, beliebige Nachrichten-Header, Broker-URLs und
  Bearer-Werte von Sitzung oder Konto aus der SDK-Konfiguration heraus.
  Verwenden Sie die projektbezogene Server-Ingest-Konfiguration von LogBrew.
</Warning>

## <span id="required-envelope-fields">Nativer Umschlag direkt senden</span>

Verwenden Sie `POST /api/telemetry/ingest` nur für einen eigenen Client, den
kein öffentliches LogBrew-SDK abdeckt. Öffentliche SDKs verwenden ihr eigenes
Batch-Format. Dieser Endpunkt akzeptiert dieses Format nicht.

Senden Sie 1 bis 512 Einträge in einem nativen Umschlag. Alle Einträge eines
Umschlags teilen sich Projekt, Dienst, Release, Umgebung und den optionalen
Trace-Kontext.

| Feld | Pflicht | Hinweise |
| - | - | - |
| `project_id` | Ja | UUID des LogBrew-Projekts. Sie muss zum Projekt des Ingest-Schlüssels passen. |
| `environment` | Ja | Umgebung der Bereitstellung. Höchstens 64 Zeichen, ohne Leerraum, `/` oder `\`. Der Wert `None` wird abgelehnt. |
| `release` | Ja | Codeversion. Höchstens 200 Zeichen, ohne `/`, `\`, Tabulatoren oder Zeilenumbrüche. Der Wert darf nicht `.` oder `..` sein. |
| `service_name` | Ja | Logischer Dienstname, zum Beispiel `checkout-api`. Er darf nicht leer sein. |
| `sdk_name` | Ja | Kennung des SDK oder eigenen Clients. |
| `sdk_version` | Ja | Version des SDK oder eigenen Clients. |
| `items` | Ja | 1 bis 512 Einträge vom Typ `log`, `trace_span`, `issue` oder `action`. |
| `trace_id` | Nein | Trace-ID, die korrelierte Einträge des Umschlags gemeinsam haben. Pflicht, wenn ein Eintrag `span_id` hat. |

### Felder eines Eintrags

Jeder Eintrag hat einen `type` und ein `data`-Objekt. Ein Log-Eintrag
verwendet `level`. Ein Issue-Eintrag verwendet `severity`. Beide akzeptieren
die Werte unter [Werte für den Schweregrad](/de/concepts/telemetry#severity-values).

| Feld | Gilt für | Hinweise |
| - | - | - |
| `id` | Alle Einträge | Optionale Ereignis-ID des Clients. 1 bis 200 Zeichen, eindeutig im Umschlag. |
| `span_id` | `log`, `issue`, `action` | Optional. 16 Hexadezimalzeichen, nicht nur Nullen. Der Umschlag muss `trace_id` haben. |
| `name` | `action` | Pflicht. Höchstens 64 UTF-8-Bytes. Darf nicht mit `$` beginnen, nicht mit Leerraum beginnen oder enden und keine Steuerzeichen oder unsichtbaren Formatierungszeichen enthalten. |

Senden Sie zu jedem Eintrag eine `id`, wenn Ihr Client Anfragen wiederholen
kann. Sendet eine Wiederholung einen angenommenen Eintrag mit derselben `id`
und demselben Inhalt erneut, speichert LogBrew ihn nicht noch einmal. Die
Antwort zählt diesen Eintrag in `already_accepted`.

### Beispielanfrage

Speichern Sie das JSON unten als `telemetry-envelope.json`. Ersetzen Sie die
Beispiel-Projekt-ID durch die genaue Projekt-ID Ihres Ingest-Schlüssels.
Setzen Sie die Zeitstempel auf die aktuelle UTC-Zeit des Testereignisses.
Verwenden Sie Ihre eigenen Werte für Dienst und Release.

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

Laden Sie den projektbezogenen Ingest-Wert über Ihre geschützte Konfiguration
in `LOGBREW_INGEST_BEARER`. Geben Sie ihn nicht aus, und verwenden Sie keine
Konto-Zugangsdaten. Der folgende Befehl sendet die Datei einmal. Er braucht
curl 7.76.0 oder neuer:

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

Lesen Sie HTTP-Status und Body. `--fail-with-body` behält einen Fehler-Body
und liefert bei HTTP-Fehlern einen Exit-Status ungleich null. Ein
Netzwerkfehler oder eine Zeitüberschreitung sagt Ihnen nicht, ob LogBrew die
Anfrage angenommen hat. Senden Sie dieselbe Datei nur dann erneut, wenn ihre
Einträge `id`-Werte haben. Ohne `id`-Werte kann ein zweites Senden die
Einträge doppelt speichern.

### Antwort

Eine erfolgreiche Anfrage liefert `200` mit der Anzahl der neuen Einträge pro
Datenstrom. `already_accepted` zählt Einträge, die eine frühere Anfrage
bereits zugestellt hat.

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

### Fehler

Ein ungültiger oder widerrufener Ingest-Schlüssel liefert `401`. Ein Schlüssel
für ein anderes Projekt liefert ebenfalls `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"
  }
}
```

Verwenden Sie einen projektbezogenen Ingest-Schlüssel. Ersetzen Sie ihn nicht
durch Konto-Zugangsdaten. Ein Artefakt-Schlüssel kann keine Telemetrie senden.

Ein Umschlag, der gegen eine Feldregel verstößt, liefert `422` mit dem Code
`validation_failed`. Das Feld `error` nennt die Regel. Das Feld `next` sagt
Ihnen, wie Sie die Anfrage korrigieren. Zum Beispiel liefert `"items": []`:

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

Senden Sie keinen Umschlag, wenn es keine Ereignisse gibt. Ein Umschlag mit
mehr als 512 Einträgen liefert `422` mit dem Fehler
`native telemetry envelope exceeds the item limit`. Teilen Sie ihn in Batches
mit höchstens 512 Einträgen auf. Behalten Sie in jedem Batch das Projekt und
den gemeinsamen Kontext bei.

Bei Nutzungslimits, Ratenlimits und Dienstausfällen folgen Sie dem
zurückgegebenen `code` unter [API-Fehler](/de/reference/api-errors).

<Tip>
  Legen Sie Release und Umgebung bei der SDK-Einrichtung fest. Erstellen Sie
  für jede Operation einen Trace-Kontext, oder setzen Sie ihn fort. Verwenden
  Sie eine Trace-ID nicht erneut für Vorgänge, die nichts miteinander zu tun
  haben.
</Tip>


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