Mejores Prácticas de Observabilidad

Los servicios Go en producción se mantienen depurables cuando los logs, métricas, trazas, sondas y el comportamiento de apagado siguen reglas compartidas que protegen a los ingenieros de guardia y los presupuestos de observabilidad.

Cómo Usar Esta Lista

• Adopte las reglas de Nivel A en las plantillas de servicio antes del primer despliegue en producción.
• Codifique las listas de permitidos de etiquetas y las rutas de sondas en las listas de verificación de revisión de código.
• Empareje las reglas de métricas con dashboards de Grafana y runbooks de alertas.
• Revise después de un crecimiento importante del tráfico o nuevas dependencias.

A - Logs y slog

• Emitir logs JSON en producción con un único manejador por defecto. Los agregadores indexan los campos de forma fiable; el texto es solo para desarrollo local.
• Incluir request_id y trace_id en cada línea de log con ámbito de solicitud. El personal de guardia puede saltar de una línea de log a una traza sin malabarismos con grep.
• Usar nombres de atributos estables entre servicios (err, http.route, user_id). Los esquemas consistentes hacen posibles las consultas entre servicios.
• Establecer el nivel de log desde el entorno; por defecto Info en producción. El volumen de depuración escala con QPS y aumenta el coste.
• Redactar secretos y tokens en un manejador personalizado o middleware. Las contraseñas nunca deben llegar al almacenamiento de logs.
• Registrar errores una vez en el límite con contexto envuelto. Evitar rastreos de pila duplicados en cada capa.

B - Métricas y cardinalidad

• Etiquetar métricas HTTP con plantillas de ruta, no con rutas crudas. /users/{id} previene series ilimitadas por IDs.
• Nunca poner IDs de usuario, correos electrónicos o IDs de pedido en etiquetas de Prometheus. Las explosiones de cardinalidad tiran abajo los backends de métricas.
• Registrar métricas una vez en main, no por solicitud. El registro duplicado causa pánicos y duplica series.
• Ajustar los buckets del histograma a los umbrales de SLO. Los buckets por defecto ocultan acantilados de latencia cerca de su objetivo p99.
• Exponer /metrics en un listener de administración o red restringida. El scrape público filtra detalles operativos internos.
• Excluir el tráfico de comprobación de estado de los gráficos RED o etiquetar probe=true. El QPS de las sondas distorsiona los agregados de tasa y duración.

C - Trazado y muestreo

• Propagar context.Context a través de manejadores HTTP, gRPC y llamadas a bases de datos. El contexto roto rompe los árboles de trazas.
• Usar ParentBased o muestreo de ratio en producción. El trazado completo con alto QPS abruma a los colectores.
• Registrar errores en los spans con span.RecordError. Las trazas fallidas deben permanecer visibles bajo muestreo.
• Llamar a TracerProvider.Shutdown al salir. Los spans en búfer se pierden con SIGKILL sin vaciado.
• Establecer service.name y atributos de recurso del entorno de despliegue. Los backends agrupan trazas por equipo y etapa.
• Crear spans en los límites de I/O, no en cada función auxiliar. El ruido oculta los spans que explican la latencia.

D - Salud, preparación y sondas

• Mantener la comprobación de vivacidad (liveness) barata, sin I/O externo. Las comprobaciones de dependencias pertenecen solo a la preparación (readiness).
• Devolver 503 en preparación cuando fallan las dependencias críticas. Los balanceadores de carga detienen el tráfico sin bucles de reinicio de pods.
• Incluir /healthz y /readyz en la lista de permitidos del middleware de autenticación. Las sondas de Kubelet no envían tokens de portador.
• Limitar las comprobaciones de preparación con tiempos de espera inferiores a un segundo. Las sondas lentas hacen fluctuar los endpoints durante interrupciones parciales.
• Retrasar la preparación hasta que terminen las migraciones y el calentamiento. El tráfico temprano causa errores de esquema y caché.
• Documentar el inicio, la preparación y la vivacidad en el README del servicio. Los nuevos operadores deben saber qué endpoint significa qué.

E - Apagado y ciclo de vida

• Manejar SIGTERM y llamar a http.Server.Shutdown con un contexto limitado. Los despliegues en rol drenan el trabajo en curso.
• Alinear el tiempo de espera de apagado con terminationGracePeriodSeconds de Kubernetes. Evitar SIGKILL a mitad de solicitud.
• Cancelar los contextos de los workers cuando comienza el drenaje HTTP. Los encuestadores en segundo plano no deben sobrevivir a la ventana de gracia.
• Establecer la preparación en falso antes de que comience el apagado. Detiene el nuevo tráfico mientras se completan las solicitudes activas.
• Registrar las fases de apagado: señal recibida, inicio de drenaje, completo. Los logs de despliegue se correlacionan con los errores dirigidos al usuario.
• Cerrar pools de bases de datos y vaciar exportadores después del drenaje HTTP. La telemetría y las conexiones no deben tener fugas al salir.

F - Configuración y operabilidad

• Validar las variables de entorno requeridas al inicio y salir con un código distinto de cero en caso de fallo. La mala configuración no debe convertirse en un pod en ejecución.
• Registrar una instantánea de configuración segura en Info al arrancar. Los operadores verifican el puerto, el entorno y las flags de características sin secretos.
• Inyectar estructuras de configuración; no leer os.Getenv en los manejadores. Las pruebas y la claridad se ven afectadas por el acceso oculto al entorno.
• Tratar los endpoints de observabilidad como parte del contrato público de operaciones. Documentar rutas, puertos e intervalos de scrape.
• Ejecutar go test con manejadores de prueba de slog para el middleware crítico. Las regresiones en el registro de solicitudes se detectan en CI.
• Revisar la observabilidad en cada postmortem de incidente. Las etiquetas o IDs faltantes se convierten en un elemento de acción rastreado.

Preguntas Frecuentes

Relacionados

• Producción Go: Logs, Métricas, Trazas y Señales - descripción general conceptual
• Registro Estructurado con slog - detalle de registro
• Métricas Prometheus y Dashboards RED/USE - métricas RED
• Trazado OpenTelemetry en Servicios Go - configuración de trazado
• Apagado Elegante y Manejo de Señales - patrones de drenaje
• Mejores Prácticas de net/http - reglas complementarias específicas de HTTP

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado GC Green Tea, go fix modernizers - verificar parche en la compilación), chi (última versión - verificar en la compilación), gin (última versión - verificar en la compilación), echo (última versión - verificar en la compilación), google.golang.org/grpc (última versión - verificar en la compilación), sigs.k8s.io/controller-runtime (última versión - verificar en la compilación), kubebuilder (última versión - verificar en la compilación), tinygo (última versión - verificar objetivos de placa en la compilación), wazero (última versión - verificar en la compilación) y golangci-lint (última versión - verificar conjunto de linters en la compilación).