Logz (Logger Global em Golang) [pt-BR]

Introdução ao Logz: Um Logger Seguro e Flexível para Desenvolvedores Go e Uso Geral! 🚀

---

Abertura

Você está cansado de lidar com sistemas de log complicados e inseguros em suas aplicações Go? Imagine ter um logger que, além de repleto de recursos poderosos e segurança robusta, oferece uma experiência de uso incrivelmente suave para o desenvolvedor. Conheça o Logz—a solução open source que transforma totalmente seu fluxo de logging, combinando flexibilidade, segurança e integração com notificações. Seja durante o desenvolvimento local ou em ambientes de produção, o Logz está aqui para tornar seu processo de logging simples e eficaz.

---

Conteúdo Principal

Por que Logz?

Toda aplicação de qualidade precisa possuir um sistema de log confiável, mas na prática, o logging frequentemente é relegado a um segundo plano. Com o Logz, transformamos essa experiência ao dar ênfase a dois pilares essenciais: experiência do desenvolvedor e segurança. Veja o que diferencia o Logz:

• Logging Orientado a Metadados:
  
  Anexe facilmente informações contextuais—como requestId, user, ou outros campos relevantes—a cada entrada de log. Esses dados não são apenas informações extras: eles fornecem inteligência acionável, agilizando a depuração e o monitoramento.

• Práticas de Build Seguras:
  
  Logz utiliza a flag -trimpath do Go para remover caminhos absolutos sensíveis dos binários, além de recomendar a compressão dos executáveis com UPX para garantir que sejam leves e seguros. Aqui, a segurança não é opcional—ela é parte fundamental do design.

• Opções de Saída Flexíveis:
  
  Seja para exibir logs no console durante o desenvolvimento ou para gravá-los em arquivos em produção, o Logz oferece total controle. Suas flags de linha de comando permitem mudar facilmente a saída ou o formato, sem impor um único fluxo rígido.

---

Principais Funcionalidades

O Logz vem carregado de recursos para atender todas as suas necessidades de logging:

• Suporte a Múltiplos Formatos de Log:
  
  Escolha entre logs em texto, que facilitam a leitura humana, ou JSON, ideal para integração com sistemas de monitoramento.

• Saída Alinhada e Amigável:
  
  Desfrute de logs formatados de forma bonita, onde timestamps, níveis e metadados permanecem alinhados e organizados. Em logs de texto, os metadados são impressos em uma segunda linha (com indentação), garantindo clareza sem poluir a mensagem principal.

• Controle Completo via CLI:
  
  Com flags como --msg, --output, --metadata e --format, você tem controle total sobre cada entrada de log, podendo customizar a saída conforme necessário.

• Integrações de Notificação:
  
  Logz vai além do simples registro de mensagens, suportando notificações via webhooks HTTP, ZeroMQ e DBus. Assim, você pode configurar alertas em tempo real para eventos críticos, integrando com seus sistemas de monitoramento de forma transparente.

• Instalador Inteligente no Primeiro Uso:
  
  Para tornar a experiência ainda mais fluida, Logz inclui um instalador inteligente que, na primeira execução, verifica se o binário está instalado corretamente. Se não estiver, ele pode copiar o binário para o diretório apropriado (por exemplo, $HOME/.local/bin para usuários não-root ou /usr/local/bin para root) e atualizar o PATH automaticamente, garantindo que sua ferramenta esteja pronta para uso imediato.

---

Exemplos de Código Avançados

Exemplo 1: Logging Básico com Metadados

Execute o seguinte comando para registrar uma mensagem de debug com metadados contextuais:

logz debug \
  --msg "Depurando a nova funcionalidade com facilidade!" \
  --output "stdout" \
  --metadata requestId=12345,user=admin

Saída Esperada:

[2025-03-02T03:35:13Z] 🐛 DEBUG - Depurando a nova funcionalidade com facilidade!
                     {"requestId":"12345","user":"admin"}

Explicação:

Cada log exibe um timestamp, o nível (com um emoji para facilitar a identificação visual) e a mensagem principal. Os metadados são exibidos logo abaixo, com uma indentação que mantém a saída limpa e organizada.

---

Exemplo 2: Logging em Arquivo no Formato JSON

Para ambientes de produção, é comum utilizar JSON para facilitar a integração com sistemas de monitoramento. Por exemplo:

logz info \
  --msg "Serviço iniciado com sucesso." \
  --output "/var/log/meuapp/servico.log" \
  --format json \
  --metadata service=auth,version=v1.0.2

Saída Esperada (JSON):

{
  "timestamp": "2025-03-02T03:40:00Z",
  "level": "INFO",
  "message": "Serviço iniciado com sucesso.",
  "metadata": {
    "service": "auth",
    "version": "v1.0.2"
  }
}

Explicação:

As entradas de log são formatadas em JSON, permitindo que sejam facilmente processadas por agregadores de logs e sistemas de monitoramento.

---

Exemplo 3: Integração do Logz em um Microserviço Web

Veja como integrar Logz em um servidor HTTP no Go:

package main

import (
    "fmt"
    "net/http"
    "github.com/faelmori/logz/logger" // Ajuste o caminho conforme necessário
)

func main() {
    // Inicializa o logger com um prefixo customizado.
    log := logger.NewLogger("WebAPI: ")

    // Define um handler HTTP que loga os detalhes de cada requisição.
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        log.Info("Requisição recebida", map[string]interface{}{
            "método": r.Method,
            "caminho": r.URL.Path,
        })
        fmt.Fprintf(w, "Olá, mundo!")
    })

    // Inicia o servidor HTTP, logando seu início.
    log.Info("Iniciando servidor na porta 8080", nil)
    if err := http.ListenAndServe(":8080", nil); err != nil {
        log.Fatal("Falha ao iniciar servidor", map[string]interface{}{"erro": err})
    }
}

