Busca, ripgrep & jq para Depuração

Q: ripgrep pode substituir find para arquivos Go?

rg --files -g '*.go' lista caminhos; combine com fzf para seletores interativos. Use find quando metadados como mtime forem importantes.

Q: E se os logs usarem logfmt em vez de JSON?

rg ainda encontra chaves; jq não se aplica. Considere mlog, lnav, ou converter uma fatia para JSON em um pequeno script Go.

Q: Contar com jq é lento?

Contagens de streaming com jq -c 'select(...)' | wc -l permanecem O(n) em memória. Evite -s em arquivos de gigabytes.

Q: Como compartilho uma receita de busca com minha equipe?

Armazene um snippet de shell em scripts/debug/ ou documente one-liners no runbook ao lado de links de dashboard.

Q: Posso usar ripgrep dentro do docker?

Sim, se a imagem incluir rg, ou docker exec em um sidecar de depuração. Imagens de runtime Distroless geralmente não possuem ferramentas de shell - copie os logs para fora em vez disso.

Q: Como encontro todos os TODOs em código Go?

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

Use ripgrep para caçar símbolos em módulos Go e jq para fatiar logs JSON em respostas durante incidentes.

Resumo

Depurar serviços Go significa procurar em dois palheiros: código-fonte no git e linhas JSON em disco ou em exportações do journal.

rg substitui o lento grep recursivo para código.

jq transforma logs estruturados em filtros, contagens e extrações de campos sem uma plataforma de logs completa.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Código: encontrar registro de handler
rg -n "HandleFunc|Handle\(" --glob '*.go' internal/ cmd/
 
# Código: testes referenciando uma função instável
rg -n "TestProcessOrder" -g '*_test.go'
 
# Logs: erros na última exportação
jq -c 'select(.level=="error")' app.json.log | head
 
# Logs: contagem por prefixo de trace_id
jq -r 'select(.level=="error") | .trace_id' app.json.log | cut -c1-8 | sort | uniq -c | sort -nr

Quando usar isso:

Você precisa de todos os sites de chamada de uma função depreciada antes de refatorar.
Logs de produção são JSON e você precisa isolar um request_id rapidamente.
CI salvou um artefato de log e você está buscando falhas offline.

Exemplo de Trabalho

#!/usr/bin/env bash
set -euo pipefail
 
# --- Busca no Repositório ---
# Encontrar onde o cancelamento de contexto é ignorado em handlers
rg -n "context\.Background\(\)" --glob '*.go' -g '!*_test.go' internal/
 
# Encontrar tags de build ou arquivos de plataforma
rg -n "//go:build" --glob '*.go'
 
# --- Análise de Logs (arquivo NDJSON de exemplo) ---
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 os erros para um trace
jq -c 'select(.trace_id=="abc123")' /tmp/sample.json.log
 
# Principais mensagens de erro
jq -r 'select(.level=="error") | .msg' /tmp/sample.json.log | sort | uniq -c | sort -nr
 
# Combinar rg em uma exportação do 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

O que isso demonstra:

ripgrep com escopo usando globs e arquivos de teste negados.
Filtros jq em NDJSON (um objeto JSON por linha).
Agregações com ferramentas Unix após jq -r extrair um campo.
Fluxo de trabalho híbrido quando a saída do journal é JSON por linha.

Mergulho Profundo

Como Funciona

ripgrep percorre o sistema de arquivos com motores regex em paralelo, ignora arquivos binários e respeita .gitignore, a menos que você passe --no-ignore.
jq analisa valores JSON; filtros (select), projeções (.field) e slurp (-s) remodelam fluxos para pipes do shell.
Logging estruturado Go (slog, zap, zerolog) geralmente emite NDJSON ou logfmt; NDJSON é amigável ao jq quando cada linha é um JSON válido.
Pipelines permanecem no shell: exportar logs, buscar, contar e, em seguida, pular para o código com rg no handler nomeado na msg do log.

Sinalizadores do ripgrep que valem a pena conhecer

Sinalizador	Efeito
`-n`	Números de linha
`-l`	Apenas arquivos com correspondências
`-g '*.go'`	Filtro Glob (repetível)
`-g '!vendor/**'`	Excluir caminhos
`-F`	String fixa (agulhas de log)
`-C 3`	Linhas de contexto
`--type go`	Filtro de tipo embutido

Padrões jq para Logs

