loghub_ident

README

lib-loghub-ident

Biblioteca Go que resolve e expõe a identidade de um software dentro do ecossistema Loghub. Preenche seis campos (DataDir, MachineID, AgentName, AgentUUID, Hostname, Workspace) a partir de variáveis de ambiente, arquivos e fallbacks do sistema. Projetada para microserviços em containers. UUID v4 gerado via crypto/rand. Arquivo de machine-id configurável via env MACHINE_ID_FILE.

Instalação

go get github.com/patrickbrandao/go-loghub-ident

Uso

package main

import (
    "fmt"
    "github.com/patrickbrandao/go-loghub-ident"
)

func main() {
    loghub_ident.Initialize() // encerra o processo se algo falhar
    fmt.Println("agent:", loghub_ident.ID.AgentName, loghub_ident.ID.AgentUUID)
}

Variáveis de identidade

Precedência: (1) variável de ambiente → (2) arquivo de disco → (3) fallback do sistema.

Cada fonte: ler primeira linha → trim whitespace → forçar lowercase → sanear → validar regex.

Variável	Env	Arquivo de fallback	Fallback final	Regex final	Códigos
DATADIR	DATADIR	—	/data	(diretório existente)	100
MACHINE_ID	MACHINE_ID	$MACHINE_ID_FILE (padrão /etc/machine-id)	—	^[0-9a-f]{32}$	101, 102
AGENT_NAME	AGENT_NAME	$DATADIR/agent_name	filepath.Base(os.Args[0]) saneado	^[a-z0-9._-]+$	103, 104
AGENT_UUID	AGENT_UUID	$DATADIR/agent_uuid	gerar via crypto/rand e gravar em $DATADIR/agent_uuid	UUID v4 canônico	105, 106, 107
HOSTNAME	HOSTNAME	—	os.Hostname()	^[a-z0-9.-]+$	108, 109
WORKSPACE	WORKSPACE	$DATADIR/workspace	— (obrigatório; sem fallback)	^[a-z0-9.-]+$	110, 111

Códigos de saída

Em qualquer falha, a biblioteca escreve em stderr:

lib-loghub-ident: <VARIÁVEL>: <motivo>

e chama os.Exit(<código>).

Código	Variável	Motivo
100	DATADIR	diretório informado (env ou /data) não existe ou não é um diretório
101	MACHINE_ID	env vazio e arquivo de machine-id ($MACHINE_ID_FILE) ausente ou ilegível
102	MACHINE_ID	valor obtido não casa com ^[0-9a-f]{32}$ após remover - e aplicar lowercase
103	AGENT_NAME	env vazio, arquivo $DATADIR/agent_name ausente/vazio e argv[0] saneado ficou vazio
104	AGENT_NAME	valor obtido não casa com ^[a-z0-9._-]+$
105	AGENT_UUID	falha na geração local de UUID v4 via crypto/rand
106	AGENT_UUID	gravação em $DATADIR/agent_uuid (perm 0644) falhou
107	AGENT_UUID	valor obtido não casa com regex de UUID v4 canônico
108	HOSTNAME	env vazio e os.Hostname() retornou erro
109	HOSTNAME	valor obtido não casa com ^[a-z0-9.-]+$ após lowercase
110	WORKSPACE	env vazio e $DATADIR/workspace ausente ou vazio
111	WORKSPACE	valor obtido não casa com ^[a-z0-9.-]+$
112	(geral)	Initialize() chamado mais de uma vez

Como rodar em container

Dockerfile

FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY go.mod ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /myservice ./examples/minimal/

FROM alpine:3.19
COPY --from=builder /myservice /usr/local/bin/myservice
ENTRYPOINT ["myservice"]

docker run

# Cria volume de dados com workspace
mkdir -p /tmp/agent-data
echo "production" > /tmp/agent-data/workspace

# Roda o container
docker run --rm \
  -v /tmp/agent-data:/data \
  -e WORKSPACE=production \
  -e MACHINE_ID=abcdef0123456789abcdef0123456789 \
  myservice:latest

Como testar

# Testes unitários (todas as plataformas)
go test ./...

# Testes de integração
go test -tags=integration ./...

# Com verbose
go test -v ./...
go test -v -tags=integration ./...

Garantias

