Accès anticipéSur invitation, et les SDK ne sont pas encore publiés.Demander une invitation
Aller au contenu
Docs

Java et Kotlin (JVM)

Des logs structurés depuis vos services Java et Kotlin (Spring, Ktor, JVM seule), avec un appender Logback. Aucune dépendance au-delà de la bibliothèque standard de Kotlin.

Serveurs Java et Kotlin, avec un appender Logback

Le SDK JVM nécessite Java 11 ou plus récent. Il est écrit en Kotlin et chacune de ses fonctions peut être appelée depuis Java. Il utilise le même moteur que le SDK Android (lyrelog-core) et n'a aucune autre dépendance que la bibliothèque standard de Kotlin. Les enregistrements SLF4J et Logback peuvent y arriver par un appender distinct et facultatif.

Préversion interne : ce package n'est pas encore publié. D'ici là, Gradle et Maven ne peuvent pas récupérer com.lyrelog:lyrelog-jvm : il n'est pas sur Maven Central, et le dépôt est privé et n'a encore aucune release.

Installation

Depuis Maven Central. Avec Gradle, dans build.gradle.kts :

dependencies {
    implementation("com.lyrelog:lyrelog-jvm:0.1.0")
    // Optional: SLF4J and Logback records (Spring Boot's default logging) to Lyrelog.
    implementation("com.lyrelog:lyrelog-jvm-logback:0.1.0")
}

Avec Maven, dans pom.xml :

<dependencies>
  <dependency>
    <groupId>com.lyrelog</groupId>
    <artifactId>lyrelog-jvm</artifactId>
    <version>0.1.0</version>
  </dependency>
  <!-- Optional: SLF4J and Logback records to Lyrelog. -->
  <dependency>
    <groupId>com.lyrelog</groupId>
    <artifactId>lyrelog-jvm-logback</artifactId>
    <version>0.1.0</version>
  </dependency>
</dependencies>

L'appender n'apporte pas Logback : il utilise celui que votre application a déjà (1.3 ou plus récent).

Démarrage

Une seule fois, le plus tôt possible : dans main, avant le démarrage du framework.

import com.lyrelog.Configuration
import com.lyrelog.Lyrelog

fun main(args: Array<String>) {
    Lyrelog.start(Configuration(
        apiKey = System.getenv("LYRELOG_KEY"), // a server key, lyr_srv_...
        platform = "api",
    ))
    runApplication<OrdersApplication>(*args) // or embeddedServer(Netty, ...) in Ktor
}

En Java :

import com.lyrelog.Configuration;
import com.lyrelog.Lyrelog;

public static void main(String[] args) {
    Lyrelog.start(Configuration.builder(System.getenv("LYRELOG_KEY")).platform("api").build());
    SpringApplication.run(OrdersApplication.class, args);
}

Utilisez une clé serveur, lyr_srv_..., créée sur la page API keys du projet (Send events from a server). C'est un secret : gardez-la dans l'environnement de votre serveur, jamais dans une app ou une page web. Ses événements sont vérifiés, et le quota journalier par adresse d'expéditeur ne s'applique pas. Une clé d'ingestion, lyr_ing_..., fonctionne aussi, mais ses événements ne sont pas vérifiés.

start renvoie true quand il a démarré Lyrelog. Un second appel pendant que Lyrelog tourne est ignoré et renvoie false. Une clé null ou vide ne démarre rien et renvoie false, et tous les autres appels ne font alors rien : une variable d'environnement absente en développement ou dans les tests n'arrête donc pas le service. Les événements enregistrés avant start sont ignorés. start ne lève jamais d'exception.

Les événements partent vers https://ingest.lyrelog.com. Ne passez endpoint que pour les envoyer ailleurs. C'est l'URL de base (un chemin .../v1/events:batch collé par erreur est retiré), et elle doit être en https://, ou en http:// pour localhost, 127.0.0.1 ou ::1. Tout autre endpoint est refusé : rien n'est envoyé, et le SDK le signale une fois dans ses diagnostics.

Enregistrer des événements

Une fonction par niveau : trace, debug, info, notice, warning, error, critical, ou Lyrelog.log(level, message, ...).

Lyrelog.info("checkout_done", attrs = mapOf("plan" to "pro", "latency_ms" to 412))
Lyrelog.error("payment_failed",
    category = "billing",
    attrs = mapOf("code" to "card_declined"),
    payload = mapOf("response" to body),
)

