> ## 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. # Intégration du SDK pour la télémétrie applicative > Choisissez un SDK LogBrew pour votre runtime et configurez sa clé d’ingestion. Envoyez la télémétrie de l’application et trouvez le signal de test. 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 : 1. Installez le paquet SDK de votre runtime. 2. Gardez la clé d’ingestion du projet hors du dépôt de code. 3. Définissez des valeurs stables pour le service, l’environnement et la version. 4. Envoyez un signal de test sans risque depuis l’application. 5. 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](/fr/guides/safe-capture). Pour alimenter la vue Analyses, suivez [Capture d’événements produit](/fr/guides/product-events). ## 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. Un message structuré avec une gravité, une source, une heure et un contexte sans risque. Une opération chronométrée, reliée à sa trace par les ID de trace et de span. Un échec capturé, sa gravité et les détails de l’erreur envoyés par l’application. Une action dans votre application, avec en option un sujet, une session et des propriétés sans risque. Une mesure numérique avec un nom, un type, une valeur, une unité et une temporalité. 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](/fr/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 | 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.10` 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 : ```bash theme={null} logbrew setup --json ``` Le plan installe l’intégration d’hôte publiée : ```bash theme={null} 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 : ```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(); ``` Sans `LOGBREW_SERVER_API_KEY`, les deux appels d’enregistrement ne font rien et restent sans risque. Le [paquet NuGet ASP.NET Core](https://www.nuget.org/packages/LogBrew.AspNetCore/0.1.2) 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 : ```bash theme={null} logbrew setup --json ``` Pour Maven, ajoutez le paquet publié : ```xml theme={null} co.logbrew logbrew-sdk 0.1.10 ``` Pour le DSL Kotlin de Gradle, ajoutez le même artefact Maven Central : ```kotlin theme={null} implementation("co.logbrew:logbrew-sdk:0.1.10") ``` 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](https://central.sonatype.com/artifact/co.logbrew/logbrew-sdk/0.1.10) 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 : ```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) ``` 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 : ```cmake theme={null} 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 : ```bash theme={null} 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](https://github.com/LogBrewCo/sdk/releases/tag/cpp/logbrew-cpp/v0.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](/fr/guides/source-maps). 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](/fr/guides/apple-crashes-and-hangs). Pour Flask, suivez le guide [Flask](/fr/guides/flask). Pour React Native et Expo, suivez [React Native](/fr/guides/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é](/fr/concepts/telemetry#severity-values). | 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. ```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 } } } ] } ``` 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 : ```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' ``` 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. ```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" } } ``` ### Erreurs Une clé d’ingestion invalide ou révoquée renvoie `401`. Une clé d’un autre projet renvoie aussi `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" } } ``` 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 : ```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" } } ``` 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](/fr/reference/api-errors). 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.