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.
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 itEl 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 Logback | Lyrelog |
|---|---|
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, ERROR | trace, debug, info, warning, error |
| El mensaje formateado | message; 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ón | attrs.error_type, attrs.error_message y payload.exception (frames, causas) |
| La hora del registro | La 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.
Consentimiento
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 stopCasi 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.tmpdirpara este proceso, que se borra al llamar aclose. 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 siguientestart. 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 environmentPara 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ón | Predeterminado | Significado |
|---|---|---|
apiKey | obligatoria | La clave de servidor del proyecto (lyr_srv_...) o una clave de ingesta. null o en blanco: no se inicia nada |
endpoint | https://ingest.lyrelog.com | La URL base; si pegas una ruta /v1/..., se quita. Solo https; http solo para localhost |
environment | $LYRELOG_ENVIRONMENT o, si no, production | Cualquier nombre válido |
platform | jvm | api, worker... |
release | el Implementation-Version del jar arrancado | Se envía como resource.app_version |
appId | el Implementation-Title o el nombre de archivo del jar arrancado o, si no, la clase principal | Se envía como resource.app_id: el nombre del servicio |
minimumLevel | Level.DEBUG | Los eventos por debajo se descartan antes de entrar en la cola |
flushIntervalMillis | 5 s | Cada cuánto envía el hilo en segundo plano |
maxBatchBytes | 512 KiB | Un lote se cierra en el límite que se alcance primero (siempre dentro de 4 MiB) |
maxBatchEvents | 500 | Como mucho 2.000 |
maxQueue | 10.000 | Eventos esperando a escribirse; por encima, el más antiguo se descarta y se cuenta |
maxDiskBytes | 20 MB | Tope del directorio de cola, empezando por lo más antiguo |
maxEventAgeMillis | 7 días | Los eventos en cola más antiguos se descartan |
redactedKeys | null: DEFAULT_REDACTED_KEYS | Nombres de clave que se ocultan; tu lista sustituye a los predeterminados, una lista vacía lo desactiva |
storageDirectory | un directorio temporal por proceso | Dónde vive la cola; consulta Dónde esperan los eventos |
captureUncaught | false | Registra las excepciones no capturadas |
shutdownHook | true | Cierra al apagarse la JVM |
closeTimeoutMillis | 5 s | Cuánto espera el cierre al último envío |
diagnostics | la salida de error estándar | Recibe los mensajes propios del SDK (un Consumer<String>). No lo apuntes a un logger que alimente a Lyrelog |
Entrega y límites
| Nunca bloquea | Registrar 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. |
| Lotes | Hasta 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. |
| Reintentos | De 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 mensual | Cuando 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 ven | Los eventos perdidos por los topes se convierten en un aviso lyrelog_events_dropped (área lyrelog) con el recuento. |
| Sus propios problemas | Un 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: . |
| Contexto | os_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. |
| Secretos | Los 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ímites | Las 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 clave | Al 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",
))