• Imutável após Initialize. ID e seus campos nunca mudam após a chamada a Initialize(). Goroutines leem ID.* direto, sem sincronização.
• Sem dependências externas. Apenas a biblioteca padrão do Go. UUID v4 gerado via crypto/rand.
• Multiplataforma. UUID gerado localmente. Arquivo de machine-id configurável via env MACHINE_ID_FILE (padrão /etc/machine-id).
• Go 1.21+. Versão mínima exigida.
• Chamada única. Initialize() só pode ser chamada uma vez; segunda chamada encerra com código 112.
• DATADIR preexistente. A biblioteca não cria o diretório de dados; o container/orquestrador deve montar o volume.

Documentation

Overview

Package loghub_ident fornece a identidade do software dentro do ecossistema Loghub. A biblioteca é carregada uma única vez na inicialização do processo (Initialize) e expõe os seis valores de identidade em um singleton imutável (ID).

Os seis campos resolvidos são:

• DataDir — diretório de dados (env DATADIR ou /data)
• MachineID — identificador único da máquina (env MACHINE_ID ou arquivo configurável via env MACHINE_ID_FILE, padrão /etc/machine-id)
• AgentName — nome do agente (env, arquivo ou argv[0])
• AgentUUID — UUID v4 persistente do agente (env, arquivo ou gerado localmente via crypto/rand)
• Hostname — hostname da máquina (env ou os.Hostname)
• Workspace — workspace lógico (env ou arquivo; obrigatório)

Cada campo segue a precedência: variável de ambiente → arquivo de disco → fallback do sistema (quando disponível). Todos são normalizados para lowercase.

Em caso de falha na resolução de qualquer campo, a biblioteca escreve uma mensagem de erro em stderr e encerra o processo via os.Exit com um código específico (100–112). Consulte a documentação de Initialize para detalhes.

A biblioteca não possui dependências externas; utiliza apenas a biblioteca padrão do Go. Compatível com qualquer plataforma suportada por Go (UUID gerado via crypto/rand, sem dependência de /proc).

Uso rápido

package main

import (
    "fmt"
    "github.com/patrickbrandao/go-loghub-ident"
)

func main() {
    loghub_ident.Initialize()
    fmt.Println("Agent:", loghub_ident.ID.AgentName)
    fmt.Println("UUID:",  loghub_ident.ID.AgentUUID)
}

Index

• Constants
• func Initialize()
• type Identity

Constants

const DefaultDataDir = "/data"

DefaultDataDir é o caminho padrão do diretório de dados quando a variável de ambiente DATADIR não está definida.

const DefaultMachineIDFile = "/etc/machine-id"

DefaultMachineIDFile é o caminho padrão do arquivo de machine-id quando a variável de ambiente MACHINE_ID_FILE não está definida.

Functions

func Initialize

func Initialize()

Initialize popula ID lendo variáveis de ambiente, arquivos e fallbacks. Em qualquer falha, escreve no stderr e chama os.Exit com o código específico (100–112). Chamar duas vezes encerra com código 112.

Deve ser chamada no início do main, antes de spawn de qualquer goroutine que vá ler ID.

Códigos de saída:

100 — DATADIR não existe ou não é diretório
101 — MACHINE_ID: env vazio e arquivo de machine-id ausente
102 — MACHINE_ID: formato inválido
103 — AGENT_NAME: todas as fontes vazias
104 — AGENT_NAME: formato inválido
105 — AGENT_UUID: falha na geração local de UUID v4
106 — AGENT_UUID: gravação em $DATADIR/agent_uuid falhou
107 — AGENT_UUID: não é UUID v4 canônico
108 — HOSTNAME: os.Hostname() falhou
109 — HOSTNAME: formato inválido
110 — WORKSPACE: env vazio e arquivo ausente
111 — WORKSPACE: formato inválido
112 — Initialize() chamado mais de uma vez

Types

type Identity

type Identity struct {
	DataDir   string // diretório existente; ex.: "/data"
	MachineID string // 32 hex chars [0-9a-f], sem hífen
	AgentName string // [a-z0-9._-]+
	AgentUUID string // UUID v4 canônico
	Hostname  string // [a-z0-9.-]+
	Workspace string // [a-z0-9.-]+
}

Identity contém os seis valores de identidade do agente. Todos em lowercase. Imutável após Initialize.

var ID *Identity

ID é o singleton populado por Initialize. Antes de Initialize é nil. Após Initialize, nunca é reatribuído nem mutado. Sem mutex porque é write-once antes das goroutines do consumidor existirem.