Les attributs peuvent être des chaînes, des nombres, des booléens, null, des listes (envoyées sous forme de chaînes) et des maps imbriquées jusqu'à 4 niveaux. Le payload peut être n'importe quelle map, liste ou valeur. Un appel de log ne bloque jamais et ne lève jamais d'exception : il copie l'événement et rend la main. Après close, les appels de log ne font plus rien.

Un logger par domaine

val billing = Lyrelog.logger("billing")
billing.warning("invoice_retry", mapOf("attempt" to 2))

Un logger ne coûte presque rien à créer et à conserver (un champ, un companion object). Il écrit dans l'instance de Lyrelog active au moment de l'appel : vous pouvez donc le créer avant start.

Utilisateurs

Un serveur traite de nombreuses personnes à la fois. Définissez l'utilisateur sur l'événement, ou pour tout le travail d'une requête :

Lyrelog.info("checkout_done", user = customerId)        // for this event only

Lyrelog.userScope(customerId).use {                     // for everything logged on this thread
    handle(request)                                     // until the scope is closed
}

Lyrelog.setUser("u_123")                                // every following event, every thread
Lyrelog.setUser(null)                                   // clear it

Le user propre à l'événement l'emporte sur celui du scope, et celui du scope sur setUser. Un scope est local au thread : en Java, ouvrez-le avec un try-with-resources dans un filtre de servlet (comme dans le filtre de requêtes ci-dessous). Les coroutines et le code réactif (Ktor, WebFlux) passent d'un thread à l'autre : passez-y plutôt user sur chaque événement. Utilisez vos propres identifiants, pas des adresses e-mail.

L'appender Logback

Avec lyrelog-jvm-logback, chaque enregistrement que vos loggers écrivent via SLF4J ou Logback peut aussi partir vers Lyrelog. Ajoutez l'appender dans logback.xml (avec Spring Boot, logback-spring.xml) :

<configuration>
  <appender name="LYRELOG" class="com.lyrelog.logback.LyrelogAppender" />

  <root level="INFO">
    <appender-ref ref="LYRELOG" />
  </root>
</configuration>

L'appender transmet au Lyrelog en cours d'exécution, démarré dans le code comme ci-dessus. Vous pouvez aussi le laisser démarrer Lyrelog lui-même, pour que le service n'ait besoin d'aucun code ; il ferme alors Lyrelog quand Logback s'arrête :

<appender name="LYRELOG" class="com.lyrelog.logback.LyrelogAppender">
  <apiKey>${LYRELOG_KEY}</apiKey>
  <platform>api</platform>
  <!-- <environment>staging</environment>, <endpoint>...</endpoint> -->
</appender>

Les enregistrements écrits avant le démarrage de Lyrelog sont ignorés : démarrez-le donc avant que votre framework n'écrive ce que vous voulez conserver. Pour continuer aussi à afficher les logs dans la console, gardez votre appender console à côté de celui-ci.

private static final org.slf4j.Logger log = LoggerFactory.getLogger(Invoices.class);

MDC.put("user_id", customerId);                 // the event's user
log.info("Order {} shipped", orderId);
log.atWarn().addKeyValue("attempt", 2).log("invoice_retry");
log.error("charge_failed", e);
SLF4J et LogbackLyrelog
Nom du logger (com.example.billing.Invoices)category, sauf si l'appender a une <category> ou l'enregistrement une clé category
TRACE, DEBUG, INFO, WARN, ERRORtrace, debug, info, warning, error
Le message formatémessage ; avec des arguments, le modèle va dans attrs.msg_template pour regrouper
Entrées du MDC, et paires clé-valeur SLF4J 2 (addKeyValue)attrs, sauf user_id (l'utilisateur de l'événement) et category. <includeMdc>false</includeMdc> laisse le MDC de côté
L'exceptionattrs.error_type, attrs.error_message et payload.exception (frames, causes)
L'heure de l'enregistrementL'heure de l'événement

Le niveau minimum propre à Lyrelog s'applique toujours : les enregistrements trace sont supprimés sauf si minimumLevel vaut Level.TRACE. L'appender ignore les enregistrements des loggers com.lyrelog et des threads propres au SDK : il ne peut donc jamais boucler. Il n'y a pas d'appender pour Log4j 2 ni pour java.util.logging. Pour les événements que vous voulez voir en graphique, préférez des appels directs avec un nom stable : un message formaté, c'est de la prose.

Un filtre de requêtes Spring

