Búsqueda, ripgrep y jq para Depuración

Q: ¿Puede ripgrep reemplazar a find para archivos Go?

rg --files -g '*.go' lista rutas; combínalo con fzf para selectores interactivos. Usa find cuando metadatos como mtime sean importantes.

Q: ¿Qué pasa si los logs usan logfmt en lugar de JSON?

rg todavía encuentra claves; jq no se aplica. Considera mlog, lnav, o convertir una porción a JSON en un pequeño script Go.

Q: ¿Es lento contar con jq?

Contar en streaming con jq -c 'select(...)' | wc -l se mantiene O(n) en memoria. Evita -s en archivos de gigabytes.

Q: ¿Cómo comparto una receta de búsqueda con mi equipo?

Registra un fragmento de shell en scripts/debug/ o documenta one-liners en el runbook junto a los enlaces del dashboard.

Q: ¿Puedo usar ripgrep dentro de docker?

Sí, si la imagen incluye rg, o docker exec a un sidecar de depuración. Las imágenes de tiempo de ejecución Distroless a menudo carecen de herramientas de shell - extrae los logs en su lugar.

Q: ¿Cómo encuentro todos los TODOs en código Go?

rg -n "TODO\(|FIXME" --glob '.go' con opcional -g '!vendor/*'.

Usa ripgrep para buscar símbolos en módulos Go y jq para segmentar logs JSON en respuestas durante incidentes.

Resumen

Depurar servicios Go significa buscar en dos pajares: el código fuente en git y las líneas JSON en disco o en exportaciones de journal.

rg reemplaza al lento grep recursivo para código.

jq convierte logs estructurados en filtros, conteos y extracciones de campos sin una plataforma de logs completa.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

# Código: encontrar registro de manejador
rg -n "HandleFunc|Handle\(" --glob '*.go' internal/ cmd/
 
# Código: pruebas que referencian una función inestable
rg -n "TestProcessOrder" -g '*_test.go'
 
# Logs: errores en la última exportación
jq -c 'select(.level=="error")' app.json.log | head
 
# Logs: contar por prefijo de trace_id
jq -r 'select(.level=="error") | .trace_id' app.json.log | cut -c1-8 | sort | uniq -c | sort -nr

Cuándo usar esto:

Necesitas cada sitio de llamada de una función obsoleta antes de refactorizar.
Los logs de producción son JSON y necesitas aislar rápidamente un request_id.
CI guardó un artefacto de log y estás buscando fallos sin conexión.

Ejemplo de Trabajo

#!/usr/bin/env bash
set -euo pipefail
 
# --- Búsqueda en el repositorio ---
# Encuentra dónde se ignora la cancelación de contexto en los manejadores
rg -n "context\.Background\(\)" --glob '*.go' -g '!*_test.go' internal/
 
# Encuentra tags de compilación o archivos de plataforma
rg -n "//go:build" --glob '*.go'
 
# --- Análisis de logs (archivo de muestra NDJSON) ---
cat > /tmp/sample.json.log <<'EOF'
{"time":"2026-07-15T10:00:01Z","level":"info","msg":"start","service":"api","trace_id":"abc123"}
{"time":"2026-07-15T10:00:02Z","level":"error","msg":"db timeout","service":"api","trace_id":"abc123","err":"context deadline"}
{"time":"2026-07-15T10:00:03Z","level":"error","msg":"db timeout","service":"api","trace_id":"def456","err":"context deadline"}
EOF
 
# Todos los errores para una traza
jq -c 'select(.trace_id=="abc123")' /tmp/sample.json.log
 
# Mensajes de error principales
jq -r 'select(.level=="error") | .msg' /tmp/sample.json.log | sort | uniq -c | sort -nr
 
# Combina rg en una exportación de journal
journalctl -u api.service --since today --no-pager -o cat > /tmp/api.today.log
rg '"level":"error"' /tmp/api.today.log | jq -c . | head

Lo que esto demuestra:

ripgrep con ámbito con globs y archivos de prueba negados.
Filtros jq en NDJSON (un objeto JSON por línea).
Agregaciones con herramientas Unix después de que jq -r extrae un campo.
Flujo de trabajo híbrido cuando la salida del journal es JSON por línea.

Inmersión Profunda

Cómo Funciona

ripgrep recorre el sistema de archivos con motores regex en paralelo, omite archivos binarios y respeta .gitignore a menos que pases --no-ignore.
jq analiza valores JSON; filtros (select), proyecciones (.field) y slurp (-s) remodelan flujos para pipes de shell.
El logging estructurado de Go (slog, zap, zerolog) típicamente emite NDJSON o logfmt; NDJSON es compatible con jq cuando cada línea es JSON válido.
Las tuberías permanecen en el shell: exporta logs, busca, cuenta, y luego salta al código con rg en el manejador nombrado en el msg del log.

Flags de ripgrep que Vale la Pena Conocer

Flag	Efecto
`-n`	Números de línea
`-l`	Solo archivos con coincidencias
`-g '*.go'`	Filtro Glob (repetible)
`-g '!vendor/**'`	Excluir rutas
`-F`	Cadena fija (agujas en el log)
`-C 3`	Líneas de contexto
`--type go`	Filtro de tipo incorporado

Patrones jq para Logs

