Acceso anticipadoSolo por invitación, y los SDK aún no están publicados.Pedir una invitación
Ir al contenido
Docs

Java y Kotlin (JVM)

Logs estructurados desde tus servicios Java y Kotlin (Spring, Ktor, JVM sin framework), con un appender de Logback. Sin más dependencias que la biblioteca estándar de Kotlin.

Servidores en Java y Kotlin, con un appender de Logback

El SDK para JVM necesita Java 11 o posterior. Está escrito en Kotlin y todas sus funciones se pueden llamar desde Java. Usa el mismo motor que el SDK de Android (lyrelog-core) y no tiene más dependencia que la biblioteca estándar de Kotlin. Los registros de SLF4J y Logback pueden entrar a través de un appender aparte y opcional.

Vista previa interna: este paquete aún no está publicado. Hasta entonces, Gradle y Maven no pueden descargar com.lyrelog:lyrelog-jvm: no está en Maven Central, y el repositorio es privado y todavía no tiene ninguna versión publicada.

Instalación

Desde Maven Central. Con Gradle, en 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")
}

Con Maven, en 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>

El appender no trae Logback: usa el que ya tiene tu aplicación (1.3 o posterior).

Primeros pasos

Una sola vez, lo antes posible: en main, antes de que arranque el 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);
}

Usa una clave de servidor, lyr_srv_..., de la página API keys del proyecto (Send events from a server). Es un secreto: guárdala en el entorno de tu servidor, nunca en una app ni en una página web. Sus eventos están verificados y no se les aplica la cuota diaria de una dirección. Una clave de ingesta, lyr_ing_..., también funciona, pero sus eventos no están verificados.

start devuelve true cuando ha iniciado Lyrelog. Una segunda llamada mientras está en marcha se ignora y devuelve false. Una clave null o en blanco no inicia nada y devuelve false, y a partir de ahí ninguna otra llamada hace nada, así que si falta una variable de entorno en desarrollo o en los tests el servicio no se detiene. Los eventos registrados antes de start se ignoran. start nunca lanza excepciones.

Los eventos van a https://ingest.lyrelog.com. Pasa endpoint solo para enviarlos a otro sitio. Es la URL base (si pegas una ruta .../v1/events:batch, se quita) y debe ser https://, o http:// para localhost, 127.0.0.1 o ::1. Cualquier otro endpoint se rechaza: no se envía nada, y el SDK lo dice una vez en sus diagnósticos.

Registrar eventos

Una función por nivel: trace, debug, info, notice, warning, error, critical, o 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),
)

Los atributos pueden ser cadenas, números, booleanos, null, listas (se envían como cadenas) y mapas anidados hasta 4 niveles. El payload puede ser cualquier mapa, lista o valor. Una llamada de registro nunca bloquea ni lanza excepciones: copia el evento y vuelve. Después de close, las llamadas de registro no hacen nada.

Loggers por área

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

Un logger es barato de crear y de guardar (en un campo, en un companion object). Registra en el Lyrelog que esté en marcha en el momento de la llamada, así que se puede crear antes de start.

Usuarios

Un servidor atiende a muchas personas a la vez. Indica el usuario en el evento, o para el trabajo de una petición:

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

El user del propio evento tiene prioridad sobre el del scope, y el del scope sobre setUser. Un scope es local al hilo: en Java, ábrelo con try-with-resources en un filtro de servlet (como en el filtro de peticiones de más abajo). Las corrutinas y el código reactivo (Ktor, WebFlux) saltan de un hilo a otro, así que ahí pasa user en cada evento. Usa tus propios ids, no direcciones de email.

El appender de Logback

Con lyrelog-jvm-logback, cada registro que tus loggers escriben con SLF4J o Logback puede ir también a Lyrelog. Añade el appender en logback.xml (en Spring Boot, logback-spring.xml):

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

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