Il n'y a pas de filtre intégré. Celui-ci enregistre chaque requête en http_request_served dans le domaine http, au niveau info, warning pour un 4xx et error pour un 5xx, avec le pattern de la route plutôt que le chemin, pour que les identifiants ne fassent pas exploser la cardinalité. Il définit aussi l'utilisateur de la requête pour tout ce qui est enregistré pendant son traitement :

import com.lyrelog.Level;
import com.lyrelog.Lyrelog;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.Map;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
import org.springframework.web.servlet.HandlerMapping;

@Component
public class LyrelogRequests extends OncePerRequestFilter {
    private final com.lyrelog.Logger http = Lyrelog.logger("http");

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
            throws ServletException, IOException {
        try (Lyrelog.UserScope user = Lyrelog.userScope(currentUserId(request))) { // your own id, or null
            long start = System.nanoTime();
            int status = 500; // when the handler throws, Spring writes the error page later
            try {
                chain.doFilter(request, response);
                status = response.getStatus();
            } finally {
                Object route = request.getAttribute(HandlerMapping.BEST_MATCHING_PATTERN_ATTRIBUTE);
                Level level = status >= 500 ? Level.ERROR : status >= 400 ? Level.WARNING : Level.INFO;
                http.log(level, "http_request_served", Map.of(
                    "method", request.getMethod(),
                    "route", route != null ? route.toString() : "unmatched", // /orders/{id}, not the id
                    "status", status,
                    "duration_ms", (System.nanoTime() - start) / 1_000_000));
            }
        }
    }
}

Spring enregistre l'exception levée par un handler sur ses propres loggers, avec la stack : avec l'appender Logback, elle arrive donc déjà avec error_type et error_message. La capturer aussi dans le filtre l'enregistrerait deux fois.

Erreurs

try {
    charge(order)
} catch (e: PaymentException) {
    Lyrelog.captureError(e, category = "billing", attrs = mapOf("order_id" to order.id))
}

