Intégration du SDK pour la télémétrie applicative

Installez le paquet SDK LogBrew adapté à votre runtime. Le SDK met en forme les signaux et les envoie. Le guide du paquet liste ses types de signaux, ses limites et son comportement en cas de nouvelle tentative. Suivez ces étapes pour chaque intégration :

Installez le paquet SDK de votre runtime.
Gardez la clé d’ingestion du projet hors du dépôt de code.
Définissez des valeurs stables pour le service, l’environnement et la version.
Envoyez un signal de test sans risque depuis l’application.
Lisez le résultat de l’envoi. Trouvez ensuite le signal dans LogBrew.

Un lot accepté a atteint l’API LogBrew. Les filtres peuvent quand même cacher ses signaux. Sélectionnez le bon projet et la bonne période. Vérifiez ensuite le service, l’environnement, la version et le type de signal. Avant d’activer la capture, choisissez et testez les champs approuvés. Pour alimenter la vue Analyses, suivez Capture d’événements produit.

Signaux et contexte partagé

Les cinq premières cartes sont des signaux. La version et l’environnement forment le contexte de ces signaux. Ils ne sont pas un type de signal distinct.

log

Un message structuré avec une gravité, une source, une heure et un contexte sans risque.

trace_span

Une opération chronométrée, reliée à sa trace par les ID de trace et de span.

issue

Un échec capturé, sa gravité et les détails de l’erreur envoyés par l’application.

action

Une action dans votre application, avec en option un sujet, une session et des propriétés sans risque.

metric

Une mesure numérique avec un nom, un type, une valeur, une unité et une temporalité.

Version et environnement

La version du code et l’environnement associés aux signaux suivants dans le même périmètre du SDK.

Valeurs de gravité

Utilisez info, warning, error ou critical pour les logs et les problèmes. Les SDK et les runtimes peuvent envoyer des alias comme trace, debug, warn ou fatal. LogBrew convertit les alias acceptés en valeurs canoniques.

Installer avec un gestionnaire de paquets

Installez le paquet SDK du runtime qui envoie la télémétrie. Utilisez la configuration SDK ou d’ingestion limitée au projet fournie par LogBrew. N’utilisez pas les informations de connexion du compte comme configuration SDK.

Runtime	Installation
JavaScript	`npm install @logbrew/sdk`
Navigateur	`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	Ajoutez `https://github.com/LogBrewCo/sdk.git` avec 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	Ajoutez `co.logbrew:logbrew-sdk:0.1.9` depuis 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	Figez le tag `cpp/logbrew-cpp/v0.2.3` avec `FetchContent` de CMake.

Traçage des requêtes Node.js

Pour corréler les signaux avec une trace qui démarre à la requête, utilisez @logbrew/sdk 0.1.16 ou une version plus récente et @logbrew/node 0.1.11 ou une version plus récente. Express nécessite @logbrew/express 0.1.5 ou une version plus récente. Fastify et NestJS nécessitent leur paquet LogBrew en version 0.1.6 ou plus récente. Ces intégrations créent ou poursuivent un span de requête. Le nom du span utilise le modèle de route correspondant. Les logs, problèmes, actions et métriques émis pendant la requête héritent de son contexte de trace et de span. Un paquet plus récent n’ajoute pas de contexte aux signaux envoyés avant la mise à jour. Par défaut, l’intégration des requêtes ne capture ni les corps de requête ou de réponse, ni les chaînes de requête, ni les en-têtes arbitraires, ni les valeurs traceparent brutes.

ASP.NET Core

La CLI v0.1.55 ou plus récente détecte les projets .NET 10 qui utilisent Microsoft.NET.Sdk.Web. Prévisualisez le plan de configuration depuis la racine du projet. Cette commande ne modifie pas vos fichiers :

logbrew setup --json

Le plan installe l’intégration d’hôte publiée :

dotnet add package LogBrew.AspNetCore --version 0.1.2

Définissez LOGBREW_SERVER_API_KEY, LOGBREW_SERVICE_NAME, LOGBREW_ENVIRONMENT et LOGBREW_RELEASE hors du dépôt de code. Enregistrez LogBrew auprès de l’hôte et placez son middleware après le routage :

using LogBrew;

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

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

Sans LOGBREW_SERVER_API_KEY, les deux appels d’enregistrement ne font rien et restent sans risque. Le paquet NuGet ASP.NET Core identifie l’intégration d’hôte publiée. Son guide public couvre le cycle de vie de l’hôte, la capture des requêtes, la capture des problèmes, les limites de confidentialité et la reprise après erreur.

Java avec Maven ou Gradle

La CLI v0.1.54 ou plus récente détecte pom.xml, build.gradle et build.gradle.kts. Prévisualisez le plan de configuration depuis la racine du projet. Cette commande ne modifie pas vos fichiers :

logbrew setup --json