Explicação:

Cada requisição é logada com informações úteis que facilitam a análise do tráfego e a depuração de problemas. Se ocorrer um erro crítico, o log dispara um alerta via o método Fatal, que encerra o servidor.

---

Exemplo 4: Integração de Notificadores para Alertas em Tempo Real

Veja como você pode configurar notificadores para enviar alertas quando ocorrerem erros críticos:

package main

import (
    "time"
    "github.com/faelmori/logz/logger"
)

func main() {
    // Inicializa o logger e define metadados globais.
    log := logger.NewLogger("AlertService: ")
    log.SetMetadata("service", "payment")
    log.SetMetadata("env", "production")

    // Simula um erro que dispara um alarme.
    log.Error("Falha na transação de pagamento", map[string]interface{}{
        "transactionId": "txn_987654321",
        "timestamp":     time.Now().Format(time.RFC3339),
    })
}

Explicação:

Com os notificadores configurados no Logz, esta mensagem de erro pode, por exemplo, disparar um alerta via um webhook HTTP ou enviar uma notificação por DBus, garantindo uma resposta rápida a problemas críticos.

---

Exemplo 5: Instalador Inteligente no Primeiro Uso

Para aprimorar a experiência do usuário, Logz possui um instalador inteligente. No primeiro uso, o binário verifica se está corretamente instalado; se não estiver, ele se copia para o diretório apropriado e atualiza o PATH:

package main

import (
    "fmt"
    "io"
    "os"
    "os/exec"
    "path/filepath"
    "strings"
)

func isInPath() bool {
    pathEnv := os.Getenv("PATH")
    exePath, err := os.Executable()
    if err != nil {
        return false
    }
    exeDir := filepath.Dir(exePath)
    return strings.Contains(pathEnv, exeDir)
}

func updatePath(targetDir string) error {
    shell := filepath.Base(os.Getenv("SHELL"))
    var shellConfig string

    switch shell {
    case "bash":
        shellConfig = filepath.Join(os.Getenv("HOME"), ".bashrc")
    case "zsh":
        shellConfig = filepath.Join(os.Getenv("HOME"), ".zshrc")
    default:
        shellConfig = filepath.Join(os.Getenv("HOME"), ".profile")
    }

    fmt.Printf("Adicione a seguinte linha ao seu %s para incluir %s no PATH:\n", shellConfig, targetDir)
    fmt.Printf("export PATH=%s:$PATH\n", targetDir)
    return nil
}

func firstRunInstaller() {
    configFile := filepath.Join(os.Getenv("HOME"), ".logzconfig")
    if _, err := os.Stat(configFile); os.IsNotExist(err) {
        fmt.Println("Parece que é a primeira vez que você executa o Logz.")
        fmt.Print("Deseja instalar o Logz no seu sistema para facilitar o uso? (Y/n): ")
        var resp string
        fmt.Scanln(&resp)
        if strings.ToLower(resp) == "y" || resp == "" {
            exePath, err := os.Executable()
            if err != nil {
                fmt.Printf("Erro ao obter o caminho do executável: %v\n", err)
                return
            }
            targetDir := "/usr/local/bin"
            if os.Geteuid() != 0 {
                targetDir = filepath.Join(os.Getenv("HOME"), ".local", "bin")
            }
            target := filepath.Join(targetDir, "logz")
            cmd := exec.Command("cp", exePath, target)
            if err := cmd.Run(); err != nil {
                fmt.Printf("Erro durante a instalação: %v\n", err)
                return
            }
            fmt.Printf("Logz instalado em: %s\n", target)
            if err := updatePath(targetDir); err != nil {
                fmt.Printf("Falha ao atualizar o PATH: %v\n", err)
            }
            os.WriteFile(configFile, []byte("installed=true\n"), 0644)
        } else {
            os.WriteFile(configFile, []byte("skip_install=true\n"), 0644)
            fmt.Println("Instalação ignorada. Você pode instalá-lo manualmente depois.")
        }
    }
}

func main() {
    firstRunInstaller()
    fmt.Println("Logz está pronto para uso!")
}

Explicação:

Neste trecho, o programa verifica se um arquivo de configuração existe para determinar se é a primeira execução. Se for, ele questiona o usuário para instalar automaticamente o binário no diretório adequado e guia a atualização do PATH, proporcionando uma experiência “mágica” e sem complicações.

---

Destaques do Projeto

• Open Source no GitHub:
  
  Explore o código, contribua com melhorias ou simplesmente dê uma estrela se o Logz fizer sentido para você. Confira no GitHub.

• Documentação Detalhada:
  
  Toda a documentação está disponível em pkg.go.dev, proporcionando referências claras e guias de integração para facilitar sua adoção.

---

Conclusão e Chamada para Ação

O Logz não é apenas um logger—é uma ferramenta completa de observabilidade projetada para aplicações modernas em Go. Ao combinar práticas de build seguras, opções de saída flexíveis, manipulação rica de metadados e integrações inteligentes de notificações, o Logz capacita os desenvolvedores a monitorar e depurar suas aplicações com mais eficiência.

Experimente o Logz no seu próximo projeto Go e descubra como ele pode simplificar o seu fluxo de logging. Se o Logz facilitar sua vida, considere dar uma estrela no repositório do GitHub e compartilhar seu feedback. Juntos, podemos construir um ecossistema de logging mais inteligente, rápido e seguro—um log por vez!