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

# Integrazione dell'SDK per la telemetria delle applicazioni

> Scegli un SDK di LogBrew per il tuo runtime e configura la chiave di ingestione. Invia la telemetria dell'applicazione e trova l'evento di test nel progetto.

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:

1. Installa il pacchetto SDK per il tuo runtime.
2. Tieni la chiave di ingestione del progetto fuori dal controllo di versione.
3. Imposta valori stabili per servizio, ambiente e release.
4. Invia un evento di test sicuro dall'applicazione.
5. 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](/it/guides/safe-capture).
Per popolare Analisi, segui [Acquisizione eventi di prodotto](/it/guides/product-events).

## <span id="item-types">Segnali e contesto condiviso</span>

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

<CardGroup cols={2}>
  <Card title="log" icon="file-text">
    Un messaggio strutturato con gravità, origine, orario e contesto sicuro.
  </Card>

  <Card title="trace_span" icon="route">
    Una singola operazione cronometrata, collegata alla sua traccia tramite gli ID di traccia e di span.
  </Card>

  <Card title="issue" icon="bug">
    Un errore acquisito, la sua gravità e i dettagli dell'errore inviati dall'app.
  </Card>

  <Card title="action" icon="mouse-pointer-click">
    Un'azione nella tua app, con soggetto, sessione e proprietà sicure facoltativi.
  </Card>

  <Card title="metric" icon="chart-line">
    Una singola misura numerica con nome, tipo, valore, unità e temporalità.
  </Card>

  <Card title="release e ambiente" icon="tags">
    La versione del codice e l'ambiente associati agli eventi successivi nello stesso ambito dell'SDK.
  </Card>
</CardGroup>

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

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

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

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

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

Senza `LOGBREW_SERVER_API_KEY`, entrambe le chiamate di registrazione non
hanno effetto e non causano errori. Il
[pacchetto NuGet ASP.NET Core](https://www.nuget.org/packages/LogBrew.AspNetCore/0.1.2)
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:

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

Per Maven, aggiungi il pacchetto pubblicato:

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

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

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

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

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

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:

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

```bash theme={null}
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](https://github.com/LogBrewCo/sdk/releases/tag/cpp/logbrew-cpp/v0.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](/it/guides/source-maps).
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](/it/guides/apple-crashes-and-hangs).

Per Flask, segui [Configura Flask](/it/guides/flask).

Per React Native ed Expo, segui [React Native](/it/guides/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.

## <span id="javascript-queue-tracing">Tracciamento delle code JavaScript</span>

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.

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

## <span id="required-envelope-fields">Envelope nativo diretto</span>

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

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

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

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:

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

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.

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

### Errori

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

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:

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

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

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


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