Tarefa	jq
Filtrar nível	`select(.level=="error")`
Campo existe	`select(has("trace_id"))`
Extrair campo	`.trace_id` com `-r`
Janela de tempo	`select(.time >= "2026-07-15T10:00:00Z")`
Estatísticas de array	`jq -s 'map(select(.level=="error"))

Notas Go

// Prefira nomes de campos estáveis para filtros jq
slog.Error("db timeout",
    "level", "error", // redundante se o handler definir o nível - seja consistente
    "trace_id", traceID,
    "err", err.Error(),
)

Alinhe nomes de chaves com dashboards (trace_id vs traceId) para evitar receitas jq duplicadas.

Armadilhas

jq em linhas não JSON - Traces de pilha e logs printf quebram os parsers jq. Correção: filtre primeiro com rg, ou use jq -R 'fromjson? | select(.)' para pular linhas ruins.
ripgrep buscando vendor - --no-ignore escaneia dependências vendidas. Correção: ignore padrão, ou -g '!vendor/**'.
Strings de nível sensíveis a maiúsculas/minúsculas - ERROR vs error perde linhas. Correção: normalize na configuração de logging Go; use jq ascii_downcase se logs legados variarem.
Grande slurp de log com jq -s - Carrega o arquivo inteiro na memória. Correção: transmita filtros linha por linha para arquivos de GB.
Metacaracteres Regex em rg - Pontos em err.context deadline precisam de -F ou escape. Correção: rg -F 'context deadline'.
Logging de PII em pipelines de shell - Extrair emails de usuários no histórico do shell é arriscado. Correção: redija na ingestão; trabalhe em exportações higienizadas em incidentes.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Busca global do IDE	Navegação em um único módulo com clique para abrir	Sessão SSH remota sem IDE
`git grep`	Histórico limitado a arquivos rastreados	Logs gerados não rastreados ou diretórios ignorados grandes
Loki / Elasticsearch	Consultas históricas para toda a equipe	Você tem apenas um arquivo de 50MB e cinco minutos
`ack` / `ag`	Laptops legados sem `rg`	Greenfield - instale ripgrep em vez disso
`mlog` / ferramenta Go personalizada	Formato de log proprietário	JSON padrão já funciona com jq

FAQs

Por que ripgrep em vez de git grep?

ripgrep respeita gitignore por padrão, busca árvores não rastreadas quando necessário e é mais rápido em monorepos grandes.

git grep é bom para buscas rápidas apenas no histórico.

jq requer um objeto JSON por linha?

Essa forma NDJSON é o caso comum para arquivos de log.

JSON bonito de várias linhas precisa de análise diferente ou jq -s para arquivos pequenos.

Como busco a saída de zap ou zerolog?

Se as chaves JSON corresponderem aos seus filtros, as mesmas receitas jq se aplicam.

Para logs codificados no console, mude para codificação JSON em staging antes de incidentes.

ripgrep pode substituir find para arquivos Go?

rg --files -g '*.go' lista caminhos; combine com fzf para seletores interativos.

Use find quando metadados como mtime forem importantes.

Como depuro panics Go multilinhas em logs?

Panics são frequentemente texto simples multilinhas.

Use o modo multilinhas rg -U ou leia entradas do journal como unidades via journalctl -o json.

E se os logs usarem logfmt em vez de JSON?

rg ainda encontra chaves; jq não se aplica.

Considere mlog, lnav, ou converter uma fatia para JSON em um pequeno script Go.

Contar com jq é lento?

Contagens de streaming com jq -c 'select(...)' | wc -l permanecem O(n) em memória.

Evite -s em arquivos de gigabytes.

Como compartilho uma receita de busca com minha equipe?

Armazene um snippet de shell em scripts/debug/ ou documente one-liners no runbook ao lado de links de dashboard.

Posso usar ripgrep dentro do docker?

Sim, se a imagem incluir rg, ou docker exec em um sidecar de depuração.

Imagens de runtime Distroless geralmente não possuem ferramentas de shell - copie os logs para fora em vez disso.

Como encontro todos os TODOs em código Go?

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

jq suporta strings de duração Go?

jq não analisa o formato de duração do Go nativamente.

Extraia o campo string e interprete em Go ou converta no momento da emissão do log para milissegundos numéricos.

E sobre dados sensíveis no histórico do shell?

Use comandos com espaço inicial onde HISTCONTROL os ignora, ou execute receitas de scripts que leiam arquivos em vez de IDs de clientes inline.

Relacionados

Noções Básicas do CLI Linux - introdução a tail e jq
Construir, Testar e Perfilamento a partir do Shell - buscando saída de teste
Habilidades de CLI Linux para Engenheiros Go - fluxo de triagem de logs
Produtividade do Shell: tmux, fzf & direnv - integração fzf + rg
Observabilidade - logging estruturado em Go

Versões de Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verifique o patch na compilação), chi (última - verifique na compilação), gin (última - verifique na compilação), echo (última - verifique na compilação), google.golang.org/grpc (última - verifique na compilação), sigs.k8s.io/controller-runtime (última - verifique na compilação), kubebuilder (última - verifique na compilação), tinygo (última - verifique os alvos de placa na compilação), wazero (última - verifique na compilação) e golangci-lint (última - verifique o conjunto de linters na compilação).

Resumo

Depurar serviços Go significa procurar em dois palheiros: código-fonte no git e linhas JSON em disco ou em exportações do journal.

rg substitui o lento grep recursivo para código.

jq transforma logs estruturados em filtros, contagens e extrações de campos sem uma plataforma de logs completa.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Código: encontrar registro de handler
rg -n "HandleFunc|Handle\(" --glob '*.go' internal/ cmd/
 
# Código: testes referenciando uma função instável
rg -n "TestProcessOrder" -g '*_test.go'
 
# Logs: erros na última exportação
jq -c 'select(.level=="error")' app.json.log | head
 
# Logs: contagem por prefixo de trace_id
jq -r 'select(.level=="error") | .trace_id' app.json.log | cut -c1-8 | sort | uniq -c | sort -nr

Quando usar isso:

Você precisa de todos os sites de chamada de uma função depreciada antes de refatorar.
Logs de produção são JSON e você precisa isolar um request_id rapidamente.
CI salvou um artefato de log e você está buscando falhas offline.

Exemplo de Trabalho

#!/usr/bin/env bash
set -euo pipefail
 
# --- Busca no Repositório ---
# Encontrar onde o cancelamento de contexto é ignorado em handlers
rg -n "context\.Background\(\)" --glob '*.go' -g '!*_test.go' internal/
 
# Encontrar tags de build ou arquivos de plataforma
rg -n "//go:build" --glob '*.go'
 
# --- Análise de Logs (arquivo NDJSON de exemplo) ---
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 os erros para um trace
jq -c 'select(.trace_id=="abc123")' /tmp/sample.json.log
 
# Principais mensagens de erro
jq -r 'select(.level=="error") | .msg' /tmp/sample.json.log | sort | uniq -c | sort -nr
 
# Combinar rg em uma exportação do 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

O que isso demonstra:

ripgrep com escopo usando globs e arquivos de teste negados.
Filtros jq em NDJSON (um objeto JSON por linha).
Agregações com ferramentas Unix após jq -r extrair um campo.
Fluxo de trabalho híbrido quando a saída do journal é JSON por linha.

Mergulho Profundo

Como Funciona

ripgrep percorre o sistema de arquivos com motores regex em paralelo, ignora arquivos binários e respeita .gitignore, a menos que você passe --no-ignore.
jq analisa valores JSON; filtros (select), projeções (.field) e slurp (-s) remodelam fluxos para pipes do shell.
Logging estruturado Go (slog, zap, zerolog) geralmente emite NDJSON ou logfmt; NDJSON é amigável ao jq quando cada linha é um JSON válido.
Pipelines permanecem no shell: exportar logs, buscar, contar e, em seguida, pular para o código com rg no handler nomeado na msg do log.

Sinalizadores do ripgrep que valem a pena conhecer

Sinalizador	Efeito
`-n`	Números de linha
`-l`	Apenas arquivos com correspondências
`-g '*.go'`	Filtro Glob (repetível)
`-g '!vendor/**'`	Excluir caminhos
`-F`	String fixa (agulhas de log)
`-C 3`	Linhas de contexto
`--type go`	Filtro de tipo embutido

Padrões jq para Logs

Tarefa	jq
Filtrar nível	`select(.level=="error")`
Campo existe	`select(has("trace_id"))`
Extrair campo	`.trace_id` com `-r`
Janela de tempo	`select(.time >= "2026-07-15T10:00:00Z")`
Estatísticas de array	`jq -s 'map(select(.level=="error"))