Pour Maven, ajoutez le paquet publié :

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

Pour le DSL Kotlin de Gradle, ajoutez le même artefact Maven Central :

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

Utilisez Java 11 ou une version plus récente. Les applications Spring Boot 3 et 4 peuvent exposer un bean LogBrewClient géré par l’application. Ce bean active des intégrations facultatives pour les requêtes, les exceptions, le client HTTP, JDBC et le cache. La capture Spring Kafka s’active uniquement de façon explicite, avec logbrew.kafka.enabled=true. Elle utilise la dépendance Spring Kafka et le bean client déjà présents dans l’application. L’artefact du SDK Java sur Maven Central identifie le paquet publié. Son guide public couvre l’envoi HTTP limité, l’arrêt, la journalisation, la configuration Spring, la corrélation Kafka et les limites de confidentialité.

C++ avec CMake

Le SDK C++ nécessite C++17 et CMake 3.16 ou une version plus récente. La CLI v0.1.39 ou plus récente détecte un CMakeLists.txt à la racine. Exécutez logbrew setup --json pour prévisualiser ce plan de configuration sans modifier vos fichiers :

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)

La cible principale n’a aucune dépendance. Pour envoyer des lots avec le transport libcurl facultatif, remplacez le dernier appel FetchContent_MakeAvailable et la liaison de cible ci-dessus par :

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

Configurez l’application. Compilez-la ensuite pour tester la version du SDK choisie :

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

Pour les builds qui ne peuvent pas récupérer le monorepo du SDK, utilisez la ressource dédiée logbrew-cpp-0.2.3.tar.gz de la version publiée C++ 0.2.3. Le paquet extrait prend en charge cmake --install et find_package(LogBrew 0.2.3 CONFIG REQUIRED). Son guide couvre le contexte typé, les preuves des problèmes, les événements de span, les métriques, les actions et l’envoi HTTP.

Source maps JavaScript

Pour les builds Vite, suivez Source maps JavaScript. Ce guide couvre le plugin, la clé d’artefact, les vérifications de l’import et un nouveau problème avec les emplacements du code source d’origine.

Apple, Flask et React Native

Utilisez le produit Swift LogBrew pour la télémétrie. Ajoutez LogBrewCrash uniquement pour capturer les plantages ou blocages Apple. Pour l’import des dSYM et la symbolisation hébergée, suivez Plantages et blocages Apple. Pour Flask, suivez le guide Flask. Pour React Native et Expo, suivez React Native. Ce guide couvre la clé du projet, un log de test sans risque, les erreurs d’envoi et la configuration Expo Metro pour les source maps de production.

Traçage des files de messages en JavaScript

Les intégrations de files de messages pour Node sont des paquets npm distincts. Installez les paquets JavaScript de base de LogBrew, le paquet d’intégration et le client de file de messages ou de broker que votre application utilise déjà.