L'événement est exception, de niveau error, avec error_type (le nom de la classe) et error_message dans les attributs et, dans le payload, la description, jusqu'à 60 frames, les causes (jusqu'à 8, de 20 frames chacune) et les exceptions supprimées (suppressed). Vos attributs sont ajoutés ; ces deux-là l'emportent. level change le niveau et user définit l'utilisateur de l'événement. logger.captureError(e) utilise la catégorie du logger.

Exceptions non interceptées

Désactivé par défaut. Avec captureUncaught = true, une exception qu'aucun code n'a interceptée, sur n'importe quel thread, est enregistrée comme exception avec handled: false, mechanism: uncaught_exception et le nom du thread dans thread. Ensuite, le handler qui était là avant s'exécute (ou l'affichage habituel de la JVM). Quand ce thread était le dernier, le shutdown hook envoie l'événement avant que la JVM ne s'arrête.

Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY"), captureUncaught = true))

Les frameworks interceptent eux-mêmes les exceptions d'une requête et les enregistrent : celles-ci arrivent par l'appender Logback. Une exception dans une tâche confiée à un ExecutorService avec submit va dans son Future, pas dans ce handler.

Environnements et plateforme

environment vient de la variable d'environnement LYRELOG_ENVIRONMENT, sinon production. platform vaut jvm. Vous pouvez définir l'un ou l'autre dans la configuration :

Lyrelog.start(Configuration(apiKey = key, environment = "staging", platform = "worker"))

N'importe quel nom convient : lettres minuscules, chiffres, - et _, jusqu'à 32 caractères. Tout autre texte dans la configuration est nettoyé pour vous (Staging EU devient staging-eu) ; un $LYRELOG_ENVIRONMENT invalide est signalé une fois et remplacé par production : une faute de frappe dans un déploiement n'arrête donc jamais un service.

release (resource.app_version) vaut par défaut l'Implementation-Version du jar avec lequel la JVM a été lancée (java -jar orders.jar), et appId (resource.app_id) son Implementation-Title, sinon le nom de fichier du jar, sinon la classe principale. Définissez-les quand ce n'est pas ce que vous voulez.

Le consentement concerne les apps qui tournent sur l'appareil de quelqu'un. Un SDK serveur envoie ce qu'on lui donne ; il n'y a pas d'option de consentement.

Vider la file et arrêter

Lyrelog.flush()               // send what's queued now, waiting up to 5 s; true when it finished
Lyrelog.flushInBackground()   // the same, without waiting
Lyrelog.close()               // send what's left (up to closeTimeoutMillis), then stop

Vous en aurez rarement besoin : le SDK envoie toutes les 5 s, et un shutdown hook de la JVM le ferme quand la JVM se termine normalement (fin de main, System.exit, SIGTERM et Ctrl-C). kill -9 ne déclenche pas le hook. Désactivez le hook avec shutdownHook = false et appelez close vous-même.

flush respecte un Retry-After demandé par le serveur : il n'envoie pas plus tôt. Après close, start peut être rappelé.

Dans une fonction serverless (AWS Lambda), appelez Lyrelog.flush() avant que le handler ne réponde : le runtime peut geler le processus avant l'envoi suivant.

Où attendent les événements

Les événements sont écrits dans un répertoire de file d'attente, un fichier par lot, et un lot n'en sort qu'une fois que le serveur l'a accepté.

  • Par défaut, un nouveau répertoire sous java.io.tmpdir pour ce processus, supprimé à close. Ce qui n'a pas été envoyé d'ici là est perdu, comme avec une file en mémoire.
  • Avec storageDirectory, un répertoire à vous : ce qui n'a pas été envoyé (le serveur était injoignable, ou a demandé d'attendre) y reste et part après le start suivant. Un seul processus à la fois : le répertoire est verrouillé, et un second processus qui le trouve verrouillé met ses événements en file dans un répertoire temporaire à la place, et le signale une fois.

Les deux sont plafonnés à 20 MB et 7 jours, les plus anciens partant en premier (maxDiskBytes, maxEventAgeMillis).

En développement et dans les tests

Ne fournissez pas de clé : Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY"))) ne démarre rien quand la variable n'est pas définie, et chaque appel ne fait rien. Les tests et un portable sans clé exécutent donc le même code. L'appender Logback ne fait rien non plus tant que Lyrelog ne tourne pas.

Pour voir ce qu'un test enregistre, faites pointer endpoint vers un serveur HTTP local (le http:// simple est autorisé pour les adresses de loopback) et lisez les lots qu'il reçoit : du NDJSON compressé en gzip, un événement par ligne, comme sur la page HTTP API.

Depuis Java

Depuis Java, toutes les fonctions de Lyrelog sont statiques, avec des surcharges pour les arguments facultatifs, et Configuration a un builder :

Lyrelog.start(Configuration.builder(System.getenv("LYRELOG_KEY"))
    .platform("api")
    .environment("staging")
    .captureUncaught(true)
    .build());

Lyrelog.info("checkout_done");
Lyrelog.info("checkout_done", "billing", Map.of("plan", "pro"));
Lyrelog.captureError(e, "billing");

try (Lyrelog.UserScope scope = Lyrelog.userScope(customerId)) {
    Lyrelog.logger("billing").warning("invoice_retry", Map.of("attempt", 2));
}

new Configuration(key) fonctionne aussi, et les fonctions d'un logger ont des surcharges : les derniers arguments peuvent donc être omis.

Événements vérifiés

Un événement vérifié est un événement qui ne peut pas avoir été envoyé par quelqu'un qui aurait copié la clé d'ingestion publique depuis une app ou une page web. Ce que cela prouve, et ce que cela ne prouve pas, est expliqué dans Événements vérifiés.

Envoyez avec une clé serveur, lyr_srv_.... Chaque événement qu'elle envoie est vérifié (verified_by vaut server) et ne compte pas dans le quota journalier d'une adresse. Un propriétaire la crée sur la page API keys du projet, Send events from a server, après s'être connecté récemment (dans les 10 dernières minutes), et elle n'est affichée qu'une fois. C'est un secret : gardez-la hors du dépôt et lisez-la depuis l'environnement ou le gestionnaire de secrets du serveur.

Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY"))) // lyr_srv_..., set in the server's environment

Pour contrôler, ouvrez l'explorer : dans Filter, choisissez Verified by et Server key (les autres valeurs sont App Attest et Not verified). Un événement ouvert l'indique sous Context, dans sa ligne Sender : Verified, server key, ou Not verified, public key.

Les événements envoyés avec une clé d'ingestion, lyr_ing_..., ou une clé d'accès complet, lyr_adm_..., arrivent non vérifiés : n'importe qui détenant une clé publique aurait pu envoyer les mêmes, et ils comptent dans le quota journalier. Un événement vérifié prouve qui l'a envoyé, pas que ce qu'il dit est vrai.

Voir Événements vérifiés pour savoir qui vérifie quoi et comment fonctionne le quota journalier.

Configuration

OptionPar défautSignification
apiKeyobligatoireLa clé serveur du projet (lyr_srv_...), ou une clé d'ingestion. null ou vide : rien ne démarre
endpointhttps://ingest.lyrelog.comL'URL de base ; un chemin /v1/... collé est retiré. https uniquement, http seulement pour localhost
environment$LYRELOG_ENVIRONMENT, sinon productionN'importe quel nom valide
platformjvmapi, worker...
releasel'Implementation-Version du jar lancéEnvoyé comme resource.app_version
appIdl'Implementation-Title ou le nom de fichier du jar lancé, sinon la classe principaleEnvoyé comme resource.app_id : le nom du service
minimumLevelLevel.DEBUGLes événements en dessous sont supprimés avant la mise en file d'attente
flushIntervalMillis5 sLa fréquence d'envoi du thread d'arrière-plan
maxBatchBytes512 KiBUn lot est clos à la première limite atteinte (gardée sous 4 MiB)
maxBatchEvents5002 000 au plus
maxQueue10 000Les événements en attente d'écriture ; au-delà, le plus ancien est supprimé et compté
maxDiskBytes20 MBPlafond du répertoire de file d'attente, les plus anciens partant en premier
maxEventAgeMillis7 joursLes événements en file plus anciens sont supprimés
redactedKeysnull : DEFAULT_REDACTED_KEYSLes noms de clés à masquer ; votre liste remplace celle par défaut, une liste vide désactive le masquage
storageDirectoryun répertoire temporaire par processusL'emplacement de la file ; voir Où attendent les événements
captureUncaughtfalseEnregistrer les exceptions non interceptées
shutdownHooktrueFermer quand la JVM s'arrête
closeTimeoutMillis5 sLe temps pendant lequel la fermeture attend le dernier envoi
diagnosticssortie d'erreur standardReçoit les messages propres au SDK (un Consumer<String>). Ne le faites pas pointer vers un logger qui alimente Lyrelog

Envoi et limites

Jamais bloquantL'appel de log copie l'événement et rend la main ; un unique writer en arrière-plan le place dans le répertoire de file d'attente et n'attend jamais le réseau. Un unique thread d'arrière-plan envoie. Utilisable en parallèle depuis plusieurs threads.
LotsJusqu'à 500 événements ou 512 KiB par requête, compressés en gzip, à chaque flushIntervalMillis. Un événement de plus de 1 MiB une fois encodé est supprimé et compté.
Nouvelles tentativesDélai de 1 s, doublé à chaque tentative jusqu'à 5 min, avec full jitter, en respectant Retry-After ; les mêmes octets sont renvoyés. Tout autre code 4xx supprime le lot, un 3xx (une redirection, jamais suivie) le supprime, et une clé refusée (401, 403) arrête l'envoi jusqu'au redémarrage du processus et conserve les événements. Un lot qui échoue sans cesse alors que d'autres passent est renvoyé en fin de file, puis supprimé.
Quota mensuelQuand une organisation Free a utilisé les événements de son mois, le serveur répond 429. Les événements restent dans la file et partent dès que le serveur les accepte de nouveau, dans les limites de 20 MB et 7 jours. Le SDK écrit un seul avertissement dans ses diagnostics, puis un autre seulement si un lot a été accepté entre-temps.
Pertes visiblesLes événements perdus à cause des plafonds donnent un avertissement lyrelog_events_dropped (domaine lyrelog) avec leur nombre.
Problèmes du SDK lui-mêmeUn mauvais endpoint, un 404, une clé refusée, des lignes rejetées ou un endpoint qui ne répond pas sont signalés une fois par processus dans diagnostics (la sortie d'erreur standard par défaut), chaque ligne commençant par lyrelog: .
Contexteos_name et os_version (les os.name et os.version de la JVM), l'identifiant d'app, la version, l'environnement et la plateforme, un identifiant d'installation par processus et un identifiant de session par processus.
SecretsLes valeurs sous des clés dont le nom est ou se termine par authorization, cookie, password, token, secret, apikey et le reste de la liste commune deviennent "[redacted]", à toute profondeur, avant toute troncature.
LimitesLes chaînes longues sont coupées sur une limite de caractère, les attributs en trop comptés dans lyrelog_dropped_attrs, les payloads de plus de 64 KiB résumés en {"lyrelog_truncated": true, "bytes": N, "preview": "..."}.
La cléAfficher une Configuration la masque.

Modifiez la liste de masquage avec redactedKeys : votre liste remplace celle par défaut, et une liste vide désactive le masquage. Pour la compléter :

Lyrelog.start(Configuration(
    apiKey = System.getenv("LYRELOG_KEY"),
    redactedKeys = Configuration.DEFAULT_REDACTED_KEYS + "card_number",
))