Notas Go

// Prefira nomes de campos estáveis para filtros jq
slog.Error("db timeout",
    "level", "error", // redundante se o handler definir o nível - seja consistente
    "trace_id", traceID,
    "err", err.Error(),
)

Alinhe nomes de chaves com dashboards (trace_id vs traceId) para evitar receitas jq duplicadas.

Armadilhas

jq em linhas não JSON - Traces de pilha e logs printf quebram os parsers jq. Correção: filtre primeiro com rg, ou use jq -R 'fromjson? | select(.)' para pular linhas ruins.
ripgrep buscando vendor - --no-ignore escaneia dependências vendidas. Correção: ignore padrão, ou -g '!vendor/**'.
Strings de nível sensíveis a maiúsculas/minúsculas - ERROR vs error perde linhas. Correção: normalize na configuração de logging Go; use jq ascii_downcase se logs legados variarem.
Grande slurp de log com jq -s - Carrega o arquivo inteiro na memória. Correção: transmita filtros linha por linha para arquivos de GB.
Metacaracteres Regex em rg - Pontos em err.context deadline precisam de -F ou escape. Correção: rg -F 'context deadline'.
Logging de PII em pipelines de shell - Extrair emails de usuários no histórico do shell é arriscado. Correção: redija na ingestão; trabalhe em exportações higienizadas em incidentes.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Busca global do IDE	Navegação em um único módulo com clique para abrir	Sessão SSH remota sem IDE
`git grep`	Histórico limitado a arquivos rastreados	Logs gerados não rastreados ou diretórios ignorados grandes
Loki / Elasticsearch	Consultas históricas para toda a equipe	Você tem apenas um arquivo de 50MB e cinco minutos
`ack` / `ag`	Laptops legados sem `rg`	Greenfield - instale ripgrep em vez disso
`mlog` / ferramenta Go personalizada	Formato de log proprietário	JSON padrão já funciona com jq

