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.
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 itLe 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 Logback | Lyrelog |
|---|---|
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, ERROR | trace, 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'exception | attrs.error_type, attrs.error_message et payload.exception (frames, causes) |
| L'heure de l'enregistrement | L'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.
Consentement
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 stopVous 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.tmpdirpour 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 lestartsuivant. 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 environmentPour 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
| Option | Par défaut | Signification |
|---|---|---|
apiKey | obligatoire | La clé serveur du projet (lyr_srv_...), ou une clé d'ingestion. null ou vide : rien ne démarre |
endpoint | https://ingest.lyrelog.com | L'URL de base ; un chemin /v1/... collé est retiré. https uniquement, http seulement pour localhost |
environment | $LYRELOG_ENVIRONMENT, sinon production | N'importe quel nom valide |
platform | jvm | api, worker... |
release | l'Implementation-Version du jar lancé | Envoyé comme resource.app_version |
appId | l'Implementation-Title ou le nom de fichier du jar lancé, sinon la classe principale | Envoyé comme resource.app_id : le nom du service |
minimumLevel | Level.DEBUG | Les événements en dessous sont supprimés avant la mise en file d'attente |
flushIntervalMillis | 5 s | La fréquence d'envoi du thread d'arrière-plan |
maxBatchBytes | 512 KiB | Un lot est clos à la première limite atteinte (gardée sous 4 MiB) |
maxBatchEvents | 500 | 2 000 au plus |
maxQueue | 10 000 | Les événements en attente d'écriture ; au-delà, le plus ancien est supprimé et compté |
maxDiskBytes | 20 MB | Plafond du répertoire de file d'attente, les plus anciens partant en premier |
maxEventAgeMillis | 7 jours | Les événements en file plus anciens sont supprimés |
redactedKeys | null : DEFAULT_REDACTED_KEYS | Les noms de clés à masquer ; votre liste remplace celle par défaut, une liste vide désactive le masquage |
storageDirectory | un répertoire temporaire par processus | L'emplacement de la file ; voir Où attendent les événements |
captureUncaught | false | Enregistrer les exceptions non interceptées |
shutdownHook | true | Fermer quand la JVM s'arrête |
closeTimeoutMillis | 5 s | Le temps pendant lequel la fermeture attend le dernier envoi |
diagnostics | sortie d'erreur standard | Reçoit les messages propres au SDK (un Consumer<String>). Ne le faites pas pointer vers un logger qui alimente Lyrelog |
Envoi et limites
| Jamais bloquant | L'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. |
| Lots | Jusqu'à 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 tentatives | Dé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 mensuel | Quand 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 visibles | Les événements perdus à cause des plafonds donnent un avertissement lyrelog_events_dropped (domaine lyrelog) avec leur nombre. |
| Problèmes du SDK lui-même | Un 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: . |
| Contexte | os_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. |
| Secrets | Les 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. |
| Limites | Les 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",
))