Java e Kotlin (JVM)
Logs estruturados dos seus serviços Java e Kotlin (Spring, Ktor, JVM pura), com um appender de Logback. Nenhuma dependência além da biblioteca padrão do Kotlin.
O SDK para JVM exige Java 11 ou mais recente. Ele é escrito em Kotlin, e todas as funções podem
ser chamadas do Java. Usa o mesmo motor do SDK Android (lyrelog-core) e não tem
nenhuma outra dependência além da biblioteca padrão do Kotlin. Os registros de SLF4J e Logback
podem chegar por um appender separado e opcional.
Prévia interna: este pacote ainda não foi publicado. Até lá, o Gradle e o Maven não conseguem
baixar com.lyrelog:lyrelog-jvm: ele não está no Maven Central, e o repositório é privado e ainda
não tem release.
Instalação
Pelo Maven Central. Com Gradle, em 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")
}Com Maven, em 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>O appender não traz o Logback: ele usa o que a sua aplicação já tem (1.3 ou mais recente).
Primeiros passos
Uma vez, o mais cedo possível: em main, antes de o framework iniciar.
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
}Em 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);
}Use uma chave de servidor, lyr_srv_..., da página API keys do projeto (Send events from a
server). É um segredo: mantenha-a no ambiente do seu servidor, nunca num app ou numa página web.
Os eventos dela são verificados, e o limite diário de um mesmo endereço de remetente não se aplica a eles. Uma chave de ingestão, lyr_ing_..., também funciona, mas os eventos dela não são
verificados.
start retorna true quando iniciou o Lyrelog. Uma segunda chamada enquanto ele está rodando é
ignorada e retorna false. Uma chave null ou em branco não inicia nada e retorna false, e
todas as outras chamadas passam a não fazer nada, então uma variável de ambiente faltando em
desenvolvimento ou nos testes não derruba o serviço. Eventos registrados antes de start são
ignorados. start nunca lança exceção.
Os eventos vão para https://ingest.lyrelog.com. Passe endpoint só para enviá-los a outro
lugar. É a URL base (se você colar um caminho .../v1/events:batch, ele é removido) e precisa ser
https://, ou http:// para localhost, 127.0.0.1 ou ::1. Qualquer outro endpoint é
recusado: nada é enviado, e o SDK avisa uma vez nos seus diagnósticos.
Registrar eventos
Uma função por nível: 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),
)Os atributos podem ser strings, números, booleanos, null, listas (enviadas como strings) e maps
aninhados até 4 níveis. O payload é qualquer map, lista ou valor. Uma chamada de log nunca bloqueia
e nunca lança exceção: ela copia o evento e retorna. Depois de close, as chamadas de log não
fazem nada.
Loggers para cada área
val billing = Lyrelog.logger("billing")
billing.warning("invoice_retry", mapOf("attempt" to 2))Um logger é barato de criar e de manter (num campo, num companion object). Ele registra no que
estiver rodando no momento da chamada, então pode ser criado antes de start.
Usuários
Um servidor atende muitas pessoas ao mesmo tempo. Defina o usuário no evento, ou para o trabalho de uma requisição:
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 itO user do próprio evento prevalece sobre o do escopo, e o do escopo sobre setUser. Um escopo é
local à thread: em Java, abra-o com try-with-resources num servlet filter (como no
filtro de requisições abaixo). Corrotinas e código reativo (Ktor,
WebFlux) pulam de uma thread para outra, então nesses casos passe user em cada evento. Use os
seus próprios ids, não endereços de email.
O appender de Logback
Com lyrelog-jvm-logback, todo registro que os seus loggers escrevem pelo SLF4J ou pelo Logback
também pode ir para o Lyrelog. Adicione o appender em logback.xml (no Spring Boot,
logback-spring.xml):
<configuration>
<appender name="LYRELOG" class="com.lyrelog.logback.LyrelogAppender" />
<root level="INFO">
<appender-ref ref="LYRELOG" />
</root>
</configuration>O appender encaminha para o Lyrelog em execução, iniciado no código como acima. Ou deixe que ele
mesmo inicie o Lyrelog, assim o serviço não precisa de código nenhum; nesse caso, ele fecha o
Lyrelog quando o Logback para:
<appender name="LYRELOG" class="com.lyrelog.logback.LyrelogAppender">
<apiKey>${LYRELOG_KEY}</apiKey>
<platform>api</platform>
<!-- <environment>staging</environment>, <endpoint>...</endpoint> -->
</appender>Registros feitos antes de o Lyrelog iniciar são ignorados, então inicie-o antes de o seu framework registrar o que você quer guardar. Para continuar imprimindo no console também, mantenha o seu appender de console ao lado deste.
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 e Logback | Lyrelog |
|---|---|
Nome do logger (com.example.billing.Invoices) | category, a não ser que o appender tenha um <category> ou o registro uma chave category |
TRACE, DEBUG, INFO, WARN, ERROR | trace, debug, info, warning, error |
| A mensagem formatada | message; com argumentos, o padrão vai para attrs.msg_template, para agrupar |
Entradas do MDC e pares chave-valor do SLF4J 2 (addKeyValue) | attrs, exceto user_id (o usuário do evento) e category. <includeMdc>false</includeMdc> deixa o MDC de fora |
| A exceção | attrs.error_type, attrs.error_message e payload.exception (frames, causas) |
| O horário do registro | O horário do evento |
O nível mínimo do próprio Lyrelog continua valendo: registros trace são descartados a não ser que
minimumLevel seja Level.TRACE. O appender ignora registros dos loggers com.lyrelog e das
threads do próprio SDK, então nunca entra em loop. Não há appender para Log4j 2 nem para
java.util.logging. Para eventos que você quer ver em gráficos, prefira chamadas diretas com um
nome estável: uma mensagem formatada é texto livre.
Um filtro de requisições para Spring
Não há filtro embutido. Este registra cada requisição como http_request_served na área http,
em info, warning para um 4xx e error para um 5xx, com o padrão da rota em vez do caminho, para que
os ids não explodam a cardinalidade. Ele também define o usuário da requisição para tudo o que for
registrado enquanto ela é tratada:
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));
}
}
}
}O Spring registra nos seus próprios loggers, com a stack, uma exceção lançada por um handler;
então, com o appender de Logback, ela já chega com error_type e error_message. Capturá-la
também no filtro a registraria duas vezes.
Erros
try {
charge(order)
} catch (e: PaymentException) {
Lyrelog.captureError(e, category = "billing", attrs = mapOf("order_id" to order.id))
}O evento é exception, nível error, com error_type (o nome da classe) e error_message nos
atributos e, no payload, a descrição, até 60 frames, as causas (até 8, com 20 frames cada) e as
exceções suprimidas. Os seus atributos são adicionados; esses dois prevalecem. level muda o nível
e user define o usuário do evento. logger.captureError(e) usa a categoria do logger.
Exceções não capturadas
Desligado por padrão. Com captureUncaught = true, uma exceção que nenhum código capturou, em
qualquer thread, é registrada como exception com handled: false, mechanism: uncaught_exception
e o nome da thread em thread. Depois, roda o handler que já estava lá (ou a impressão de sempre da
JVM). Quando essa thread era a última, o shutdown hook envia o evento antes de a JVM sair.
Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY"), captureUncaught = true))Os frameworks capturam por conta própria as exceções de uma requisição e as registram: essas chegam pelo
appender de Logback. Uma exceção numa tarefa entregue a um ExecutorService com submit vai para
o Future dela, não para este handler.
Ambientes e plataforma
environment vem da variável de ambiente LYRELOG_ENVIRONMENT; sem ela, é production.
platform é jvm. Defina qualquer um dos dois na configuração:
Lyrelog.start(Configuration(apiKey = key, environment = "staging", platform = "worker"))Qualquer nome serve: letras minúsculas, dígitos, - e _, até 32. Outro texto na configuração é
limpo para você (Staging EU vira staging-eu); um $LYRELOG_ENVIRONMENT inválido é informado
uma vez e substituído por production, então um erro de digitação num deploy nunca derruba um
serviço.
release (resource.app_version) tem como padrão o Implementation-Version do jar com que a JVM
foi iniciada (java -jar orders.jar), e appId (resource.app_id), o Implementation-Title
dele; sem isso, o nome do arquivo do jar e, por fim, a classe principal. Defina-os quando não for
isso que você quer.
Consentimento
O consentimento é para apps que rodam no dispositivo de alguém. Um SDK de servidor envia o que recebe; não há opção de consentimento.
Esvaziar a fila e parar
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 stopVocê raramente precisa de qualquer uma delas: o SDK envia a cada 5 s, e um shutdown hook da JVM o
fecha quando a JVM sai normalmente (o fim de main, System.exit, SIGTERM e Ctrl-C). kill -9
pula o hook. Desligue o hook com shutdownHook = false e chame close você mesmo.
flush respeita um Retry-After pedido pelo servidor: não envia antes disso. Depois de close,
start pode ser chamado de novo.
Numa função serverless (AWS Lambda), chame Lyrelog.flush() antes de o handler retornar: o
runtime pode congelar o processo antes do próximo envio.
Onde os eventos esperam
Os eventos são gravados num diretório de fila, um arquivo por lote, e um lote só sai dali depois que o servidor o aceita.
- Por padrão, um diretório novo em
java.io.tmpdirpara este processo, apagado noclose. O que não foi enviado até lá se perde, como numa fila em memória. - Com
storageDirectory, um diretório seu: o que não foi enviado (o servidor estava inacessível, ou pediu para esperar) fica ali e sai depois do próximostart. Um processo por vez: o diretório fica bloqueado, e um segundo processo que o encontra bloqueado usa uma fila num diretório temporário, e avisa uma vez.
Os dois têm limite de 20 MB e 7 dias, saindo primeiro os mais antigos (maxDiskBytes,
maxEventAgeMillis).
Em desenvolvimento e testes
Deixe a chave de fora: Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY"))) não
inicia nada quando a variável não está definida, e todas as chamadas não fazem nada, então os testes
e um laptop sem chave rodam o mesmo código. O appender de Logback também não faz nada enquanto o
Lyrelog não está rodando.
Para ver o que um teste registra, aponte endpoint para um servidor HTTP local (http:// simples
é permitido para endereços de loopback) e leia os lotes que ele recebe: NDJSON com gzip, um evento
por linha, como na página da API HTTP.
A partir do Java
Todas as funções de Lyrelog são estáticas no Java, com sobrecargas para os argumentos opcionais,
e Configuration tem um 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) também funciona, e as funções de um logger têm sobrecargas, então os
argumentos finais podem ser omitidos.
Eventos verificados
Um evento verificado é um evento que não pode ter sido enviado por alguém que copiou a chave de ingestão pública de um app ou de uma página web. O que isso prova, e o que não prova, está em Eventos verificados.
Envie com uma chave de servidor, lyr_srv_.... Todo evento que ela envia é verificado
(verified_by é server) e não conta para a
cota diária de um endereço. Um
proprietário a cria na página API keys do projeto, em Send events from a server, depois de
ter entrado recentemente (nos últimos 10 minutos), e ela é mostrada uma única vez. É um segredo:
mantenha-a fora do repositório e leia-a do ambiente do servidor ou do seu gerenciador de segredos.
Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY"))) // lyr_srv_..., set in the server's environmentPara conferir, abra o explorer: em Filter, escolha Verified by e Server key (os outros valores são App Attest e Not verified). Um evento aberto mostra isso em Context, na linha Sender: Verified, server key ou Not verified, public key.
Eventos enviados com uma chave de ingestão, lyr_ing_..., ou com uma chave de acesso total,
lyr_adm_..., chegam não verificados: qualquer pessoa com uma chave pública poderia ter enviado o
mesmo, e eles contam para a cota diária. Um evento verificado prova quem o enviou, não que o que
ele diz seja verdade.
Veja Eventos verificados para saber quem verifica o quê e como funciona a cota diária.
Configuração
| Opção | Padrão | Significado |
|---|---|---|
apiKey | obrigatório | A chave de servidor do projeto (lyr_srv_...), ou uma chave de ingestão. null ou em branco: nada é iniciado |
endpoint | https://ingest.lyrelog.com | A URL base; um caminho /v1/... colado é removido. Só https, http só para localhost |
environment | $LYRELOG_ENVIRONMENT, senão production | Qualquer nome válido |
platform | jvm | api, worker... |
release | o Implementation-Version do jar iniciado | Enviado como resource.app_version |
appId | o Implementation-Title ou o nome do arquivo do jar iniciado, senão a classe principal | Enviado como resource.app_id: o nome do serviço |
minimumLevel | Level.DEBUG | Eventos abaixo dele são descartados antes de entrar na fila |
flushIntervalMillis | 5 s | Com que frequência a thread em segundo plano envia |
maxBatchBytes | 512 KiB | Um lote fecha no limite que chegar primeiro (mantido dentro de 4 MiB) |
maxBatchEvents | 500 | No máximo 2.000 |
maxQueue | 10.000 | Eventos esperando para serem gravados; além disso, o mais antigo é descartado e contado |
maxDiskBytes | 20 MB | Limite do diretório de fila, saindo primeiro os mais antigos |
maxEventAgeMillis | 7 dias | Eventos na fila mais antigos que isso são descartados |
redactedKeys | null: DEFAULT_REDACTED_KEYS | Nomes de chave a ocultar; a sua lista substitui os padrões, e uma lista vazia desliga |
storageDirectory | um diretório temporário por processo | Onde a fila fica; veja Onde os eventos esperam |
captureUncaught | false | Registra exceções não capturadas |
shutdownHook | true | Fecha quando a JVM é desligada |
closeTimeoutMillis | 5 s | Quanto tempo o fechamento espera pelo último envio |
diagnostics | saída de erro padrão | Recebe as mensagens do próprio SDK (um Consumer<String>). Não o aponte para um logger que alimente o Lyrelog |
Entrega e limites
| Nunca bloqueia | Registrar copia o evento e retorna; um único writer em segundo plano o coloca no diretório de fila e nunca espera pela rede. Uma thread em segundo plano envia. Seguro para uso concorrente. |
| Lotes | Até 500 eventos ou 512 KiB por requisição, com gzip, a cada flushIntervalMillis. Um evento acima de 1 MiB depois de codificado é descartado e contado. |
| Novas tentativas | 1 s, dobrando até 5 min, com full jitter, respeitando Retry-After; os mesmos bytes são reenviados. Qualquer outro 4xx descarta o lote, um 3xx (um redirecionamento, nunca seguido) o descarta, e uma chave recusada (401, 403) para os envios até o processo reiniciar e mantém os eventos. Um lote que o servidor continua rejeitando enquanto outros passam vai para o fim da fila e depois é descartado. |
| Cota mensal | Quando uma organização Free já usou os eventos do mês, o servidor responde 429. Os eventos ficam na fila e saem quando o servidor voltar a aceitá-los, dentro dos limites de 20 MB e 7 dias. O SDK imprime um aviso nos seus diagnósticos, e de novo só depois de um lote ter sido aceito nesse meio-tempo. |
| Descartes visíveis | Os eventos perdidos pelos limites viram um único aviso lyrelog_events_dropped (área lyrelog) com a contagem. |
| Problemas do próprio SDK | Um endpoint errado, um 404, uma chave recusada, linhas rejeitadas ou um endpoint que não responde são informados uma vez por processo em diagnostics (o stderr, por padrão), cada linha começando com lyrelog: . |
| Contexto | os_name e os_version (o os.name e o os.version da JVM), o id do app, a versão, o ambiente e a plataforma, um id de instalação por processo e um id de sessão por processo. |
| Segredos | Valores em chaves cujo nome é ou termina com authorization, cookie, password, token, secret, apikey e o resto da lista compartilhada viram "[redacted]", em qualquer profundidade, antes de qualquer corte. |
| Limites | Strings longas cortadas sem partir um caractere, atributos extras contados em lyrelog_dropped_attrs, payloads acima de 64 KiB resumidos como {"lyrelog_truncated": true, "bytes": N, "preview": "..."}. |
| A chave | Imprimir uma Configuration a oculta. |
Mude a lista de ocultação com redactedKeys: a sua lista substitui os padrões, e uma lista vazia
desliga a ocultação. Para somar a ela:
Lyrelog.start(Configuration(
apiKey = System.getenv("LYRELOG_KEY"),
redactedKeys = Configuration.DEFAULT_REDACTED_KEYS + "card_number",
))