Java und Kotlin (JVM)
Strukturierte Logs aus deinen Java- und Kotlin-Services (Spring, Ktor, reine JVM), mit einem Logback-Appender. Keine Abhängigkeiten außer der Kotlin-Standardbibliothek.
Das JVM-SDK braucht Java 11 oder neuer. Es ist in Kotlin geschrieben, und jede Funktion lässt sich
aus Java aufrufen. Es verwendet dieselbe Engine wie das Android-SDK
(lyrelog-core) und hat außer der Kotlin-Standardbibliothek keine weitere Abhängigkeit. SLF4J-
und Logback-Records können über einen separaten, optionalen Appender einfließen.
Interne Vorschau: Dieses Paket ist noch nicht veröffentlicht. Bis dahin können Gradle und Maven
com.lyrelog:lyrelog-jvm nicht laden: Es liegt nicht auf Maven Central, und das Repository ist
privat und hat noch kein Release.
Installation
Von Maven Central. Mit Gradle, in 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")
}Mit Maven, in 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>Der Appender bringt kein eigenes Logback mit: Er verwendet das, das deine Anwendung bereits hat (1.3 oder neuer).
Starten
Einmal, so früh wie möglich: in main, bevor das Framework startet.
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
}In 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);
}Verwende einen Server-Schlüssel, lyr_srv_..., von der Seite API keys des Projekts (Send
events from a server). Er ist geheim: Bewahre ihn in der Umgebung deines Servers auf,
nie in einer App oder einer Webseite. Seine Events sind verifiziert,
und das Tageslimit für die Adresse eines einzelnen Absenders gilt für sie nicht. Ein Ingest-Schlüssel,
lyr_ing_..., funktioniert auch, aber seine Events sind nicht verifiziert.
start gibt true zurück, wenn es Lyrelog gestartet hat. Ein zweiter Aufruf, während es läuft,
wird ignoriert und gibt false zurück. Ein null- oder leerer Schlüssel startet nichts und gibt
false zurück, und jeder andere Aufruf tut danach nichts, damit eine fehlende Umgebungsvariable in
Entwicklung oder Tests den Service nicht stoppt. Events, die vor start geloggt werden, werden
ignoriert. start wirft nie.
Events gehen an https://ingest.lyrelog.com. Gib endpoint nur an, wenn du sie woandershin
schicken willst. Das ist die Basis-URL (ein eingefügter Pfad .../v1/events:batch wird
entfernt) und muss mit https:// beginnen, oder mit http:// für localhost, 127.0.0.1 oder
::1. Jeder andere Endpoint wird abgelehnt: Es wird nichts gesendet, und das SDK meldet das
einmal über seine Diagnose.
Events loggen
Eine Funktion pro Level: trace, debug, info, notice, warning, error, critical oder
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),
)Attribute können Strings, Zahlen, Booleans, null, Listen (als Strings gesendet) und
verschachtelte Maps bis zu 4 Ebenen sein. Der Payload ist eine beliebige Map, Liste oder ein
beliebiger Wert. Ein Log-Aufruf blockiert nie und wirft nie: Er kopiert das Event und kehrt
zurück. Nach close tun Log-Aufrufe nichts mehr.
Logger für jeden Bereich
val billing = Lyrelog.logger("billing")
billing.warning("invoice_retry", mapOf("attempt" to 2))Ein Logger ist günstig zu erstellen und zu behalten (als Feld, in einem Companion Object). Er loggt
in das, was zum Zeitpunkt des Aufrufs läuft, und kann deshalb schon vor start erstellt werden.
Nutzer
Ein Server bedient viele Personen gleichzeitig. Setz den Nutzer pro Event oder für die Arbeit eines einzelnen Requests:
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 itDer user des Events selbst hat Vorrang vor dem des Scopes, und dieser vor setUser.
Ein Scope ist thread-lokal: In Java öffnest du ihn mit try-with-resources in einem Servlet-Filter
(wie im Request-Filter weiter unten). Coroutines und reaktiver Code
(Ktor, WebFlux) springen zwischen Threads, übergib dort also user bei jedem Event. Verwende
deine eigenen IDs, keine E-Mail-Adressen.
Der Logback-Appender
Mit lyrelog-jvm-logback kann jeder Record, den deine Logger über SLF4J oder Logback schreiben,
auch an Lyrelog gehen. Füg den Appender in logback.xml hinzu (in Spring Boot logback-spring.xml):
<configuration>
<appender name="LYRELOG" class="com.lyrelog.logback.LyrelogAppender" />
<root level="INFO">
<appender-ref ref="LYRELOG" />
</root>
</configuration>Der Appender leitet an das laufende Lyrelog weiter, das wie oben im Code gestartet wurde. Oder
du lässt ihn Lyrelog selbst starten, dann braucht der Service überhaupt keinen Code; er schließt
Lyrelog dann auch, wenn Logback stoppt:
<appender name="LYRELOG" class="com.lyrelog.logback.LyrelogAppender">
<apiKey>${LYRELOG_KEY}</apiKey>
<platform>api</platform>
<!-- <environment>staging</environment>, <endpoint>...</endpoint> -->
</appender>Records, die vor dem Start von Lyrelog geloggt werden, werden ignoriert, starte es also, bevor dein Framework loggt, was du behalten willst. Wenn du weiterhin auch auf die Konsole schreiben willst, behalte deinen Konsolen-Appender neben diesem.
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 und Logback | Lyrelog |
|---|---|
Name des Loggers (com.example.billing.Invoices) | category, außer der Appender hat eine <category> oder der Record einen Schlüssel category |
TRACE, DEBUG, INFO, WARN, ERROR | trace, debug, info, warning, error |
| Die formatierte Nachricht | message; mit Argumenten geht das Pattern zum Gruppieren nach attrs.msg_template |
MDC-Einträge und Key-Value-Paare von SLF4J 2 (addKeyValue) | attrs, außer user_id (der Nutzer des Events) und category. <includeMdc>false</includeMdc> lässt das MDC weg |
| Die Exception | attrs.error_type, attrs.error_message und payload.exception (Frames, Ursachen) |
| Die Zeit des Records | Die Zeit des Events |
Das eigene Mindestlevel von Lyrelog gilt weiterhin: trace-Records werden verworfen, außer
minimumLevel ist Level.TRACE. Der Appender ignoriert Records von com.lyrelog-Loggern und aus
den eigenen Threads des SDK, er kann also nie in eine Schleife geraten. Für Log4j 2 oder
java.util.logging gibt es keinen Appender. Für Events, die du in Diagrammen auswerten willst,
sind direkte Aufrufe mit einem stabilen Namen besser: Eine formatierte Nachricht ist Fließtext.
Ein Spring-Request-Filter
Es gibt keinen eingebauten Filter. Dieser hier zeichnet jeden Request als http_request_served im
Bereich http auf, mit info, bei einem 4xx mit warning und bei einem 5xx mit error, mit dem Routen-Pattern
statt des Pfads, damit IDs die Kardinalität nicht sprengen. Außerdem setzt er den Nutzer des
Requests für alles, was während seiner Verarbeitung geloggt wird:
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 loggt eine Exception, die ein Handler wirft, auf seinen eigenen Loggern mit Stack. Mit dem
Logback-Appender kommt sie also bereits mit error_type und error_message an; würdest du sie im
Filter zusätzlich erfassen, käme sie doppelt an.
Fehler
try {
charge(order)
} catch (e: PaymentException) {
Lyrelog.captureError(e, category = "billing", attrs = mapOf("order_id" to order.id))
}Das Event ist exception, Level error, mit error_type (dem Klassennamen) und error_message
in den Attributen und, im Payload, der Beschreibung, bis zu 60 Frames, den Ursachen (bis zu 8, je
20 Frames) und den unterdrückten Exceptions. Deine Attribute kommen hinzu; diese beiden gewinnen.
level ändert das Level, und user setzt den Nutzer des Events. logger.captureError(e)
verwendet die Kategorie des Loggers.
Nicht abgefangene Exceptions
Standardmäßig aus. Mit captureUncaught = true wird eine Exception, die kein Code abgefangen hat,
auf jedem Thread als exception aufgezeichnet, mit handled: false,
mechanism: uncaught_exception und dem Namen des Threads in thread. Danach läuft der Handler,
der vorher da war (oder die übliche Ausgabe der JVM). War dieser Thread der letzte, sendet der
Shutdown-Hook das Event, bevor die JVM endet.
Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY"), captureUncaught = true))Frameworks fangen die Exceptions eines Requests selbst ab und loggen sie: Diese kommen über den
Logback-Appender an. Eine Exception in einem Task, der per submit an einen ExecutorService
übergeben wurde, landet in dessen Future, nicht bei diesem Handler.
Umgebungen und Plattform
environment kommt aus der Umgebungsvariable LYRELOG_ENVIRONMENT, sonst production.
platform ist jvm. Beides kannst du in der Konfiguration setzen:
Lyrelog.start(Configuration(apiKey = key, environment = "staging", platform = "worker"))Jeder Name funktioniert: Kleinbuchstaben, Ziffern, - und _, bis zu 32 Zeichen. Anderer Text in
der Konfiguration wird für dich bereinigt (Staging EU wird staging-eu); ein ungültiges
$LYRELOG_ENVIRONMENT wird einmal gemeldet und durch production ersetzt, damit ein Tippfehler in
einem Deployment nie einen Service stoppt.
release (resource.app_version) ist standardmäßig die Implementation-Version des Jars, mit
dem die JVM gestartet wurde (java -jar orders.jar), und appId (resource.app_id) dessen
Implementation-Title, sonst der Dateiname des Jars, sonst die Hauptklasse. Setz sie, wenn das
nicht passt.
Einwilligung
Einwilligung betrifft Apps, die auf dem Gerät einer Person laufen. Ein Server-SDK sendet, was es bekommt; eine Option für die Einwilligung gibt es nicht.
Flush und Stopp
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 stopDu brauchst sie selten: Das SDK sendet alle 5 s, und ein Shutdown-Hook der JVM schließt es, wenn
die JVM normal endet (das Ende von main, System.exit, SIGTERM und Ctrl-C). kill -9
überspringt den Hook. Mit shutdownHook = false schaltest du den Hook ab und rufst close selbst auf.
flush respektiert ein Retry-After, das der Server verlangt hat: Es sendet nicht früher. Nach
close kann start erneut aufgerufen werden.
In einer Serverless-Funktion (AWS Lambda) rufst du Lyrelog.flush() auf, bevor der Handler
zurückkehrt: Die Laufzeitumgebung kann den Prozess vor dem nächsten Senden einfrieren.
Wo Events warten
Events werden in ein Queue-Verzeichnis geschrieben, eine Datei pro Batch, und ein Batch verlässt es erst, wenn der Server ihn angenommen hat.
- Standardmäßig ein neues Verzeichnis unter
java.io.tmpdirfür diesen Prozess, das beiclosegelöscht wird. Was bis dahin nicht gesendet wurde, geht verloren, wie bei einer Warteschlange im Arbeitsspeicher. - Mit
storageDirectoryein eigenes Verzeichnis: Was nicht gesendet wurde (der Server war nicht erreichbar oder hat um Aufschub gebeten), bleibt dort und geht nach dem nächstenstartraus. Immer nur ein Prozess: Das Verzeichnis wird gesperrt, und ein zweiter Prozess, der es gesperrt vorfindet, nutzt stattdessen ein temporäres Verzeichnis als Warteschlange und meldet das einmal.
Beide Verzeichnisse sind auf 20 MB und 7 Tage begrenzt, die ältesten zuerst (maxDiskBytes, maxEventAgeMillis).
In Entwicklung und Tests
Lass den Schlüssel weg: Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY")))
startet nichts, wenn die Variable nicht gesetzt ist, und jeder Aufruf tut nichts, sodass Tests und
ein Laptop ohne Schlüssel denselben Code ausführen. Auch der Logback-Appender tut nichts, solange
Lyrelog nicht läuft.
Um zu sehen, was ein Test loggt, richte endpoint auf einen lokalen HTTP-Server (einfaches
http:// ist für Loopback-Adressen erlaubt) und lies die Batches, die er empfängt: mit gzip
komprimiertes NDJSON, ein Event pro Zeile, wie auf der Seite HTTP API beschrieben.
Aus Java
Jede Funktion auf Lyrelog ist aus Java statisch, mit Überladungen für die optionalen Argumente,
und Configuration hat einen 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) funktioniert ebenfalls, und die Funktionen eines Loggers haben
Überladungen, sodass hintere Argumente weggelassen werden können.
Verifizierte Events
Ein verifiziertes Event kann nicht von jemandem gesendet worden sein, der den öffentlichen Ingest-Schlüssel aus einer App oder einer Webseite kopiert hat. Was das beweist und was nicht, steht unter Verifizierte Events.
Sende mit einem Server-Schlüssel, lyr_srv_.... Jedes Event, das er sendet, ist verifiziert
(verified_by ist server) und zählt nicht zum
Tagesanteil einer Adresse. Ein Inhaber
erstellt ihn auf der Seite API keys des Projekts unter Send events from a server, nach einer
frischen Anmeldung (innerhalb von 10 Minuten), und er wird nur einmal angezeigt. Er ist
geheim: Check ihn nicht ins Repository ein, sondern lies ihn aus der Umgebung oder dem
Secret-Store des Servers.
Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY"))) // lyr_srv_..., set in the server's environmentZur Kontrolle öffnest du den Explorer: Wähl unter Filter erst Verified by und dann Server key (die anderen Werte sind App Attest und Not verified). Ein geöffnetes Event zeigt es unter Context in seiner Zeile Sender: Verified, server key oder Not verified, public key.
Events, die mit einem Ingest-Schlüssel, lyr_ing_..., oder einem Vollzugriffs-Schlüssel,
lyr_adm_..., gesendet werden, kommen unverifiziert an: Jeder mit einem öffentlichen Schlüssel
hätte dasselbe senden können, und sie zählen zum Tagesanteil. Ein verifiziertes Event beweist,
wer es gesendet hat, nicht, dass sein Inhalt stimmt.
Unter Verifizierte Events steht, wer was verifiziert und wie der Tagesanteil funktioniert.
Konfiguration
| Option | Standard | Bedeutung |
|---|---|---|
apiKey | erforderlich | Der Server-Schlüssel des Projekts (lyr_srv_...) oder ein Ingest-Schlüssel. null oder leer: Es startet nichts |
endpoint | https://ingest.lyrelog.com | Die Basis-URL; ein eingefügter Pfad /v1/... wird entfernt. Nur https, http nur für localhost |
environment | $LYRELOG_ENVIRONMENT, sonst production | Jeder gültige Name |
platform | jvm | api, worker... |
release | die Implementation-Version des gestarteten Jars | Wird als resource.app_version gesendet |
appId | der Implementation-Title oder Dateiname des gestarteten Jars, sonst die Hauptklasse | Wird als resource.app_id gesendet: der Name des Service |
minimumLevel | Level.DEBUG | Events darunter werden verworfen, bevor sie in die Warteschlange kommen |
flushIntervalMillis | 5 s | Wie oft der Hintergrund-Thread sendet |
maxBatchBytes | 512 KiB | Ein Batch wird geschlossen, sobald die erste der beiden Grenzen erreicht ist (höchstens 4 MiB) |
maxBatchEvents | 500 | Höchstens 2.000 |
maxQueue | 10.000 | Events, die darauf warten, geschrieben zu werden; darüber hinaus wird das älteste verworfen und gezählt |
maxDiskBytes | 20 MB | Grenze für das Queue-Verzeichnis, die ältesten zuerst |
maxEventAgeMillis | 7 Tage | Ältere Events in der Warteschlange werden verworfen |
redactedKeys | null: DEFAULT_REDACTED_KEYS | Zu schwärzende Schlüsselnamen; deine Liste ersetzt die Standardliste, eine leere Liste schaltet es ab |
storageDirectory | ein temporäres Verzeichnis pro Prozess | Wo die Warteschlange liegt; siehe Wo Events warten |
captureUncaught | false | Zeichnet nicht abgefangene Exceptions auf |
shutdownHook | true | Schließt, wenn die JVM herunterfährt |
closeTimeoutMillis | 5 s | Wie lange das Schließen auf das letzte Senden wartet |
diagnostics | Standardfehlerausgabe | Empfängt die eigenen Meldungen des SDK (ein Consumer<String>). Richte sie nicht auf einen Logger, der in Lyrelog schreibt |
Zustellung und Limits
| Blockiert nie | Loggen kopiert das Event und kehrt zurück; ein Writer im Hintergrund legt es im Queue-Verzeichnis ab und wartet nie auf das Netzwerk. Ein Hintergrund-Thread sendet. Sicher für nebenläufige Nutzung. |
| Batches | Bis zu 500 Events oder 512 KiB pro Request, mit gzip komprimiert, alle flushIntervalMillis. Ein Event, das kodiert über 1 MiB groß ist, wird verworfen und gezählt. |
| Wiederholungen | 1 s, verdoppelt bis 5 min, mit Full Jitter, unter Beachtung von Retry-After; dieselben Bytes werden erneut gesendet. Jeder andere 4xx-Status verwirft den Batch, ein 3xx-Status (eine Weiterleitung, die nie verfolgt wird) verwirft ihn, und ein abgelehnter Schlüssel (401, 403) stoppt das Senden bis zum Neustart des Prozesses und behält die Events. Ein Batch, bei dem der Server immer wieder scheitert, während andere durchgehen, wandert ans Ende und wird dann verworfen. |
| Monatskontingent | Wenn eine Free-Organisation die Events ihres Monats aufgebraucht hat, antwortet der Server mit 429. Die Events bleiben in der Warteschlange und gehen raus, sobald der Server sie wieder annimmt, innerhalb der Grenzen von 20 MB und 7 Tagen. Das SDK gibt eine Warnung über seine Diagnose aus, und erst dann wieder, wenn zwischendurch ein Batch angenommen wurde. |
| Verluste sind sichtbar | Events, die durch die Grenzen verloren gehen, werden zu einer Warnung lyrelog_events_dropped (Bereich lyrelog) mit der Anzahl. |
| Eigene Probleme | Ein falscher Endpoint, ein 404, ein abgelehnter Schlüssel, abgelehnte Zeilen oder ein Endpoint, der nicht antwortet, werden einmal pro Prozess über diagnostics gemeldet (standardmäßig auf der Standardfehlerausgabe), jede Zeile beginnt mit lyrelog: . |
| Kontext | os_name und os_version (os.name und os.version der JVM), App-ID, Release, Umgebung und Plattform, eine Installations-ID pro Prozess und eine Session-ID pro Prozess. |
| Secrets | Werte unter Schlüsseln, deren Name authorization, cookie, password, token, secret, apikey oder einer der übrigen Einträge der gemeinsamen Liste ist oder darauf endet, werden zu "[redacted]", in jeder Tiefe, bevor irgendetwas gekürzt wird. |
| Limits | Lange Strings werden an einer Zeichengrenze gekürzt, überzählige Attribute in lyrelog_dropped_attrs gezählt, Payloads über 64 KiB als {"lyrelog_truncated": true, "bytes": N, "preview": "..."} zusammengefasst. |
| Der Schlüssel | Wird verborgen, wenn du eine Configuration ausgibst. |
Die Liste fürs Schwärzen änderst du mit redactedKeys: Deine Liste ersetzt die Standardliste,
und eine leere Liste schaltet das Schwärzen ab. Zum Ergänzen:
Lyrelog.start(Configuration(
apiKey = System.getenv("LYRELOG_KEY"),
redactedKeys = Configuration.DEFAULT_REDACTED_KEYS + "card_number",
))