Acesso antecipadoSó por convite, e os SDKs ainda não foram publicados.Pedir um convite
Ir para o conteúdo
Docs

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.

Servidores Java e Kotlin, com um appender de Logback

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 it

O 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 LogbackLyrelog
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, ERRORtrace, debug, info, warning, error
A mensagem formatadamessage; 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çãoattrs.error_type, attrs.error_message e payload.exception (frames, causas)
O horário do registroO 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.

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 stop

Você 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.tmpdir para este processo, apagado no close. 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óximo start. 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 environment

Para 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çãoPadrãoSignificado
apiKeyobrigatórioA chave de servidor do projeto (lyr_srv_...), ou uma chave de ingestão. null ou em branco: nada é iniciado
endpointhttps://ingest.lyrelog.comA URL base; um caminho /v1/... colado é removido. Só https, http só para localhost
environment$LYRELOG_ENVIRONMENT, senão productionQualquer nome válido
platformjvmapi, worker...
releaseo Implementation-Version do jar iniciadoEnviado como resource.app_version
appIdo Implementation-Title ou o nome do arquivo do jar iniciado, senão a classe principalEnviado como resource.app_id: o nome do serviço
minimumLevelLevel.DEBUGEventos abaixo dele são descartados antes de entrar na fila
flushIntervalMillis5 sCom que frequência a thread em segundo plano envia
maxBatchBytes512 KiBUm lote fecha no limite que chegar primeiro (mantido dentro de 4 MiB)
maxBatchEvents500No máximo 2.000
maxQueue10.000Eventos esperando para serem gravados; além disso, o mais antigo é descartado e contado
maxDiskBytes20 MBLimite do diretório de fila, saindo primeiro os mais antigos
maxEventAgeMillis7 diasEventos na fila mais antigos que isso são descartados
redactedKeysnull: DEFAULT_REDACTED_KEYSNomes de chave a ocultar; a sua lista substitui os padrões, e uma lista vazia desliga
storageDirectoryum diretório temporário por processoOnde a fila fica; veja Onde os eventos esperam
captureUncaughtfalseRegistra exceções não capturadas
shutdownHooktrueFecha quando a JVM é desligada
closeTimeoutMillis5 sQuanto tempo o fechamento espera pelo último envio
diagnosticssaída de erro padrãoRecebe as mensagens do próprio SDK (um Consumer<String>). Não o aponte para um logger que alimente o Lyrelog

Entrega e limites

Nunca bloqueiaRegistrar 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.
LotesAté 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 tentativas1 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 mensalQuando 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íveisOs eventos perdidos pelos limites viram um único aviso lyrelog_events_dropped (área lyrelog) com a contagem.
Problemas do próprio SDKUm 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: .
Contextoos_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.
SegredosValores 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.
LimitesStrings 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 chaveImprimir 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",
))