SDK-integratie voor applicatietelemetrie

Installeer het SDK-pakket van LogBrew voor je runtime. De SDK maakt events op en levert ze af. De handleiding van het pakket noemt de eventtypen, de limieten en het gedrag bij nieuwe pogingen. Volg deze stappen voor elke integratie:

Installeer het SDK-pakket voor je runtime.
Houd de projectgebonden ingest-sleutel buiten versiebeheer.
Stel vaste waarden in voor service, omgeving en release.
Verzend één veilig testevent vanuit de applicatie.
Lees het afleverresultaat. Zoek daarna het event in LogBrew.

Een geaccepteerde batch heeft de LogBrew API bereikt. Filters kunnen de events toch verbergen. Kies het juiste project en tijdsbereik. Zorg daarna dat service, omgeving, release en signaaltype overeenkomen. Kies en test goedgekeurde velden voordat je het vastleggen inschakelt. Volg Productevents vastleggen om Analytics te vullen.

Signalen en gedeelde context

De eerste vijf kaarten zijn signalen. Release en omgeving zijn context voor die signalen. Ze zijn geen apart eventtype.

log

Een gestructureerd bericht met ernst, bron, tijd en veilige context.

trace_span

Eén bewerking met een gemeten duur, via trace- en span-ID’s gekoppeld aan de trace.

issue

Een vastgelegde fout, de ernst ervan en de foutdetails die de app heeft verzonden.

action

Een actie in je app, met optioneel een subject, een sessie en veilige eigenschappen.

metric

Eén numerieke meting met een naam, soort, waarde, eenheid en temporaliteit.

release en omgeving

De codeversie en omgeving die worden gekoppeld aan latere events binnen dezelfde SDK-scope.

Ernstwaarden

Gebruik info, warning, error of critical voor logs en issues. SDK’s en runtimes kunnen aliassen verzenden, zoals trace, debug, warn of fatal. LogBrew zet geaccepteerde aliassen om naar de canonieke waarden.

Installeren met een pakketbeheerder

Installeer het SDK-pakket voor de runtime die telemetrie verzendt. Gebruik de projectgebonden SDK- of ingest-configuratie uit LogBrew. Gebruik geen inloggegevens van je account als SDK-configuratie.

Runtime	Installatie
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	Voeg `https://github.com/LogBrewCo/sdk.git` toe via 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	Voeg `co.logbrew:logbrew-sdk:0.1.9` toe uit 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	Zet `cpp/logbrew-cpp/v0.2.3` vast met `FetchContent` van CMake.

Request-tracing in Node.js

Gebruik voor tracecorrelatie vanaf de root van het request @logbrew/sdk 0.1.16 of nieuwer en @logbrew/node 0.1.11 of nieuwer. Express vereist @logbrew/express 0.1.5 of nieuwer. Fastify en NestJS vereisen hun LogBrew-pakket in versie 0.1.6 of nieuwer. Deze integraties maken één request-span aan of zetten die voort. De spannaam gebruikt het herkende routetemplate. Logs, issues, acties en metrics binnen het request erven de trace- en spancontext van het request. Een nieuwer pakket voegt geen context toe aan events die vóór de upgrade zijn verzonden. De standaardintegratie voor requests legt geen request- of responsebody’s, querystrings, willekeurige headers of ruwe traceparent-waarden vast.

ASP.NET Core

CLI v0.1.55 of nieuwer herkent .NET 10-projecten die Microsoft.NET.Sdk.Web gebruiken. Bekijk het installatieplan vooraf vanuit de hoofdmap van het project. Deze opdracht wijzigt je bestanden niet:

logbrew setup --json

Het plan voor de uitgebrachte versie installeert de hostintegratie:

dotnet add package LogBrew.AspNetCore --version 0.1.2

Stel LOGBREW_SERVER_API_KEY, LOGBREW_SERVICE_NAME, LOGBREW_ENVIRONMENT en LOGBREW_RELEASE in buiten versiebeheer. Registreer LogBrew bij de host en plaats de middleware van LogBrew na de routing:

using LogBrew;

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

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

Zonder LOGBREW_SERVER_API_KEY doen beide registratieaanroepen veilig niets. Het NuGet-pakket voor ASP.NET Core is de uitgebrachte hostintegratie. De openbare handleiding van het pakket behandelt de levenscyclus van de host, het vastleggen van requests en issues, privacygrenzen en herstel.

Java met Maven of Gradle

CLI v0.1.54 of nieuwer herkent pom.xml, build.gradle en build.gradle.kts. Bekijk het installatieplan vooraf vanuit de hoofdmap van het project. Deze opdracht wijzigt je bestanden niet:

logbrew setup --json

Voeg voor Maven het uitgebrachte pakket toe:

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

