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

Go

Logs estruturados dos seus serviços Go, com um handler de log/slog. Só a biblioteca padrão.

Servidores, com um handler de slog

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/lyrelog

Primeiros 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 it

Um 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 category no nível superior define a área (e não é enviado como atributo); sem ele, é usado o Category do handler.
  • Níveis: Debug-4 e abaixo é trace, Debug é debug, Info é info, entre Info e Warn é notice, Warn é warning, Error é error, Error+4 e acima é critical.
  • SlogOptions.Level adiciona um mínimo além do mínimo do cliente; AddSource adiciona um atributo source com a função, o arquivo e a linha de quem chamou. Compile com go build -trimpath para 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.

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 stop

Flush envia tudo o que estava na fila antes da chamada e espera por isso ou por ctx. Ele retorna:

  • nil quando tudo chegou ao servidor;
  • ctx.Err() se o contexto terminou antes;
  • ErrUnauthorized depois de um 401 ou 403 (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-After pedido pelo servidor, Flush retorna isso na hora e não envia nada;
  • ErrClosed depois de Close.

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

CampoPadrãoSignificado
Endpointhttps://ingest.lyrelog.comA URL base; um caminho /v1/... colado é removido. http:// simples só para localhost
APIKeyobrigatórioA chave de servidor do projeto (lyr_srv_...), ou uma chave de ingestão
Environment$LYRELOG_ENVIRONMENT, senão productionQualquer nome válido
Platformgoapi, worker...
Releasea versão do móduloEnviado como resource.app_version
AppIDo caminho do móduloEnviado como resource.app_id
MinimumLevelLevelDebugEventos abaixo dele são descartados antes de entrar na fila
FlushInterval5 sCom que frequência a goroutine em segundo plano envia
MaxQueue10.000Além disso, os mais antigos são descartados e contados em Stats().Dropped
MaxQueueBytes16 MiBO mesmo limite, em bytes
CloseTimeout5 sQuanto tempo Close espera pelo último esvaziamento da fila
HTTPClienttimeout de 30 sO cliente que envia os lotes. Redirecionamentos nunca são seguidos, mesmo com o seu próprio cliente
ErrorLogstderr, uma vezRecebe 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, apikey e 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.RedactKeys substitui 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 em ErrorLog (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.status vira http_status), erros, horários, durações e Stringers viram strings, structs viram a sua forma JSON, NaN vira null. 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 Config ou um *Client com fmt oculta a chave de API.