Jamie-BitFlight/bash-logging

Bash Logging

Padrões estruturados de logging para scripts bash com suporte a cores, ícones emoji e integração com CI/CD.

Funções Básicas de Logging

Implementação simples e portável de logging:

# Definições de cores
declare -A colors=(
    [green]=$'\033[0;32m'
    [red]=$'\033[0;31m'
    [yellow]=$'\033[1;33m'
    [blue]=$'\033[0;34m'
    [reset]=$'\033[0m'
)

declare -A emojis=(
    [success]='✅'
    [error]='❌'
    [warning]='⚠️'
    [info]='ℹ️'
    [debug]='🐛'
)

# Funções de logging
print_success() {
    printf '%b %b%b%b\n' "${emojis[success]}" "${colors[green]}" "$*" "${colors[reset]}"
}

print_error() {
    printf '%b %b%b%b\n' "${emojis[error]}" "${colors[red]}" "$*" "${colors[reset]}" >&2
}

print_warning() {
    printf '%b %b%b%b\n' "${emojis[warning]}" "${colors[yellow]}" "$*" "${colors[reset]}"
}

print_info() {
    printf '%b %b\n' "${emojis[info]}" "$*"
}

print_debug() {
    [[ -n "${DEBUG:-}" ]] && printf '%b %b%b%b\n' "${emojis[debug]}" "${colors[blue]}" "$*" "${colors[reset]}"
}

Níveis de Log

Implementa níveis de log configuráveis.

Exemplos de código

Detecção de TTY

Desabilita cores em ambientes não interativos:

setup_colors() {
    if [[ -t 1 ]] && [[ -z "${NO_COLOR:-}" ]]; then
        # Terminal suporta cores
        COLOR_RED=$'\033[0;31m'
        COLOR_GREEN=$'\033[0;32m'
        COLOR_YELLOW=$'\033[1;33m'
        COLOR_BLUE=$'\033[0;34m'
        COLOR_RESET=$'\033[0m'
    else
        # Sem suporte a cores
        COLOR_RED=''
        COLOR_GREEN=''
        COLOR_YELLOW=''
        COLOR_BLUE=''
        COLOR_RESET=''
    fi
}

# Ambientes CI frequentemente suportam cores
detect_color_support() {
    if [[ -n "${CI:-}" ]] || [[ -n "${GITLAB_CI:-}" ]] || [[ -n "${GITHUB_ACTIONS:-}" ]]; then
        return 0  # Ambiente CI, habilita cores
    elif [[ -t 1 ]]; then
        return 0  # Terminal, habilita cores
    else
        return 1  # Sem suporte a cores
    fi
}

Seções Retráteis do GitLab CI

Cria seções de log retráteis no GitLab CI:

section_start() {
    local section_key="\${1:-section}"
    local section_header="\${2:-$section_key}"
    local collapsed="\${3:-true}"

    if [[ -n "${GITLAB_CI:-}" ]]; then
        printf "\e[0Ksection_start:%s:%s[collapsed=%s]\r\e[0K%s\n" \
            "$(date +%s)" "$section_key" "$collapsed" "$section_header"
    else
        printf '\n=== %s ===\n' "$section_header"
    fi
}

section_end() {
    local section_key="\${1:-section}"

    if [[ -n "${GITLAB_CI:-}" ]]; then
        printf "\e[0Ksection_end:%s:%s\r\e[0K" "$(date +%s)" "$section_key"
    else
        printf '\n'
    fi
}

# Uso
section_start "build" "Construindo Aplicação"
make build
section_end "build"

Agrupamento do GitHub Actions

Exemplos de código

Indicadores de Progresso

Exemplos de código

Logging Estruturado de Etapas

Exemplos de código

Biblioteca de Logging Shlocksmith

Para logging abrangente com integração total de CI, use a biblioteca de logging shlocksmith.

Recursos

• Mais de 20 funções de nível de log (log_info, log_error, log_warning, etc.)
• Logging baseado em etapas (log_step_start, log_step_pass, log_step_fail)
• Suporte a cores e emojis com detecção de TTY
• Gerenciamento de seções do GitLab CI
• Caracteres de desenho de caixa para TUI
• Formatação de pares chave-valor

Funções Disponíveis

# Logging básico
log_info "Mensagem informativa"
log_warning "Mensagem de aviso"
log_error "Mensagem de erro"
log_debug "Mensagem de depuração"  # Exibido apenas quando DEBUG está definido
log_notice "Mensagem de notificação"
log_fatal "Erro fatal"    # Encerra o script

# Logging baseado em etapas
log_start "Nome do processo"
log_step_start "Descrição da etapa"
log_step_pass "Mensagem de sucesso"
log_step_fail "Mensagem de falha"
log_step_skip "Mensagem de pulo"
log_step_done "Mensagem de conclusão"
log_done "Processo completo"

# Resultados
log_pass "Teste aprovado"
log_fail "Teste falhou"
log_result "Detalhes do resultado"
log_success "Mensagem de sucesso"

# Seções de CI
section_start "section_id" "Título da Seção"
section_end "section_id"

Uso

#!/usr/bin/env bash
source /caminho/para/log_functions.sh

log_start "Processo de Implantação"

section_start "deps" "Instalando Dependências"
log_step_start "Instalando pacotes"
if apt-get install -y pacote; then
    log_step_pass "Pacotes instalados"
else
    log_step_fail "Falha na instalação de pacotes"
fi
section_end "deps"

log_done "Implantação concluída"

Recursos Adicionais

Scripts

• log_functions.sh - Biblioteca de logging shlocksmith completa

Referência de Cores

Código	Cor
\033[0;30m	Preto
\033[0;31m	Vermelho
\033[0;32m	Verde
\033[0;33m	Amarelo
\033[0;34m	Azul
\033[0;35m	Magenta
\033[0;36m	Ciano
\033[0;37m	Branco
\033[1;XXm	Variante negrito
\033[0m	Reset