Early AccessNur auf Einladung, und die SDKs sind noch nicht veröffentlicht.Einladung anfragen
Zum Inhalt springen
Docs

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.

Java- und Kotlin-Server, mit einem Logback-Appender

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 it

Der 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 LogbackLyrelog
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, ERRORtrace, debug, info, warning, error
Die formatierte Nachrichtmessage; 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 Exceptionattrs.error_type, attrs.error_message und payload.exception (Frames, Ursachen)
Die Zeit des RecordsDie 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 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 stop

Du 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.tmpdir für diesen Prozess, das bei close gelöscht wird. Was bis dahin nicht gesendet wurde, geht verloren, wie bei einer Warteschlange im Arbeitsspeicher.
  • Mit storageDirectory ein eigenes Verzeichnis: Was nicht gesendet wurde (der Server war nicht erreichbar oder hat um Aufschub gebeten), bleibt dort und geht nach dem nächsten start raus. 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 environment

Zur 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

OptionStandardBedeutung
apiKeyerforderlichDer Server-Schlüssel des Projekts (lyr_srv_...) oder ein Ingest-Schlüssel. null oder leer: Es startet nichts
endpointhttps://ingest.lyrelog.comDie Basis-URL; ein eingefügter Pfad /v1/... wird entfernt. Nur https, http nur für localhost
environment$LYRELOG_ENVIRONMENT, sonst productionJeder gültige Name
platformjvmapi, worker...
releasedie Implementation-Version des gestarteten JarsWird als resource.app_version gesendet
appIdder Implementation-Title oder Dateiname des gestarteten Jars, sonst die HauptklasseWird als resource.app_id gesendet: der Name des Service
minimumLevelLevel.DEBUGEvents darunter werden verworfen, bevor sie in die Warteschlange kommen
flushIntervalMillis5 sWie oft der Hintergrund-Thread sendet
maxBatchBytes512 KiBEin Batch wird geschlossen, sobald die erste der beiden Grenzen erreicht ist (höchstens 4 MiB)
maxBatchEvents500Höchstens 2.000
maxQueue10.000Events, die darauf warten, geschrieben zu werden; darüber hinaus wird das älteste verworfen und gezählt
maxDiskBytes20 MBGrenze für das Queue-Verzeichnis, die ältesten zuerst
maxEventAgeMillis7 TageÄltere Events in der Warteschlange werden verworfen
redactedKeysnull: DEFAULT_REDACTED_KEYSZu schwärzende Schlüsselnamen; deine Liste ersetzt die Standardliste, eine leere Liste schaltet es ab
storageDirectoryein temporäres Verzeichnis pro ProzessWo die Warteschlange liegt; siehe Wo Events warten
captureUncaughtfalseZeichnet nicht abgefangene Exceptions auf
shutdownHooktrueSchließt, wenn die JVM herunterfährt
closeTimeoutMillis5 sWie lange das Schließen auf das letzte Senden wartet
diagnosticsStandardfehlerausgabeEmpfängt die eigenen Meldungen des SDK (ein Consumer<String>). Richte sie nicht auf einen Logger, der in Lyrelog schreibt

Zustellung und Limits

Blockiert nieLoggen 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.
BatchesBis 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.
Wiederholungen1 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.
MonatskontingentWenn 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 sichtbarEvents, die durch die Grenzen verloren gehen, werden zu einer Warnung lyrelog_events_dropped (Bereich lyrelog) mit der Anzahl.
Eigene ProblemeEin 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: .
Kontextos_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.
SecretsWerte 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.
LimitsLange 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üsselWird 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",
))