Acceso anticipadoSolo por invitación, y los SDK aún no están publicados.Pedir una invitación
Ir al contenido
Docs

Go

Logs estructurados desde tus servicios Go, con un handler de log/slog. Solo la biblioteca estándar.

Servidores, con un handler de slog

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

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

Un 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 category en el nivel superior define el área (y no se envía como atributo); sin él se usa el Category del handler.
  • Niveles: Debug-4 y por debajo es trace, Debug es debug, Info es info, entre Info y Warn es notice, Warn es warning, Error es error, Error+4 y por encima es critical.
  • SlogOptions.Level añade un mínimo encima del del cliente; AddSource añade un atributo source con la función, el archivo y la línea de quien llama. Compila con go build -trimpath para 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.

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 stop

Flush envía todo lo que estaba en cola antes de la llamada y espera a que termine o a ctx. Devuelve:

  • nil cuando todo llegó al servidor;
  • ctx.Err() si el contexto terminó antes;
  • ErrUnauthorized tras un 401 o un 403 (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-After que haya pedido el servidor, Flush devuelve esto al instante y no envía nada;
  • ErrClosed después de Close.

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

CampoPredeterminadoSignificado
Endpointhttps://ingest.lyrelog.comLa URL base; si pegas una ruta /v1/..., se elimina. http:// sin cifrar solo para localhost
APIKeyobligatorioLa clave de servidor del proyecto (lyr_srv_...) o una clave de ingesta
Environment$LYRELOG_ENVIRONMENT o, si no, productionCualquier nombre válido
Platformgoapi, worker...
Releasela versión del móduloSe envía como resource.app_version
AppIDla ruta del móduloSe envía como resource.app_id
MinimumLevelLevelDebugLos eventos por debajo se descartan antes de entrar en la cola
FlushInterval5 sCada cuánto envía la goroutine en segundo plano
MaxQueue10.000Por encima, se descartan los más antiguos y se cuentan en Stats().Dropped
MaxQueueBytes16 MiBEl mismo tope, en bytes
CloseTimeout5 sCuánto espera Close al último envío
HTTPClienttimeout de 30 sEl cliente que envía los lotes. Nunca se siguen redirecciones, ni siquiera con tu propio cliente
ErrorLogstderr, una vezRecibe 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, apikey y 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.RedactKeys sustituye 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, hasta MaxQueue. El cliente registra un aviso en ErrorLog (o en stderr) y no dice nada más hasta que se acepte un lote.
  • Contexto: os_name es runtime.GOOS, app_build es 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.status pasa a http_status), los errores, las horas, las duraciones y los Stringer se convierten en cadenas, los structs en su forma JSON y NaN en null. 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 Config o un *Client con fmt, la clave de API queda oculta.