Tarea	jq
Filtrar nivel	`select(.level=="error")`
Campo existe	`select(has("trace_id"))`
Extraer campo	`.trace_id` con `-r`
Ventana de tiempo	`select(.time >= "2026-07-15T10:00:00Z")`
Estadísticas de array	`jq -s 'map(select(.level=="error"))

Notas de Go

// Prefiere nombres de campo estables para filtros jq
slog.Error("db timeout",
    "level", "error", // redundante si el manejador establece el nivel - sé consistente
    "trace_id", traceID,
    "err", err.Error(),
)

Alinea los nombres de clave con los dashboards (trace_id vs traceId) para evitar recetas jq duplicadas.

Trampas Comunes

jq en líneas no JSON - Stack traces y logs printf rompen los analizadores jq. Solución: Filtra primero con rg, o usa jq -R 'fromjson? | select(.)' para omitir líneas incorrectas.
ripgrep buscando en vendor - --no-ignore escanea dependencias empaquetadas. Solución: Ignorar por defecto, o -g '!vendor/**'.
Cadenas de nivel sensibles a mayúsculas/minúsculas - ERROR vs error omite filas. Solución: Normaliza en la configuración de logging de Go; usa jq ascii_downcase si los logs heredados varían.
Enorme carga de logs con jq -s - Carga el archivo completo en memoria. Solución: Transmite filtros línea por línea para archivos de GB.
Metacaracteres regex en rg - Puntos en err.context deadline necesitan -F o escape. Solución: rg -F 'context deadline'.
Registrar PII en pipelines de jq - Extraer correos de usuario en el historial del shell es arriesgado. Solución: Redacta en la ingesta; trabaja con exportaciones saneadas en incidentes.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
Búsqueda global del IDE	Navegación de módulo único con clic para abrir	Sesión SSH remota sin IDE
`git grep`	Historial limitado a archivos rastreados	Logs generados no rastreados o directorios grandes ignorados
Loki / Elasticsearch	Consultas históricas de todo el equipo	Solo tienes un archivo de 50 MB y cinco minutos
`ack` / `ag`	Laptops heredadas sin `rg`	Proyecto nuevo - instala ripgrep en su lugar
`mlog` / herramienta Go personalizada	Formato de log propietario	JSON estándar ya funciona con jq

Preguntas Frecuentes

¿Por qué ripgrep sobre git grep?

ripgrep respeta gitignore por defecto, busca árboles no rastreados cuando es necesario y es más rápido en monorepos grandes.

git grep está bien para búsquedas rápidas solo de historial.

¿jq requiere un objeto JSON por línea?

Esa forma NDJSON es el caso común para archivos de log.

JSON bonito multilínea necesita un análisis diferente o jq -s para archivos pequeños.

¿Cómo busco salida de zap o zerolog?

Si las claves JSON coinciden con tus filtros, las mismas recetas jq se aplican.

Para logs codificados en consola, cambia a codificación JSON en staging antes de los incidentes.

¿Puede ripgrep reemplazar a find para archivos Go?

rg --files -g '*.go' lista rutas; combínalo con fzf para selectores interactivos.

Usa find cuando metadatos como mtime sean importantes.

¿Cómo depuro panics de Go multilínea en logs?

Los panics suelen ser texto plano multilínea.

Usa el modo multilínea rg -U o lee entradas de journal como unidades a través de journalctl -o json.

¿Qué pasa si los logs usan logfmt en lugar de JSON?

rg todavía encuentra claves; jq no se aplica.

Considera mlog, lnav, o convertir una porción a JSON en un pequeño script Go.

¿Es lento contar con jq?

Contar en streaming con jq -c 'select(...)' | wc -l se mantiene O(n) en memoria.

Evita -s en archivos de gigabytes.

¿Cómo comparto una receta de búsqueda con mi equipo?

Registra un fragmento de shell en scripts/debug/ o documenta one-liners en el runbook junto a los enlaces del dashboard.

¿Puedo usar ripgrep dentro de docker?

Sí, si la imagen incluye rg, o docker exec a un sidecar de depuración.

Las imágenes de tiempo de ejecución Distroless a menudo carecen de herramientas de shell - extrae los logs en su lugar.

¿Cómo encuentro todos los TODOs en código Go?

rg -n "TODO\(|FIXME" --glob '*.go' con opcional -g '!vendor/**'.

¿jq soporta cadenas de duración de Go?

jq no analiza el formato de duración de Go de forma nativa.

Extrae el campo de cadena e interprétalo en Go o conviértelo en el momento de la emisión del log a milisegundos numéricos.

¿Qué pasa con los datos sensibles en el historial del shell?

Usa comandos prefijados con espacio donde HISTCONTROL los ignore, o ejecuta recetas desde scripts que lean archivos en lugar de IDs de cliente en línea.

Relacionados

Conceptos Básicos de la CLI de Linux - introducción a tail y jq
Compilar, Probar y Perfilar desde el Shell - búsqueda de salida de pruebas
Habilidades de CLI de Linux para Ingenieros Go - flujo de triaje de logs
Productividad del Shell: tmux, fzf y direnv - integración de fzf + rg
Observabilidad - logging estructurado en Go

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

Resumen

Depurar servicios Go significa buscar en dos pajares: el código fuente en git y las líneas JSON en disco o en exportaciones de journal.

rg reemplaza al lento grep recursivo para código.

jq convierte logs estructurados en filtros, conteos y extracciones de campos sin una plataforma de logs completa.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

# Código: encontrar registro de manejador
rg -n "HandleFunc|Handle\(" --glob '*.go' internal/ cmd/
 
# Código: pruebas que referencian una función inestable
rg -n "TestProcessOrder" -g '*_test.go'
 
# Logs: errores en la última exportación
jq -c 'select(.level=="error")' app.json.log | head
 
# Logs: contar por prefijo de trace_id
jq -r 'select(.level=="error") | .trace_id' app.json.log | cut -c1-8 | sort | uniq -c | sort -nr

Cuándo usar esto:

Necesitas cada sitio de llamada de una función obsoleta antes de refactorizar.
Los logs de producción son JSON y necesitas aislar rápidamente un request_id.
CI guardó un artefacto de log y estás buscando fallos sin conexión.

Ejemplo de Trabajo

#!/usr/bin/env bash
set -euo pipefail
 
# --- Búsqueda en el repositorio ---
# Encuentra dónde se ignora la cancelación de contexto en los manejadores
rg -n "context\.Background\(\)" --glob '*.go' -g '!*_test.go' internal/
 
# Encuentra tags de compilación o archivos de plataforma
rg -n "//go:build" --glob '*.go'
 
# --- Análisis de logs (archivo de muestra NDJSON) ---
cat > /tmp/sample.json.log <<'EOF'
{"time":"2026-07-15T10:00:01Z","level":"info","msg":"start","service":"api","trace_id":"abc123"}
{"time":"2026-07-15T10:00:02Z","level":"error","msg":"db timeout","service":"api","trace_id":"abc123","err":"context deadline"}
{"time":"2026-07-15T10:00:03Z","level":"error","msg":"db timeout","service":"api","trace_id":"def456","err":"context deadline"}
EOF
 
# Todos los errores para una traza
jq -c 'select(.trace_id=="abc123")' /tmp/sample.json.log
 
# Mensajes de error principales
jq -r 'select(.level=="error") | .msg' /tmp/sample.json.log | sort | uniq -c | sort -nr
 
# Combina rg en una exportación de journal
journalctl -u api.service --since today --no-pager -o cat > /tmp/api.today.log
rg '"level":"error"' /tmp/api.today.log | jq -c . | head

Lo que esto demuestra:

ripgrep con ámbito con globs y archivos de prueba negados.
Filtros jq en NDJSON (un objeto JSON por línea).
Agregaciones con herramientas Unix después de que jq -r extrae un campo.
Flujo de trabajo híbrido cuando la salida del journal es JSON por línea.

Inmersión Profunda

Cómo Funciona

ripgrep recorre el sistema de archivos con motores regex en paralelo, omite archivos binarios y respeta .gitignore a menos que pases --no-ignore.
jq analiza valores JSON; filtros (select), proyecciones (.field) y slurp (-s) remodelan flujos para pipes de shell.
El logging estructurado de Go (slog, zap, zerolog) típicamente emite NDJSON o logfmt; NDJSON es compatible con jq cuando cada línea es JSON válido.
Las tuberías permanecen en el shell: exporta logs, busca, cuenta, y luego salta al código con rg en el manejador nombrado en el msg del log.

Flags de ripgrep que Vale la Pena Conocer

Flag	Efecto
`-n`	Números de línea
`-l`	Solo archivos con coincidencias
`-g '*.go'`	Filtro Glob (repetible)
`-g '!vendor/**'`	Excluir rutas
`-F`	Cadena fija (agujas en el log)
`-C 3`	Líneas de contexto
`--type go`	Filtro de tipo incorporado

Patrones jq para Logs

Tarea	jq
Filtrar nivel	`select(.level=="error")`
Campo existe	`select(has("trace_id"))`
Extraer campo	`.trace_id` con `-r`
Ventana de tiempo	`select(.time >= "2026-07-15T10:00:00Z")`
Estadísticas de array	`jq -s 'map(select(.level=="error"))