FAQs

Por que ripgrep em vez de git grep?

ripgrep respeita gitignore por padrão, busca árvores não rastreadas quando necessário e é mais rápido em monorepos grandes.

git grep é bom para buscas rápidas apenas no histórico.

jq requer um objeto JSON por linha?

Essa forma NDJSON é o caso comum para arquivos de log.

JSON bonito de várias linhas precisa de análise diferente ou jq -s para arquivos pequenos.

Como busco a saída de zap ou zerolog?

Se as chaves JSON corresponderem aos seus filtros, as mesmas receitas jq se aplicam.

Para logs codificados no console, mude para codificação JSON em staging antes de incidentes.

ripgrep pode substituir find para arquivos Go?

rg --files -g '*.go' lista caminhos; combine com fzf para seletores interativos.

Use find quando metadados como mtime forem importantes.

Como depuro panics Go multilinhas em logs?

Panics são frequentemente texto simples multilinhas.

Use o modo multilinhas rg -U ou leia entradas do journal como unidades via journalctl -o json.

E se os logs usarem logfmt em vez de JSON?

rg ainda encontra chaves; jq não se aplica.

Considere mlog, lnav, ou converter uma fatia para JSON em um pequeno script Go.

Contar com jq é lento?

Contagens de streaming com jq -c 'select(...)' | wc -l permanecem O(n) em memória.

Evite -s em arquivos de gigabytes.

Como compartilho uma receita de busca com minha equipe?

Armazene um snippet de shell em scripts/debug/ ou documente one-liners no runbook ao lado de links de dashboard.

Posso usar ripgrep dentro do docker?

Sim, se a imagem incluir rg, ou docker exec em um sidecar de depuração.

Imagens de runtime Distroless geralmente não possuem ferramentas de shell - copie os logs para fora em vez disso.

Como encontro todos os TODOs em código Go?

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

jq suporta strings de duração Go?

jq não analisa o formato de duração do Go nativamente.

Extraia o campo string e interprete em Go ou converta no momento da emissão do log para milissegundos numéricos.

E sobre dados sensíveis no histórico do shell?

Use comandos com espaço inicial onde HISTCONTROL os ignora, ou execute receitas de scripts que leiam arquivos em vez de IDs de clientes inline.

Relacionados

Noções Básicas do CLI Linux - introdução a tail e jq
Construir, Testar e Perfilamento a partir do Shell - buscando saída de teste
Habilidades de CLI Linux para Engenheiros Go - fluxo de triagem de logs
Produtividade do Shell: tmux, fzf & direnv - integração fzf + rg
Observabilidade - logging estruturado em Go

Versões de Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verifique o patch na compilação), chi (última - verifique na compilação), gin (última - verifique na compilação), echo (última - verifique na compilação), google.golang.org/grpc (última - verifique na compilação), sigs.k8s.io/controller-runtime (última - verifique na compilação), kubebuilder (última - verifique na compilação), tinygo (última - verifique os alvos de placa na compilação), wazero (última - verifique na compilação) e golangci-lint (última - verifique o conjunto de linters na compilação).

Busca, ripgrep & jq para Depuração

Buscar na documentação

Busca, ripgrep & jq para Depuração