Go
Logs estructurados desde tus servicios Go, con un handler de log/slog. Solo la biblioteca estándar.
El módulo es go.lyrelog.com/lyrelog. Necesita Go 1.24 o posterior y no tiene dependencias.
Vista previa interna: este paquete aún no está publicado. Hasta entonces,
go get go.lyrelog.com/lyrelog falla: el repositorio es privado y todavía no tiene ninguna
versión publicada.
Instalación
go get go.lyrelog.com/lyrelogPrimeros pasos
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)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.
Solo APIKey es obligatorio: sin él, New devuelve un error y un cliente nil. Un *Client
nil no hace nada, así que el código puede registrar eventos antes de tener uno (o sin él).
Endpoint es https://ingest.lyrelog.com por defecto; es la URL base, y si pegas una ruta
/v1/events:batch, se elimina.
log.Fatal y os.Exit se saltan las llamadas diferidas, así que defer client.Close() nunca se
ejecuta después de ellas. En main, devuelve un código de salida desde una función que haga el
trabajo:
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
}En una función serverless (AWS Lambda), llama a client.Flush(ctx) antes de que el handler
devuelva: el runtime puede congelar el proceso antes del siguiente envío.
Registrar eventos
Un método por nivel: Trace, Debug, Info, Notice, Warning, Error, Critical, o
Log(level, message, ...). Los detalles son opciones: lyrelog.Category, lyrelog.Attrs,
lyrelog.Payload y 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}),
)Los atributos pueden ser cadenas, números, booleanos, nil, slices de cadenas y mapas anidados
(4 niveles). Los nombres con puntos se reescriben con _. Varias opciones Attrs se combinan, y
gana la clave posterior. Un Payload se codifica con encoding/json: pasa json.RawMessage para
bytes que ya son JSON (un []byte normal llega como cadena base64).
Loggers por área
billing := client.Logger("billing")
billing.Warning("invoice_retry", lyrelog.Attrs{"attempt": 2})Usuarios
client.SetUser("u_123") // attached to every following event
client.SetUser("") // clear itUn servidor atiende a muchas personas a la vez: indica el usuario en cada evento con
lyrelog.User(id), que sustituye al de SetUser para ese evento.
El handler de slog
Envía los registros de log/slog a Lyrelog:
logger := slog.New(lyrelog.NewSlogHandler(client, &lyrelog.SlogOptions{Category: "app"}))
logger.Info("order_shipped", "order_id", id, "category", "fulfillment")- El mensaje del registro es el mensaje del evento, y su hora, la hora del evento; los atributos y los grupos se convierten en atributos anidados.
- Un atributo de cadena
categoryen el nivel superior define el área (y no se envía como atributo); sin él se usa elCategorydel handler. - Niveles:
Debug-4y por debajo estrace,Debugesdebug,Infoesinfo, entreInfoyWarnesnotice,Warneswarning,Erroreserror,Error+4y por encima escritical. SlogOptions.Levelañade un mínimo encima del del cliente;AddSourceañade un atributosourcecon la función, el archivo y la línea de quien llama. Compila congo build -trimpathpara que el archivo contenga rutas de módulo y no los directorios de tu máquina de compilación.
Para seguir imprimiendo también en la terminal, envía cada registro a ambos handlers. En Go 1.26
o posterior, slog.NewMultiHandler lo hace:
logger := slog.New(slog.NewMultiHandler(
slog.NewTextHandler(os.Stderr, nil),
lyrelog.NewSlogHandler(client, &lyrelog.SlogOptions{Category: "app"}),
))
slog.SetDefault(logger)Un middleware de net/http
No hay middleware 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:
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 está vacío para una petición que no coincidió con ninguna ruta.
Errores
if err := charge(ctx, order); err != nil {
client.CaptureError(err, lyrelog.Category("billing"), lyrelog.Attrs{"order_id": order.ID})
}El evento es exception, con nivel error, con error_type y error_message en los atributos
y, en el payload, la cadena de errores (cada error envuelto) y el stack. Un error nil no
registra nada. Logger.CaptureError hace lo mismo con la categoría del logger. El nivel es
siempre error: para otro, registra el error tú mismo con Log.
Panics
El SDK no recupera los panics. net/http recupera el panic de un handler y solo lo imprime, así
que regístralo en un middleware, por fuera del de arriba:
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)))El stack del payload se toma donde se recuperó el panic, así que sigue mostrando los frames que provocaron el panic. Un panic en una goroutine tuya hace caer el programa antes de que se envíe nada: recupéralo en esa goroutine de la misma forma.
Entornos y plataforma
Environment toma por defecto la variable de entorno LYRELOG_ENVIRONMENT (en minúsculas) o, si
no, production. Platform es go por defecto. Puedes definir cualquiera de los dos en la
configuración:
client, err := lyrelog.New(lyrelog.Config{
APIKey: "lyr_srv_...",
Environment: "staging",
Platform: "worker",
})Ambos deben ser letras minúsculas, dígitos, - y _, hasta 32, empezando por una letra o un
dígito. Un Config.Environment o un Config.Platform no válidos hacen que New devuelva un
error; un $LYRELOG_ENVIRONMENT no válido se notifica en ErrorLog y se sustituye por
production, para que una errata en un despliegue nunca detenga un servicio.
Release toma por defecto la versión del módulo principal según la información de compilación, y
AppID, la ruta del módulo principal.
Consentimiento
El consentimiento es para apps que se ejecutan en el dispositivo de alguien. Un SDK de servidor envía lo que recibe.
Vaciar la cola y detener
err := client.Flush(ctx) // send what's queued now
client.Close() // flush (up to CloseTimeout) and stopFlush envía todo lo que estaba en cola antes de la llamada y espera a que termine o a ctx.
Devuelve:
nilcuando todo llegó al servidor;ctx.Err()si el contexto terminó antes;ErrUnauthorizedtras un401o un403(el cliente deja de enviar hasta que el proceso se reinicia y conserva su cola);- un error que dice que un lote se rechazó y se descartó (el resto sí se envió);
- un error que dice que la entrega falló y se reintentará, con los eventos conservados. Dentro de
un
Retry-Afterque haya pedido el servidor,Flushdevuelve esto al instante y no envía nada; ErrCloseddespués deClose.
Close espera como mucho CloseTimeout al último envío y devuelve los mismos valores; los
eventos que sigan sin enviarse entonces se descartan y se cuentan en Stats().Dropped. Después de
Close, las llamadas de registro no hacen nada.
client.Stats() devuelve Queued (en espera, incluido un lote que se está reintentando), Sent
(aceptados por el servidor), Rejected (líneas que el servidor rechazó, nunca se reenvían) y
Dropped (por el cliente: desbordamiento de la cola, un lote rechazado o pendientes al llamar a
Close).
En desarrollo y en tests
Sin APIKey, New devuelve un error y un cliente nil, y un cliente nil no hace nada: el mismo
código se ejecuta en los tests y en una laptop sin clave, como en el ejemplo de run de arriba.
El handler de slog sobre un cliente nil descarta todos los registros.
Para ver lo que registra un test, pasa un HTTPClient cuyo Transport guarde las peticiones, o
apunta Endpoint a un httptest.Server (se permite http:// sin cifrar para direcciones de
loopback).
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.
client, err := lyrelog.New(lyrelog.Config{
APIKey: os.Getenv("LYRELOG_KEY"), // lyr_srv_..., set in the server's environment
})Para 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
| Campo | Predeterminado | Significado |
|---|---|---|
Endpoint | https://ingest.lyrelog.com | La URL base; si pegas una ruta /v1/..., se elimina. http:// sin cifrar solo para localhost |
APIKey | obligatorio | La clave de servidor del proyecto (lyr_srv_...) o una clave de ingesta |
Environment | $LYRELOG_ENVIRONMENT o, si no, production | Cualquier nombre válido |
Platform | go | api, worker... |
Release | la versión del módulo | Se envía como resource.app_version |
AppID | la ruta del módulo | Se envía como resource.app_id |
MinimumLevel | LevelDebug | Los eventos por debajo se descartan antes de entrar en la cola |
FlushInterval | 5 s | Cada cuánto envía la goroutine en segundo plano |
MaxQueue | 10.000 | Por encima, se descartan los más antiguos y se cuentan en Stats().Dropped |
MaxQueueBytes | 16 MiB | El mismo tope, en bytes |
CloseTimeout | 5 s | Cuánto espera Close al último envío |
HTTPClient | timeout de 30 s | El cliente que envía los lotes. Nunca se siguen redirecciones, ni siquiera con tu propio cliente |
ErrorLog | stderr, una vez | Recibe los diagnósticos propios del SDK, cada uno empezando por lyrelog: . Sin él, solo se imprimen en stderr la primera clave rechazada o el primer lote descartado y el aviso de cuota. No lo apuntes a un logger que alimente a este cliente |
Entrega y límites
- Una goroutine en segundo plano agrupa hasta 500 eventos o 512 KiB por lote, con gzip; un lote lleno se envía de inmediato. Seguro para uso concurrente.
- Reintentos con jitter completo (de 1 s, duplicándose hasta 5 min), respetando
Retry-After(segundos o una fecha) y reenviando los mismos bytes. Cualquier otro 4xx descarta el lote; un 3xx lo descarta y registra un aviso. - Los valores bajo claves cuyo nombre es o termina en
authorization,cookie,password,token,secret,apikeyy el resto de la lista común se convierten en"[redacted]"antes de entrar en la cola: en los atributos y en el payload, a cualquier profundidad (mapas, structs por sus nombres JSON, slices,http.Header), antes de recortar nada.Config.RedactKeyssustituye la lista, y un slice vacío no nil la desactiva; para añadir nombres,RedactKeys: append(lyrelog.DefaultRedactKeys(), "pin"). - Cuando una organización Free ha agotado los eventos de su mes, el servidor responde
429. Los eventos se quedan en memoria y salen en cuanto el servidor vuelve a aceptarlos, hastaMaxQueue. El cliente registra un aviso enErrorLog(o en stderr) y no dice nada más hasta que se acepte un lote. - Contexto:
os_nameesruntime.GOOS,app_buildes la revisión del VCS cuando el binario la tiene, y los ids de instalación y de sesión son por proceso. - Los límites se aplican antes de entrar en la cola: los atributos que pasen de 200 hojas (los valores anidados se cuentan uno a uno) se
descartan y se cuentan en
lyrelog_dropped_attrs, los puntos en los nombres se convierten en_(http.statuspasa ahttp_status), los errores, las horas, las duraciones y losStringerse convierten en cadenas, los structs en su forma JSON y NaN ennull. Un payload de más de 64 KiB se convierte en{"lyrelog_truncated": true, "bytes": N, "preview": "..."}con su primer KiB. Los atributos de un evento tienen un tope de 256 KiB codificados, y un evento que no cabe en un lote de 512 KiB se descarta y se cuenta. - Al imprimir un
Configo un*Clientconfmt, la clave de API queda oculta.