Notas de Go

// Prefiere nombres de campo estables para filtros jq
slog.Error("db timeout",
    "level", "error", // redundante si el manejador establece el nivel - sé consistente
    "trace_id", traceID,
    "err", err.Error(),
)

Alinea los nombres de clave con los dashboards (trace_id vs traceId) para evitar recetas jq duplicadas.

Trampas Comunes

jq en líneas no JSON - Stack traces y logs printf rompen los analizadores jq. Solución: Filtra primero con rg, o usa jq -R 'fromjson? | select(.)' para omitir líneas incorrectas.
ripgrep buscando en vendor - --no-ignore escanea dependencias empaquetadas. Solución: Ignorar por defecto, o -g '!vendor/**'.
Cadenas de nivel sensibles a mayúsculas/minúsculas - ERROR vs error omite filas. Solución: Normaliza en la configuración de logging de Go; usa jq ascii_downcase si los logs heredados varían.
Enorme carga de logs con jq -s - Carga el archivo completo en memoria. Solución: Transmite filtros línea por línea para archivos de GB.
Metacaracteres regex en rg - Puntos en err.context deadline necesitan -F o escape. Solución: rg -F 'context deadline'.
Registrar PII en pipelines de jq - Extraer correos de usuario en el historial del shell es arriesgado. Solución: Redacta en la ingesta; trabaja con exportaciones saneadas en incidentes.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
Búsqueda global del IDE	Navegación de módulo único con clic para abrir	Sesión SSH remota sin IDE
`git grep`	Historial limitado a archivos rastreados	Logs generados no rastreados o directorios grandes ignorados
Loki / Elasticsearch	Consultas históricas de todo el equipo	Solo tienes un archivo de 50 MB y cinco minutos
`ack` / `ag`	Laptops heredadas sin `rg`	Proyecto nuevo - instala ripgrep en su lugar
`mlog` / herramienta Go personalizada	Formato de log propietario	JSON estándar ya funciona con jq