El appender reenvía al Lyrelog en marcha, iniciado en código como arriba. O deja que sea él quien inicie Lyrelog, para que el servicio no necesite nada de código; en ese caso cierra Lyrelog cuando Logback se detiene:

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

Los registros anteriores al inicio de Lyrelog se ignoran, así que inícialo antes de que tu framework registre lo que quieres conservar. Para seguir imprimiendo también en la consola, mantén tu appender de consola junto a este.

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 y LogbackLyrelog
Nombre del logger (com.example.billing.Invoices)category, salvo que el appender tenga un <category> o el registro una clave category
TRACE, DEBUG, INFO, WARN, ERRORtrace, debug, info, warning, error
El mensaje formateadomessage; con argumentos, el patrón va a attrs.msg_template para agrupar
Entradas del MDC y pares clave-valor de SLF4J 2 (addKeyValue)attrs, salvo user_id (el usuario del evento) y category. <includeMdc>false</includeMdc> deja fuera el MDC
La excepciónattrs.error_type, attrs.error_message y payload.exception (frames, causas)
La hora del registroLa hora del evento

El nivel mínimo propio de Lyrelog se sigue aplicando: los registros trace se descartan salvo que minimumLevel sea Level.TRACE. El appender ignora los registros de los loggers com.lyrelog y de los hilos propios del SDK, así que nunca puede entrar en bucle. No hay appender para Log4j 2 ni para java.util.logging. Para los eventos que quieras graficar, mejor llamadas directas con un nombre estable: un mensaje formateado es prosa.

Un filtro de peticiones para Spring

No hay filtro incluido. Este registra cada petición como http_request_served en el área http, con nivel info, warning para un 4xx y error para un 5xx, con el patrón de la ruta en lugar de la ruta concreta, para que los ids no disparen la cardinalidad. También define el usuario de la petición para todo lo que se registre mientras se atiende:

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 registra en sus propios loggers, con el stack, la excepción que lanza un handler, así que con el appender de Logback ya llega con error_type y error_message; capturarla también en el filtro la registraría dos veces.

Errores

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

El evento es exception, con nivel error, con error_type (el nombre de la clase) y error_message en los atributos y, en el payload, la descripción, hasta 60 frames, las causas (hasta 8, de 20 frames cada una) y las excepciones suprimidas. Tus atributos se añaden; esos dos tienen prioridad. level cambia el nivel y user define el usuario del evento. logger.captureError(e) usa la categoría del logger.

Excepciones no capturadas

Desactivado por defecto. Con captureUncaught = true, una excepción que ningún código capturó, en cualquier hilo, se registra como exception con handled: false, mechanism: uncaught_exception y el nombre del hilo en thread. Después se ejecuta el handler que hubiera antes (o la salida habitual de la JVM). Cuando ese hilo era el último, el shutdown hook envía el evento antes de que la JVM termine.

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

Los frameworks capturan por su cuenta las excepciones de una petición y las registran: esas llegan a través del appender de Logback. Una excepción en una tarea entregada a un ExecutorService con submit va a su Future, no a este handler.

Entornos y plataforma

environment sale de la variable de entorno LYRELOG_ENVIRONMENT o, si no, es production. platform es jvm. Puedes definir cualquiera de los dos en la configuración:

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

Vale cualquier nombre: letras minúsculas, dígitos, - y _, hasta 32. Cualquier otro texto en la configuración se limpia por ti (Staging EU pasa a staging-eu); un $LYRELOG_ENVIRONMENT no válido se notifica una vez y se sustituye por production, para que una errata en un despliegue nunca detenga un servicio.

release (resource.app_version) toma por defecto el Implementation-Version del jar con el que se arrancó la JVM (java -jar orders.jar), y appId (resource.app_id), su Implementation-Title o, si no, el nombre de archivo del jar o, si no, la clase principal. Defínelos cuando eso no sea lo que quieres.

El consentimiento es para apps que se ejecutan en el dispositivo de alguien. Un SDK de servidor envía lo que recibe; no hay opción de consentimiento.

Vaciar la cola y detener

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

