Integrazione dell'SDK per la telemetria delle applicazioni

Installa il pacchetto SDK di LogBrew per il tuo runtime. L’SDK formatta gli eventi e li consegna. La guida del pacchetto elenca i tipi di evento, i limiti e il comportamento dei nuovi tentativi. Segui questi passaggi per ogni integrazione:

Installa il pacchetto SDK per il tuo runtime.
Tieni la chiave di ingestione del progetto fuori dal controllo di versione.
Imposta valori stabili per servizio, ambiente e release.
Invia un evento di test sicuro dall’applicazione.
Leggi il risultato della consegna. Poi trova l’evento in LogBrew.

Se un batch è stato accettato, ha raggiunto l’API di LogBrew. I filtri possono comunque nasconderne gli eventi. Seleziona il progetto e l’intervallo di tempo corretti. Poi verifica che servizio, ambiente, release e tipo di segnale corrispondano. Prima di attivare l’acquisizione, seleziona e verifica i campi approvati. Per popolare Analisi, segui Acquisizione eventi di prodotto.

Segnali e contesto condiviso

Le prime cinque schede sono segnali. Release e ambiente sono il contesto di quei segnali. Non sono un tipo di evento a sé.

log

Un messaggio strutturato con gravità, origine, orario e contesto sicuro.

trace_span

Una singola operazione cronometrata, collegata alla sua traccia tramite gli ID di traccia e di span.

issue

Un errore acquisito, la sua gravità e i dettagli dell’errore inviati dall’app.

action

Un’azione nella tua app, con soggetto, sessione e proprietà sicure facoltativi.

metric

Una singola misura numerica con nome, tipo, valore, unità e temporalità.

release e ambiente

La versione del codice e l’ambiente associati agli eventi successivi nello stesso ambito dell’SDK.

Valori di gravità

Per log e problemi usa info, warning, error o critical. SDK e runtime possono inviare alias come trace, debug, warn o fatal. LogBrew normalizza gli alias accettati nei valori canonici.

Installazione con un gestore di pacchetti

Installa il pacchetto SDK per il runtime che invia la telemetria. Usa la configurazione SDK o di ingestione del progetto fornita da LogBrew. Non usare i valori di accesso dell’account come configurazione dell’SDK.

Runtime	Installazione
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	Aggiungi `https://github.com/LogBrewCo/sdk.git` tramite 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	Aggiungi `co.logbrew:logbrew-sdk:0.1.9` da 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	Fissa `cpp/logbrew-cpp/v0.2.3` con `FetchContent` di CMake.

Tracciamento delle richieste in Node.js

Per correlare le tracce a partire dalla radice della richiesta, usa @logbrew/sdk 0.1.16 o successivo e @logbrew/node 0.1.11 o successivo. Express richiede @logbrew/express 0.1.5 o successivo. Fastify e NestJS richiedono il rispettivo pacchetto LogBrew alla versione 0.1.6 o successiva. Queste integrazioni creano o continuano uno span per la richiesta. Il nome dello span usa il modello della route corrispondente. Log, problemi, azioni e metriche all’interno della richiesta ereditano il suo contesto di traccia e di span. Un pacchetto più recente non aggiunge contesto agli eventi inviati prima dell’aggiornamento. L’integrazione predefinita per le richieste non acquisisce i corpi di richiesta o di risposta, le query string, header arbitrari né valori traceparent grezzi.

ASP.NET Core

La CLI v0.1.55 o successiva rileva i progetti .NET 10 che usano Microsoft.NET.Sdk.Web. Visualizza in anteprima il piano di configurazione dalla radice del progetto. Questo comando non modifica i tuoi file:

logbrew setup --json

Il piano per il pacchetto pubblicato installa l’integrazione con l’host:

dotnet add package LogBrew.AspNetCore --version 0.1.2

Imposta LOGBREW_SERVER_API_KEY, LOGBREW_SERVICE_NAME, LOGBREW_ENVIRONMENT e LOGBREW_RELEASE fuori dal controllo di versione. Registra LogBrew nell’host e posiziona il suo middleware dopo il routing:

using LogBrew;

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

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

Senza LOGBREW_SERVER_API_KEY, entrambe le chiamate di registrazione non hanno effetto e non causano errori. Il pacchetto NuGet ASP.NET Core identifica l’integrazione con l’host pubblicata. La sua guida pubblica copre ciclo di vita dell’host, acquisizione delle richieste, acquisizione dei problemi, limiti di privacy e ripristino.

Java con Maven o Gradle

La CLI v0.1.54 o successiva rileva pom.xml, build.gradle e build.gradle.kts. Visualizza in anteprima il piano di configurazione dalla radice del progetto. Questo comando non modifica i tuoi file:

logbrew setup --json