Preguntas Frecuentes

¿Por qué ripgrep sobre git grep?

ripgrep respeta gitignore por defecto, busca árboles no rastreados cuando es necesario y es más rápido en monorepos grandes.

git grep está bien para búsquedas rápidas solo de historial.

¿jq requiere un objeto JSON por línea?

Esa forma NDJSON es el caso común para archivos de log.

JSON bonito multilínea necesita un análisis diferente o jq -s para archivos pequeños.

¿Cómo busco salida de zap o zerolog?

Si las claves JSON coinciden con tus filtros, las mismas recetas jq se aplican.

Para logs codificados en consola, cambia a codificación JSON en staging antes de los incidentes.

¿Puede ripgrep reemplazar a find para archivos Go?

rg --files -g '*.go' lista rutas; combínalo con fzf para selectores interactivos.

Usa find cuando metadatos como mtime sean importantes.

¿Cómo depuro panics de Go multilínea en logs?

Los panics suelen ser texto plano multilínea.

Usa el modo multilínea rg -U o lee entradas de journal como unidades a través de journalctl -o json.

¿Qué pasa si los logs usan logfmt en lugar de JSON?

rg todavía encuentra claves; jq no se aplica.

Considera mlog, lnav, o convertir una porción a JSON en un pequeño script Go.

¿Es lento contar con jq?

Contar en streaming con jq -c 'select(...)' | wc -l se mantiene O(n) en memoria.

Evita -s en archivos de gigabytes.

¿Cómo comparto una receta de búsqueda con mi equipo?

Registra un fragmento de shell en scripts/debug/ o documenta one-liners en el runbook junto a los enlaces del dashboard.

¿Puedo usar ripgrep dentro de docker?

Sí, si la imagen incluye rg, o docker exec a un sidecar de depuración.

Las imágenes de tiempo de ejecución Distroless a menudo carecen de herramientas de shell - extrae los logs en su lugar.

¿Cómo encuentro todos los TODOs en código Go?

rg -n "TODO\(|FIXME" --glob '*.go' con opcional -g '!vendor/**'.

¿jq soporta cadenas de duración de Go?

jq no analiza el formato de duración de Go de forma nativa.

Extrae el campo de cadena e interprétalo en Go o conviértelo en el momento de la emisión del log a milisegundos numéricos.

¿Qué pasa con los datos sensibles en el historial del shell?

Usa comandos prefijados con espacio donde HISTCONTROL los ignore, o ejecuta recetas desde scripts que lean archivos en lugar de IDs de cliente en línea.

Relacionados

Conceptos Básicos de la CLI de Linux - introducción a tail y jq
Compilar, Probar y Perfilar desde el Shell - búsqueda de salida de pruebas
Habilidades de CLI de Linux para Ingenieros Go - flujo de triaje de logs
Productividad del Shell: tmux, fzf y direnv - integración de fzf + rg
Observabilidad - logging estructurado en Go

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

Búsqueda, ripgrep y jq para Depuración

Buscar en la documentación

Búsqueda, ripgrep y jq para Depuración