Go
Logs estruturados dos seus serviços Go, com um handler de log/slog. Só a biblioteca padrão.
O módulo é go.lyrelog.com/lyrelog. Ele exige Go 1.24 ou mais recente e não tem dependências.
Prévia interna: este pacote ainda não foi publicado. Até lá, go get go.lyrelog.com/lyrelog
falha: o repositório é privado e ainda não tem release.
Instalação
go get go.lyrelog.com/lyrelogPrimeiros passos
import "go.lyrelog.com/lyrelog"
client, err := lyrelog.New(lyrelog.Config{
APIKey: "lyr_srv_...", // a server key, or read it from your own config
Platform: "api",
})
if err != nil {
log.Fatal(err) // only for a bad config: logging itself never fails
}
defer client.Close() // sends what is left (waits at most 5 s)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.
Só APIKey é obrigatório: sem ele, New retorna um erro e um cliente nil. Um *Client nil
não faz nada, então o código pode registrar logs antes de ter um cliente (ou sem nenhum).
Endpoint tem como padrão https://ingest.lyrelog.com; é a URL base, e um caminho
/v1/events:batch colado é removido.
log.Fatal e os.Exit pulam as chamadas adiadas, então defer client.Close() nunca roda depois
deles. Em main, retorne um código de saída de uma função que faz o trabalho:
func main() { os.Exit(run()) }
func run() int {
client, err := lyrelog.New(lyrelog.Config{APIKey: os.Getenv("LYRELOG_KEY")})
if err != nil {
fmt.Fprintln(os.Stderr, err) // client is nil and does nothing: carry on without it
}
defer client.Close() // runs before os.Exit
// ...
return 0
}Numa função serverless (AWS Lambda), chame client.Flush(ctx) antes de o handler retornar: o
runtime pode congelar o processo antes do próximo envio.
Registrar eventos
Um método por nível: Trace, Debug, Info, Notice, Warning, Error, Critical, ou
Log(level, message, ...). Os detalhes são opções: lyrelog.Category, lyrelog.Attrs,
lyrelog.Payload e lyrelog.User.
client.Info("checkout_done", lyrelog.Attrs{"plan": "pro", "latency_ms": 412})
client.Error("payment_failed",
lyrelog.Category("billing"),
lyrelog.Attrs{"code": "card_declined"},
lyrelog.Payload(map[string]any{"response": body}),
)Os atributos podem ser strings, números, booleanos, nil, slices de strings e maps aninhados (4
níveis). Nomes com pontos são reescritos com _. Várias opções Attrs se combinam, e a chave que
vem depois prevalece. Um Payload é codificado com encoding/json: passe json.RawMessage para
bytes que já são JSON (um []byte simples chega como uma string base64).
Loggers para cada área
billing := client.Logger("billing")
billing.Warning("invoice_retry", lyrelog.Attrs{"attempt": 2})Usuários
client.SetUser("u_123") // attached to every following event
client.SetUser("") // clear itUm servidor atende muitas pessoas ao mesmo tempo: defina o usuário em cada evento com
lyrelog.User(id), que substitui o de SetUser naquele evento.
O handler de slog
Envie registros de log/slog para o Lyrelog:
logger := slog.New(lyrelog.NewSlogHandler(client, &lyrelog.SlogOptions{Category: "app"}))
logger.Info("order_shipped", "order_id", id, "category", "fulfillment")- A mensagem do registro vira a mensagem do evento, e o horário do registro vira o horário do evento; atributos e grupos viram atributos aninhados.
- Um atributo string
categoryno nível superior define a área (e não é enviado como atributo); sem ele, é usado oCategorydo handler. - Níveis:
Debug-4e abaixo étrace,Debugédebug,Infoéinfo, entreInfoeWarnénotice,Warnéwarning,Erroréerror,Error+4e acima écritical. SlogOptions.Leveladiciona um mínimo além do mínimo do cliente;AddSourceadiciona um atributosourcecom a função, o arquivo e a linha de quem chamou. Compile comgo build -trimpathpara que o arquivo tenha caminhos de módulo em vez dos diretórios da sua máquina de build.
Para continuar imprimindo no terminal também, envie cada registro para os dois handlers. No Go
1.26 ou mais recente, slog.NewMultiHandler faz isso:
logger := slog.New(slog.NewMultiHandler(
slog.NewTextHandler(os.Stderr, nil),
lyrelog.NewSlogHandler(client, &lyrelog.SlogOptions{Category: "app"}),
))
slog.SetDefault(logger)Um middleware de net/http
Não há middleware 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:
func logRequests(client *lyrelog.Client, next http.Handler) http.Handler {
httpLog := client.Logger("http")
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
start := time.Now()
recorder := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
next.ServeHTTP(recorder, r)
level := lyrelog.LevelInfo
switch {
case recorder.status >= 500:
level = lyrelog.LevelError
case recorder.status >= 400:
level = lyrelog.LevelWarning
}
httpLog.Log(level, "http_request_served", lyrelog.Attrs{
"method": r.Method,
"route": r.Pattern, // set by http.ServeMux (Go 1.23+), e.g. "GET /users/{id}"
"status": recorder.status,
"duration_ms": time.Since(start).Milliseconds(),
})
})
}
type statusRecorder struct {
http.ResponseWriter
status int
}
func (s *statusRecorder) WriteHeader(code int) {
s.status = code
s.ResponseWriter.WriteHeader(code)
}
// Unwrap lets http.ResponseController reach the original writer (Flush, deadlines).
func (s *statusRecorder) Unwrap() http.ResponseWriter { return s.ResponseWriter }
// http.ListenAndServe(":8080", logRequests(client, mux))r.Pattern fica vazio numa requisição que não bateu com nenhuma rota.
Erros
if err := charge(ctx, order); err != nil {
client.CaptureError(err, lyrelog.Category("billing"), lyrelog.Attrs{"order_id": order.ID})
}O evento é exception, nível error, com error_type e error_message nos atributos e, no
payload, a cadeia do erro (cada erro encapsulado) e a stack. Um erro nil não registra nada.
Logger.CaptureError faz o mesmo com a categoria do logger. O nível é sempre error: para outro
nível, registre o erro você mesmo com Log.
Panics
O SDK não recupera panics. O net/http recupera o panic de um handler e só o imprime, então
registre-o num middleware que envolva o anterior:
func recoverPanics(client *lyrelog.Client, next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
v := recover()
if v == nil {
return
}
if v == http.ErrAbortHandler {
panic(v)
}
err, ok := v.(error)
if !ok {
err = fmt.Errorf("panic: %v", v)
}
client.CaptureError(err, lyrelog.Category("http"),
lyrelog.Attrs{"handled": false, "mechanism": "panic", "route": r.Pattern})
http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
}()
next.ServeHTTP(w, r)
})
}
// http.ListenAndServe(":8080", recoverPanics(client, logRequests(client, mux)))A stack no payload é capturada onde o panic foi recuperado, então ainda mostra os frames que entraram em panic. Um panic numa goroutine sua derruba o programa antes de qualquer coisa ser enviada: recupere-o nessa goroutine da mesma forma.
Ambientes e plataforma
Environment tem como padrão a variável de ambiente LYRELOG_ENVIRONMENT (em minúsculas); sem
ela, production. Platform tem como padrão go. Defina qualquer um dos dois na config:
client, err := lyrelog.New(lyrelog.Config{
APIKey: "lyr_srv_...",
Environment: "staging",
Platform: "worker",
})Os dois devem ter letras minúsculas, dígitos, - e _, até 32, começando com uma letra ou um
dígito. Um Config.Environment ou Config.Platform inválido faz New retornar um erro; um
$LYRELOG_ENVIRONMENT inválido é informado em ErrorLog e substituído por production, então um
erro de digitação num deploy nunca derruba um serviço.
Release tem como padrão a versão do módulo principal tirada das informações de build, e AppID,
o caminho do módulo principal.
Consentimento
O consentimento é para apps que rodam no dispositivo de alguém. Um SDK de servidor envia o que recebe.
Esvaziar a fila e parar
err := client.Flush(ctx) // send what's queued now
client.Close() // flush (up to CloseTimeout) and stopFlush envia tudo o que estava na fila antes da chamada e espera por isso ou por ctx. Ele
retorna:
nilquando tudo chegou ao servidor;ctx.Err()se o contexto terminou antes;ErrUnauthorizeddepois de um401ou403(o cliente para de enviar até o processo reiniciar e mantém a fila);- um erro dizendo que um lote foi recusado e descartado (o resto foi enviado mesmo assim);
- um erro dizendo que a entrega falhou e será tentada de novo, com os eventos mantidos. Durante um
Retry-Afterpedido pelo servidor,Flushretorna isso na hora e não envia nada; ErrCloseddepois deClose.
Close espera no máximo CloseTimeout pelo último esvaziamento da fila e retorna os mesmos valores; os eventos
ainda não enviados nesse momento são descartados e contados em Stats().Dropped. Depois de
Close, as chamadas de log não fazem nada.
client.Stats() retorna Queued (esperando, incluindo um lote sendo reenviado), Sent (aceitos
pelo servidor), Rejected (linhas que o servidor recusou, nunca reenviadas) e Dropped (pelo
cliente: fila estourada, um lote recusado ou sobras no Close).
Em desenvolvimento e testes
Sem um APIKey, New retorna um erro e um cliente nil, e um cliente nil não faz nada: o
mesmo código roda nos testes e num laptop sem chave, como no exemplo run acima. O handler de
slog sobre um cliente nil descarta todos os registros.
Para ver o que um teste registra, passe um HTTPClient cujo Transport grave as requisições, ou
aponte Endpoint para um httptest.Server (http:// simples é permitido para endereços de
loopback).
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.
client, err := lyrelog.New(lyrelog.Config{
APIKey: os.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
| Campo | Padrão | Significado |
|---|---|---|
Endpoint | https://ingest.lyrelog.com | A URL base; um caminho /v1/... colado é removido. http:// simples só para localhost |
APIKey | obrigatório | A chave de servidor do projeto (lyr_srv_...), ou uma chave de ingestão |
Environment | $LYRELOG_ENVIRONMENT, senão production | Qualquer nome válido |
Platform | go | api, worker... |
Release | a versão do módulo | Enviado como resource.app_version |
AppID | o caminho do módulo | Enviado como resource.app_id |
MinimumLevel | LevelDebug | Eventos abaixo dele são descartados antes de entrar na fila |
FlushInterval | 5 s | Com que frequência a goroutine em segundo plano envia |
MaxQueue | 10.000 | Além disso, os mais antigos são descartados e contados em Stats().Dropped |
MaxQueueBytes | 16 MiB | O mesmo limite, em bytes |
CloseTimeout | 5 s | Quanto tempo Close espera pelo último esvaziamento da fila |
HTTPClient | timeout de 30 s | O cliente que envia os lotes. Redirecionamentos nunca são seguidos, mesmo com o seu próprio cliente |
ErrorLog | stderr, uma vez | Recebe os diagnósticos do próprio SDK, cada um começando com lyrelog: . Sem ele, só a primeira chave recusada ou o primeiro lote descartado e o aviso de cota são impressos em stderr. Não o aponte para um logger que alimente este cliente |
Entrega e limites
- Uma goroutine em segundo plano junta lotes de até 500 eventos ou 512 KiB, com gzip; um lote cheio é enviado na hora. Seguro para uso concorrente.
- Novas tentativas com full jitter (1 s, dobrando até 5 min), respeitando
Retry-After(segundos ou uma data), reenviando os mesmos bytes. Qualquer outro 4xx descarta o lote; um 3xx o descarta e registra um aviso. - Valores em chaves cujo nome é ou termina com
authorization,cookie,password,token,secret,apikeye o resto da lista compartilhada viram"[redacted]"antes de entrar na fila: nos atributos e no payload, em qualquer profundidade (maps, structs pelos nomes JSON, slices,http.Header), antes de qualquer corte.Config.RedactKeyssubstitui a lista, e um slice vazio e não nil a desliga; para somar a ela,RedactKeys: append(lyrelog.DefaultRedactKeys(), "pin"). - Quando uma organização Free já usou os eventos do mês, o servidor responde
429. Os eventos ficam em memória e saem quando o servidor voltar a aceitá-los, atéMaxQueue. O cliente registra um aviso emErrorLog(ou stderr) e não diz mais nada até um lote ser aceito. - Contexto:
os_nameéruntime.GOOS,app_buildé a revisão do VCS quando o binário tem uma, e os ids de instalação e de sessão são por processo. - Os limites são aplicados antes de entrar na fila: atributos além de 200 folhas (valores aninhados contados um a um) são
descartados e contados em
lyrelog_dropped_attrs, pontos nos nomes viram_(http.statusvirahttp_status), erros, horários, durações eStringers viram strings, structs viram a sua forma JSON, NaN viranull. Um payload acima de 64 KiB vira{"lyrelog_truncated": true, "bytes": N, "preview": "..."}com o seu primeiro KiB. Os atributos de um evento são limitados a 256 KiB codificados, e um evento que não cabe num lote de 512 KiB é descartado e contado. - Imprimir um
Configou um*Clientcomfmtoculta a chave de API.