File de messages ou 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`

Utilisez ces paquets pour une corrélation de traces explicite, gérée par l’application, autour des appels de file de messages que vous choisissez. Par défaut, LogBrew ne gère pas votre connexion au broker, ne crée pas de files de messages et ne modifie pas globalement chaque client.

Ne mettez dans la configuration du SDK ni contenu des messages de la file, ni en-têtes de message arbitraires, ni URL de broker, ni jetons de session ou de compte. Utilisez la configuration d’ingestion serveur limitée au projet fournie par LogBrew.

Enveloppe native directe

Utilisez POST /api/telemetry/ingest uniquement pour un client personnalisé qu’aucun SDK LogBrew public ne prend en charge. Les SDK publics utilisent leur propre format de lot. Ce point de terminaison n’accepte pas ce format. Envoyez de 1 à 512 éléments dans une enveloppe native. Tous les éléments d’une enveloppe partagent le projet, le service, la version, l’environnement et le contexte de trace facultatif.

Champ	Requis	Remarques
`project_id`	Oui	UUID du projet LogBrew. Il doit correspondre au projet de la clé d’ingestion.
`environment`	Oui	Environnement de déploiement. 64 caractères au maximum, sans espace, `/` ni `\`. La valeur `None` est rejetée.
`release`	Oui	Version du code. 200 caractères au maximum, sans `/`, `\`, tabulation ni saut de ligne. Elle ne peut pas valoir `.` ou `..`.
`service_name`	Oui	Nom logique du service, comme `checkout-api`. Il ne doit pas être vide.
`sdk_name`	Oui	Identifiant du SDK ou du client personnalisé.
`sdk_version`	Oui	Version du SDK ou du client personnalisé.
`items`	Oui	De 1 à 512 éléments `log`, `trace_span`, `issue` ou `action`.
`trace_id`	Non	ID de trace partagé par les éléments corrélés de l’enveloppe. Requis quand un élément a un `span_id`.

Champs des éléments

Chaque élément a un type et un objet data. Un élément de log utilise level. Un élément de problème utilise severity. Les deux acceptent les valeurs décrites dans Valeurs de gravité.

Champ d’élément	S’applique à	Remarques
`id`	Tous les éléments	ID d’événement client facultatif. De 1 à 200 caractères, unique dans l’enveloppe.
`span_id`	`log`, `issue`, `action`	Facultatif. 16 caractères hexadécimaux, pas tous à zéro. L’enveloppe doit avoir un `trace_id`.
`name`	`action`	Requis. 64 octets UTF-8 au maximum. Il ne doit pas commencer par `$`, ni commencer ou finir par un espace, ni contenir de caractères de contrôle ou de mise en forme invisibles.

Envoyez un id avec chaque élément si votre client peut réessayer. Quand une nouvelle tentative renvoie un élément déjà accepté avec le même id et le même contenu, LogBrew ne le stocke pas une deuxième fois. La réponse compte cet élément dans already_accepted.

Exemple de requête

Enregistrez le JSON ci-dessous sous le nom telemetry-envelope.json. Remplacez l’ID de projet d’exemple par l’ID exact du projet de votre clé d’ingestion. Réglez les horodatages sur l’heure UTC actuelle du signal de test. Utilisez vos propres valeurs de service et de version.

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

Chargez la valeur d’ingestion du projet dans LOGBREW_INGEST_BEARER depuis votre configuration protégée. Ne l’affichez pas et n’utilisez pas d’identifiant de compte. La commande suivante envoie le fichier une fois. Elle nécessite curl 7.76.0 ou une version plus récente :

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

Lisez le statut HTTP et le corps de la réponse. --fail-with-body conserve le corps d’une erreur et renvoie un code de sortie non nul pour les erreurs HTTP. Une panne réseau ou un délai dépassé ne vous indique pas si LogBrew a accepté la requête. Renvoyez le même fichier uniquement si ses éléments ont des valeurs id. Sans valeurs id, un second envoi peut stocker les éléments deux fois.

Réponse

Une requête réussie renvoie 200 avec le nombre de nouveaux éléments par flux. already_accepted compte les éléments qu’une requête précédente a déjà envoyés.

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

Erreurs

Une clé d’ingestion invalide ou révoquée renvoie 401. Une clé d’un autre projet renvoie aussi 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"
  }
}

Utilisez une clé d’ingestion limitée au projet. Ne la remplacez pas par un identifiant de compte. Une clé d’artefact ne peut pas envoyer de télémétrie. Une enveloppe qui enfreint une règle de champ renvoie 422 avec le code validation_failed. Le champ error nomme la règle. Le champ next indique comment corriger la requête. Par exemple, "items": [] renvoie :

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

N’envoyez pas d’enveloppe s’il n’y a aucun signal. Une enveloppe de plus de 512 éléments renvoie 422 avec l’erreur native telemetry envelope exceeds the item limit. Découpez-la en lots de 512 éléments au maximum. Gardez le projet et le contexte partagé dans chaque lot. Pour les limites d’utilisation, les limites de débit et les pannes de service, suivez le code renvoyé dans Erreurs de l’API.

Définissez la version et l’environnement dans la configuration du SDK. Créez ou poursuivez un contexte de trace pour chaque opération. Ne réutilisez pas un ID de trace pour des traitements sans rapport.

Démarrage

Concepts

Installer et envoyer

Investiguer

CLI et agents

Support

Intégration du SDK pour la télémétrie applicative

Signaux et contexte partagé

log

trace_span

issue

action

metric

Version et environnement

Valeurs de gravité

Installer avec un gestionnaire de paquets

Traçage des requêtes Node.js

ASP.NET Core

Java avec Maven ou Gradle

C++ avec CMake

Source maps JavaScript

Apple, Flask et React Native

Traçage des files de messages en JavaScript

Enveloppe native directe

Champs des éléments

Exemple de requête

Réponse

Erreurs

​Signaux et contexte partagé

log

trace_span

issue

action

metric

Version et environnement

​Valeurs de gravité

​Installer avec un gestionnaire de paquets

​Traçage des requêtes Node.js

​ASP.NET Core

​Java avec Maven ou Gradle

​C++ avec CMake

​Source maps JavaScript

​Apple, Flask et React Native

​Traçage des files de messages en JavaScript

​Enveloppe native directe

​Champs des éléments

​Exemple de requête

​Réponse

​Erreurs

Signaux et contexte partagé

Valeurs de gravité

Installer avec un gestionnaire de paquets

Traçage des requêtes Node.js

ASP.NET Core

Java avec Maven ou Gradle

C++ avec CMake

Source maps JavaScript

Apple, Flask et React Native

Traçage des files de messages en JavaScript

Enveloppe native directe

Champs des éléments

Exemple de requête

Réponse

Erreurs