Voeg voor Gradle Kotlin DSL hetzelfde artefact uit Maven Central toe:

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

Gebruik Java 11 of nieuwer. Applicaties met Spring Boot 3 en 4 kunnen een eigen LogBrewClient-bean aanbieden. Die bean schakelt optionele integraties in voor requests, exceptions, de HTTP-client, JDBC en de cache. Vastleggen via Spring Kafka schakel je expliciet in met logbrew.kafka.enabled=true. Het gebruikt de bestaande Spring Kafka-dependency en client-bean van de applicatie. Het artefact van de Java-SDK op Maven Central is het uitgebrachte pakket. De openbare handleiding behandelt begrensde aflevering via HTTP, afsluiten, logging, Spring-configuratie, Kafka-correlatie en privacygrenzen.

C++ met CMake

De C++-SDK vereist C++17 en CMake 3.16 of nieuwer. CLI v0.1.39 of nieuwer herkent een CMakeLists.txt in de hoofdmap. Voer logbrew setup --json uit om dit installatieplan vooraf te bekijken zonder je bestanden te wijzigen:

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)

Het core-target heeft geen dependencies. Wil je batches verzenden via het optionele libcurl-transport? Vervang dan de laatste aanroep van FetchContent_MakeAvailable en de targetkoppeling hierboven door:

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

Configureer de applicatie. Bouw de applicatie daarna om de gekozen SDK-versie te testen:

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

Kan je build de SDK-monorepo niet ophalen? Gebruik dan het aparte C++-bestand logbrew-cpp-0.2.3.tar.gz uit de C++ 0.2.3-release. Het uitgepakte pakket ondersteunt cmake --install en find_package(LogBrew 0.2.3 CONFIG REQUIRED). De handleiding van het pakket behandelt getypeerde context, issuebewijs, span-events, metrics, acties en aflevering via HTTP.

Source maps voor JavaScript

Volg voor Vite-builds Source maps voor JavaScript. Die handleiding behandelt de plug-in, de artefactsleutel, controles van de upload en een nieuw issue met de oorspronkelijke bronlocaties.

Apple, Flask en React Native

Gebruik het Swift-product LogBrew voor telemetrie. Voeg LogBrewCrash alleen toe om crashes of vastlopers op Apple-platforms vast te leggen. Volg Apple-crashes en vastlopers voor het uploaden van dSYM’s en gehoste symbolisatie. Volg voor Flask de handleiding Flask. Volg voor React Native en Expo React Native. Die handleiding behandelt de projectsleutel, een veilige testlog, afleverfouten en de Expo Metro-configuratie voor source maps in productie.

Queue-tracing in JavaScript

Integraties voor queues in Node zijn aparte npm-pakketten. Installeer de basispakketten van LogBrew voor JavaScript, het integratiepakket en de queue- of brokerclient die je app al gebruikt.