Casi nunca necesitas ninguna de las tres: el SDK envía cada 5 s, y un shutdown hook de la JVM lo cierra cuando la JVM termina con normalidad (el final de main, System.exit, SIGTERM y Ctrl-C). kill -9 se salta el hook. Desactiva el hook con shutdownHook = false y llama tú a close.

flush respeta un Retry-After que haya pedido el servidor: no envía antes. Después de close, se puede volver a llamar a start.

En una función serverless (AWS Lambda), llama a Lyrelog.flush() antes de que el handler devuelva: el runtime puede congelar el proceso antes del siguiente envío.

Dónde esperan los eventos

Los eventos se escriben en un directorio de cola, un archivo por lote, y un lote solo sale de él cuando el servidor lo ha aceptado.

  • Por defecto, un directorio nuevo dentro de java.io.tmpdir para este proceso, que se borra al llamar a close. Lo que no se haya enviado para entonces se pierde, como con una cola en memoria.
  • Con storageDirectory, un directorio propio: lo que no se haya enviado (el servidor no respondía, o pidió esperar) se queda ahí y sale después del siguiente start. Un proceso cada vez: el directorio se bloquea, y un segundo proceso que lo encuentre bloqueado usa una cola en un directorio temporal en su lugar, y lo dice una vez.

Ambos tienen un tope de 20 MB y 7 días, empezando por lo más antiguo (maxDiskBytes, maxEventAgeMillis).

En desarrollo y en tests

Omite la clave: Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY"))) no inicia nada cuando la variable no está definida, y ninguna llamada hace nada, así que los tests y una laptop sin clave ejecutan el mismo código. El appender de Logback tampoco hace nada mientras Lyrelog no está en marcha.

Para ver lo que registra un test, apunta endpoint a un servidor HTTP local (se permite http:// sin cifrar para direcciones de loopback) y lee los lotes que recibe: NDJSON con gzip, un evento por línea, como en la página de la API HTTP.

Desde Java

Todas las funciones de Lyrelog son estáticas desde Java, con sobrecargas para los argumentos opcionales, y Configuration tiene 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) también funciona, y las funciones de un logger tienen sobrecargas, así que puedes omitir los argumentos finales.

Eventos verificados

Un evento verificado es uno que no puede haber enviado alguien que haya copiado la clave de ingesta pública de una app o de una página web. Qué demuestra eso, y qué no, se explica en Eventos verificados.

Envía con una clave de servidor, lyr_srv_.... Todos los eventos que envía están verificados (verified_by es server) y no cuentan para la cuota diaria de una dirección. Un propietario la crea en la página API keys del proyecto, Send events from a server, tras un inicio de sesión reciente (en los últimos 10 minutos), y se muestra una sola vez. Es un secreto: mantenla fuera del repositorio y léela del entorno del servidor o de su almacén de secretos.

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

Para comprobarlo, abre el explorador: en Filter, elige Verified by y Server key (los otros valores son App Attest y Not verified). Un evento abierto lo indica en Context, en su línea Sender: Verified, server key o Not verified, public key.

Los eventos enviados con una clave de ingesta, lyr_ing_..., o con una clave de acceso total, lyr_adm_..., llegan sin verificar: cualquiera que tenga una clave pública podría haber enviado lo mismo, y cuentan para la cuota diaria. Un evento verificado demuestra quién lo envió, no que lo que dice sea cierto.

Consulta Eventos verificados para saber quién verifica qué y cómo funciona la cuota diaria.

Configuración