Per Maven, aggiungi il pacchetto pubblicato:

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

Per Gradle Kotlin DSL, aggiungi lo stesso artefatto di Maven Central:

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

Usa Java 11 o successivo. Le applicazioni Spring Boot 3 e 4 possono esporre un bean LogBrewClient gestito dall’app. Il bean attiva integrazioni facoltative per richieste, eccezioni, client HTTP, JDBC e cache. L’acquisizione di Spring Kafka va attivata in modo esplicito con logbrew.kafka.enabled=true. Usa la dipendenza Spring Kafka e il bean client già presenti nell’applicazione. L’artefatto dell’SDK Java su Maven Central identifica il pacchetto pubblicato. La sua guida pubblica copre la consegna HTTP con limiti, lo spegnimento, il logging, la configurazione di Spring, la correlazione con Kafka e i limiti di privacy.

C++ con CMake

L’SDK C++ richiede C++17 e CMake 3.16 o successivo. La CLI v0.1.39 o successiva rileva un CMakeLists.txt nella radice. Esegui logbrew setup --json per vedere in anteprima questo piano di configurazione senza modificare i tuoi file:

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)

Il target principale non ha dipendenze. Per inviare i batch tramite il trasporto libcurl facoltativo, sostituisci la chiamata finale FetchContent_MakeAvailable e il collegamento del target qui sopra con:

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

Configura l’applicazione. Poi compilala per testare la versione dell’SDK selezionata:

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

Per le build che non possono scaricare il monorepo dell’SDK, usa l’asset dedicato logbrew-cpp-0.2.3.tar.gz dalla release C++ 0.2.3. Il pacchetto estratto supporta cmake --install e find_package(LogBrew 0.2.3 CONFIG REQUIRED). La sua guida copre contesto tipizzato, prove dei problemi, eventi degli span, metriche, azioni e consegna HTTP.

Source map JavaScript

Per le build Vite, segui Source map JavaScript. La guida copre il plugin, la chiave per artefatti, i controlli del caricamento e un nuovo problema con le posizioni nel codice sorgente originale.

Apple, Flask e React Native

Usa il prodotto Swift LogBrew per la telemetria. Aggiungi LogBrewCrash solo per acquisire crash o blocchi su Apple. Per il caricamento dei dSYM e la simbolizzazione ospitata, segui Acquisisci crash e blocchi Apple. Per Flask, segui Configura Flask. Per React Native ed Expo, segui React Native. La guida copre la chiave del progetto, un log di test sicuro, gli errori di consegna e la configurazione di Expo Metro per le source map di produzione.

Tracciamento delle code JavaScript

Le integrazioni per le code in Node sono pacchetti npm separati. Installa i pacchetti JavaScript di base di LogBrew, il pacchetto di integrazione e il client della coda o del broker che la tua app usa già.