Queue of broker	Installatie
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`

Gebruik deze pakketten voor expliciete tracecorrelatie die je app zelf beheert, rond de queue-aanroepen die je kiest. LogBrew beheert je brokerverbinding niet, maakt geen queues aan en patcht standaard niet elke client globaal.

Houd queue-payloads, willekeurige berichtheaders, broker-URL’s en bearer-waarden van sessies of accounts buiten de SDK-configuratie. Gebruik de projectgebonden ingest-configuratie voor servers uit LogBrew.

Directe native envelop

Gebruik POST /api/telemetry/ingest alleen voor een eigen client die niet door een openbare LogBrew-SDK wordt ondersteund. Openbare SDK’s gebruiken hun eigen batchformaat. Dit endpoint accepteert dat formaat niet. Verzend 1 tot 512 items in één native envelop. Alle items in één envelop delen het project, de service, de release, de omgeving en de optionele tracecontext.

Veld	Verplicht	Opmerkingen
`project_id`	Ja	UUID van het LogBrew-project. Moet overeenkomen met het project van de ingest-sleutel.
`environment`	Ja	Deploymentomgeving. Maximaal 64 tekens, zonder witruimte, `/` of `\`. De waarde `None` wordt geweigerd.
`release`	Ja	Codeversie. Maximaal 200 tekens, zonder `/`, `\`, tabs of regeleinden. Mag niet `.` of `..` zijn.
`service_name`	Ja	Logische servicenaam, zoals `checkout-api`. Mag niet leeg zijn.
`sdk_name`	Ja	Naam die de SDK of eigen client identificeert.
`sdk_version`	Ja	Versie van de SDK of eigen client.
`items`	Ja	1 tot 512 items van het type `log`, `trace_span`, `issue` of `action`.
`trace_id`	Nee	Trace-ID dat gecorreleerde items in de envelop delen. Verplicht als een item `span_id` heeft.

Itemvelden

Elk item heeft een type en een data-object. Een logitem gebruikt level. Een issue-item gebruikt severity. Beide accepteren de waarden in Ernstwaarden.

Itemveld	Geldt voor	Opmerkingen
`id`	Alle items	Optioneel event-ID van de client. 1 tot 200 tekens, uniek binnen de envelop.
`span_id`	`log`, `issue`, `action`	Optioneel. 16 hexadecimale tekens, niet allemaal nullen. De envelop moet `trace_id` hebben.
`name`	`action`	Verplicht. Maximaal 64 UTF-8-bytes. Mag niet beginnen met `$`, niet beginnen of eindigen met witruimte en geen stuurtekens of onzichtbare opmaaktekens bevatten.

Verzend bij elk item een id als je client nieuwe pogingen kan doen. Verzendt een nieuwe poging een geaccepteerd item opnieuw met dezelfde id en inhoud? Dan slaat LogBrew het niet opnieuw op. De response telt dat item in already_accepted.

Voorbeeldrequest

Sla de JSON hieronder op als telemetry-envelope.json. Vervang het voorbeeld-ID van het project door het exacte project-ID van je ingest-sleutel. Zet de tijdstempels op de huidige UTC-tijd van het testevent. Gebruik je eigen waarden voor service en release.

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

Laad de projectgebonden ingest-waarde via je beveiligde configuratie in LOGBREW_INGEST_BEARER. Toon de waarde niet en gebruik geen toegangsgegevens van je account. De volgende opdracht verzendt het bestand één keer. Daarvoor is curl 7.76.0 of nieuwer nodig:

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

Lees de HTTP-status en de body. --fail-with-body bewaart de body van een fout en geeft bij HTTP-fouten een exitstatus die niet nul is. Een netwerkfout of time-out vertelt je niet of LogBrew het request heeft geaccepteerd. Verzend hetzelfde bestand alleen opnieuw als de items id-waarden hebben. Zonder id-waarden kan een tweede verzending de items twee keer opslaan.

Response

Een geslaagd request geeft 200 terug met het aantal nieuwe items per stream. already_accepted telt items die een eerder request al heeft afgeleverd.

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

Fouten

Een ongeldige of ingetrokken ingest-sleutel geeft 401. Een sleutel voor een ander project geeft ook 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"
  }
}

Gebruik een projectgebonden ingest-sleutel. Vervang die niet door toegangsgegevens van je account. Met een artefactsleutel kun je geen telemetrie verzenden. Een envelop die een veldregel overtreedt, geeft 422 met code validation_failed. Het veld error noemt de regel. Het veld next vertelt hoe je het request herstelt. "items": [] geeft bijvoorbeeld:

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

Verzend geen envelop als er geen events zijn. Een envelop met meer dan 512 items geeft 422 met de fout native telemetry envelope exceeds the item limit. Splits de envelop op in batches van maximaal 512 items. Houd het project en de gedeelde context in elke batch. Volg bij gebruikslimieten, rate limits en storingen van de service de teruggegeven code in API-fouten.

Stel release en omgeving in tijdens de SDK-installatie. Maak voor elke bewerking een tracecontext aan of zet de bestaande voort. Gebruik één trace-ID niet opnieuw voor werk dat er niets mee te maken heeft.

Aan de slag

Concepten

Installeren en verzenden

Onderzoeken

CLI en agents

Ondersteuning

SDK-integratie voor applicatietelemetrie

Signalen en gedeelde context

log

trace_span

issue

action

metric

release en omgeving

Ernstwaarden

Installeren met een pakketbeheerder

Request-tracing in Node.js

ASP.NET Core

Java met Maven of Gradle

C++ met CMake

Source maps voor JavaScript

Apple, Flask en React Native

Queue-tracing in JavaScript

Directe native envelop

Itemvelden

Voorbeeldrequest

Response

Fouten

​Signalen en gedeelde context

log

trace_span

issue

action

metric

release en omgeving

​Ernstwaarden

​Installeren met een pakketbeheerder

​Request-tracing in Node.js

​ASP.NET Core

​Java met Maven of Gradle

​C++ met CMake

​Source maps voor JavaScript

​Apple, Flask en React Native

​Queue-tracing in JavaScript

​Directe native envelop

​Itemvelden

​Voorbeeldrequest

​Response

​Fouten

Signalen en gedeelde context

Ernstwaarden

Installeren met een pakketbeheerder

Request-tracing in Node.js

ASP.NET Core

Java met Maven of Gradle

C++ met CMake

Source maps voor JavaScript

Apple, Flask en React Native

Queue-tracing in JavaScript

Directe native envelop

Itemvelden

Voorbeeldrequest

Response

Fouten