OpciónPredeterminadoSignificado
apiKeyobligatoriaLa clave de servidor del proyecto (lyr_srv_...) o una clave de ingesta. null o en blanco: no se inicia nada
endpointhttps://ingest.lyrelog.comLa URL base; si pegas una ruta /v1/..., se quita. Solo https; http solo para localhost
environment$LYRELOG_ENVIRONMENT o, si no, productionCualquier nombre válido
platformjvmapi, worker...
releaseel Implementation-Version del jar arrancadoSe envía como resource.app_version
appIdel Implementation-Title o el nombre de archivo del jar arrancado o, si no, la clase principalSe envía como resource.app_id: el nombre del servicio
minimumLevelLevel.DEBUGLos eventos por debajo se descartan antes de entrar en la cola
flushIntervalMillis5 sCada cuánto envía el hilo en segundo plano
maxBatchBytes512 KiBUn lote se cierra en el límite que se alcance primero (siempre dentro de 4 MiB)
maxBatchEvents500Como mucho 2.000
maxQueue10.000Eventos esperando a escribirse; por encima, el más antiguo se descarta y se cuenta
maxDiskBytes20 MBTope del directorio de cola, empezando por lo más antiguo
maxEventAgeMillis7 díasLos eventos en cola más antiguos se descartan
redactedKeysnull: DEFAULT_REDACTED_KEYSNombres de clave que se ocultan; tu lista sustituye a los predeterminados, una lista vacía lo desactiva
storageDirectoryun directorio temporal por procesoDónde vive la cola; consulta Dónde esperan los eventos
captureUncaughtfalseRegistra las excepciones no capturadas
shutdownHooktrueCierra al apagarse la JVM
closeTimeoutMillis5 sCuánto espera el cierre al último envío
diagnosticsla salida de error estándarRecibe los mensajes propios del SDK (un Consumer<String>). No lo apuntes a un logger que alimente a Lyrelog

Entrega y límites

Nunca bloqueaRegistrar copia el evento y vuelve; un escritor en segundo plano lo pone en el directorio de cola y nunca espera a la red. Un hilo en segundo plano envía. Seguro para uso concurrente.
LotesHasta 500 eventos o 512 KiB por petición, con gzip, cada flushIntervalMillis. Un evento de más de 1 MiB una vez codificado se descarta y se cuenta.
ReintentosDe 1 s, duplicándose hasta 5 min, con jitter completo, respetando Retry-After; se reenvían los mismos bytes. Cualquier otro 4xx descarta el lote, un 3xx (una redirección, que nunca se sigue) lo descarta, y una clave rechazada (401, 403) detiene los envíos hasta que el proceso se reinicia y conserva los eventos. Un lote que el servidor sigue rechazando mientras otros pasan va al final de la cola y luego se descarta.
Cuota mensualCuando una organización Free ha agotado los eventos de su mes, el servidor responde 429. Los eventos se quedan en la cola y salen en cuanto el servidor vuelve a aceptarlos, dentro de los topes de 20 MB y 7 días. El SDK imprime un aviso en sus diagnósticos, y solo vuelve a hacerlo después de que se haya aceptado algún lote entretanto.
Los descartes se venLos eventos perdidos por los topes se convierten en un aviso lyrelog_events_dropped (área lyrelog) con el recuento.
Sus propios problemasUn endpoint incorrecto, un 404, una clave rechazada, líneas rechazadas o un endpoint que no responde se indican una vez por proceso en diagnostics (la salida de error estándar por defecto), cada línea empezando por lyrelog: .
Contextoos_name y os_version (los os.name y os.version de la JVM), el id de la app, la versión, el entorno y la plataforma, un id de instalación por proceso y un id de sesión por proceso.
SecretosLos valores bajo claves cuyo nombre es o termina en authorization, cookie, password, token, secret, apikey y el resto de la lista común se convierten en "[redacted]", a cualquier profundidad, antes de recortar nada.
LímitesLas cadenas largas se cortan respetando los límites de los caracteres, los atributos sobrantes se cuentan en lyrelog_dropped_attrs y los payloads de más de 64 KiB se resumen como {"lyrelog_truncated": true, "bytes": N, "preview": "..."}.
La claveAl imprimir una Configuration, queda oculta.

Cambia la lista de ocultación con redactedKeys: tu lista sustituye a los predeterminados, y una lista vacía desactiva la ocultación. Para añadir nombres:

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