Coda o broker	Installazione
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`

Usa questi pacchetti per una correlazione delle tracce esplicita, gestita dall’app, intorno alle chiamate alla coda che scegli. LogBrew non gestisce la connessione al broker, non crea code e per impostazione predefinita non modifica globalmente ogni client.

Tieni fuori dalla configurazione dell’SDK i payload delle code, gli header arbitrari dei messaggi, gli URL dei broker e i valori bearer di sessione o dell’account. Usa la configurazione di ingestione lato server del progetto fornita da LogBrew.

Envelope nativo diretto

Usa POST /api/telemetry/ingest solo per un client personalizzato che nessun SDK pubblico di LogBrew supporta. Gli SDK pubblici usano un loro formato di batch. Questo endpoint non accetta quel formato. Invia da 1 a 512 elementi in un envelope nativo. Tutti gli elementi di un envelope condividono progetto, servizio, release, ambiente e l’eventuale contesto di traccia.

Campo	Obbligatorio	Note
`project_id`	Sì	UUID del progetto LogBrew. Deve corrispondere al progetto della chiave di ingestione.
`environment`	Sì	Ambiente di deploy. Al massimo 64 caratteri, senza caratteri di spaziatura, `/` o `\`. LogBrew rifiuta il valore `None`.
`release`	Sì	Versione del codice. Al massimo 200 caratteri, senza `/`, `\`, tabulazioni o a capo. Non può essere `.` o `..`.
`service_name`	Sì	Nome logico del servizio, come `checkout-api`. Non può essere vuoto.
`sdk_name`	Sì	Identificativo dell’SDK o del client personalizzato.
`sdk_version`	Sì	Versione dell’SDK o del client personalizzato.
`items`	Sì	Da 1 a 512 elementi `log`, `trace_span`, `issue` o `action`.
`trace_id`	No	ID traccia condiviso dagli elementi correlati dell’envelope. Obbligatorio quando un elemento ha `span_id`.

Campi degli elementi

Ogni elemento ha un type e un oggetto data. Un elemento di log usa level. Un elemento di problema usa severity. Entrambi accettano i valori indicati in Valori di gravità.

Campo dell’elemento	Si applica a	Note
`id`	Tutti gli elementi	ID evento facoltativo del client. Da 1 a 200 caratteri, univoco nell’envelope.
`span_id`	`log`, `issue`, `action`	Facoltativo. 16 caratteri esadecimali, non tutti zero. L’envelope deve avere `trace_id`.
`name`	`action`	Obbligatorio. Al massimo 64 byte UTF-8. Non deve iniziare con `$`, iniziare o finire con spazi, né contenere caratteri di controllo o di formattazione invisibili.

Invia un id con ogni elemento quando il tuo client può ripetere l’invio. Quando un nuovo tentativo invia di nuovo un elemento già accettato con lo stesso id e lo stesso contenuto, LogBrew non lo salva di nuovo. La risposta conta quell’elemento in already_accepted.

Richiesta di esempio

Salva il JSON qui sotto come telemetry-envelope.json. Sostituisci l’ID progetto di esempio con l’ID esatto del progetto della tua chiave di ingestione. Imposta i timestamp all’ora UTC corrente dell’evento di test. Usa i tuoi valori di servizio e 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 }
      }
    }
  ]
}

Carica il valore di ingestione del progetto in LOGBREW_INGEST_BEARER tramite la tua configurazione protetta. Non stamparlo e non usare una credenziale dell’account. Il comando seguente invia il file una volta. Richiede curl 7.76.0 o successivo:

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

Leggi lo stato HTTP e il corpo della risposta. --fail-with-body conserva il corpo dell’errore e restituisce un codice di uscita diverso da zero per gli errori HTTP. Un errore di rete o un timeout non ti dice se LogBrew ha accettato la richiesta. Invia di nuovo lo stesso file solo se i suoi elementi hanno valori id. Senza valori id, un secondo invio può salvare gli elementi due volte.

Risposta

Una richiesta riuscita restituisce 200 con il conteggio dei nuovi elementi per flusso. already_accepted conta gli elementi già consegnati da una richiesta precedente.

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

Errori

Una chiave di ingestione non valida o revocata restituisce 401. Anche una chiave di un altro progetto restituisce 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"
  }
}

Usa una chiave di ingestione del progetto. Non sostituirla con una credenziale dell’account. Una chiave per artefatti non può inviare telemetria. Un envelope che viola la regola di un campo restituisce 422 con codice validation_failed. Il campo error indica la regola. Il campo next ti dice come correggere la richiesta. Per esempio, "items": [] restituisce:

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

Non inviare un envelope quando non ci sono eventi. Un envelope con più di 512 elementi restituisce 422 con l’errore native telemetry envelope exceeds the item limit. Dividilo in batch di massimo 512 elementi. Mantieni il progetto e il contesto condiviso in ogni batch. Per limiti di utilizzo, limiti di frequenza ed errori del servizio, segui il code restituito in Errori API.

Imposta release e ambiente nella configurazione dell’SDK. Crea o continua il contesto di traccia per ogni operazione. Non riusare lo stesso ID traccia per lavori non correlati.

Per iniziare

Concetti

Installare e inviare

Indagare

CLI e agenti

Supporto

Integrazione dell'SDK per la telemetria delle applicazioni

Segnali e contesto condiviso

log

trace_span

issue

action

metric

release e ambiente

Valori di gravità

Installazione con un gestore di pacchetti

Tracciamento delle richieste in Node.js

ASP.NET Core

Java con Maven o Gradle

C++ con CMake

Source map JavaScript

Apple, Flask e React Native

Tracciamento delle code JavaScript

Envelope nativo diretto

Campi degli elementi

Richiesta di esempio

Risposta

Errori

​Segnali e contesto condiviso

log

trace_span

issue

action

metric

release e ambiente

​Valori di gravità

​Installazione con un gestore di pacchetti

​Tracciamento delle richieste in Node.js

​ASP.NET Core

​Java con Maven o Gradle

​C++ con CMake

​Source map JavaScript

​Apple, Flask e React Native

​Tracciamento delle code JavaScript

​Envelope nativo diretto

​Campi degli elementi

​Richiesta di esempio

​Risposta

​Errori

Segnali e contesto condiviso

Valori di gravità

Installazione con un gestore di pacchetti

Tracciamento delle richieste in Node.js

ASP.NET Core

Java con Maven o Gradle

C++ con CMake

Source map JavaScript

Apple, Flask e React Native

Tracciamento delle code JavaScript

Envelope nativo diretto

Campi degli elementi

Richiesta di esempio

Risposta

Errori