loghubident

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.

• Leve e rápida: após Initialize, cada getter é apenas a leitura de uma variável de pacote — sem locks, adequado a centenas de threads chamando milhares de vezes por milissegundo.
• Imutável após Initialize: os valores são escritos uma única vez no boot e nunca mais modificados.
• Multiplataforma: UUIDv7 gerado localmente via go-loghub-uuid, sem dependência de /proc.

A especificação completa de design está em SPEC.md.

Instalação

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

Requer Go 1.22+.

Uso

package main

import (
	"fmt"

	lhident "github.com/patrickbrandao/go-loghub-ident"
)

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

Regras de uso

• Chame Initialize() uma única vez, no início de main(), antes de criar qualquer goroutine que vá ler os getters. Esse contrato é o que torna a leitura concorrente segura sem sincronização.
• Uma segunda chamada a Initialize() encerra o processo com código 112.

API

Função	Retorno	Descrição
Initialize()	—	resolve a identidade; encerra em falha
DataDir()	string	diretório de dados
MachineID()	string	id da máquina (32 hex, sem hífen)
AgentName()	string	nome do agente
AgentUUID()	string	UUIDv7 canônico (com hífens)
Hostname()	string	hostname
Workspace()	string	workspace/tenant

Resolução de cada campo

Precedência geral: variável de ambiente → arquivo de disco → fallback. Para cada fonte: ler 1ª linha → trim → lowercase → sanear → validar regex. Uma fonte ausente cai para a próxima; uma env presente mas inválida encerra o processo.

Campo	Env	Fontes de fallback	Regex
DATADIR	DATADIR	/data (validado de forma preguiçosa)	caminho de dir
MACHINE_ID	MACHINE_ID	$MACHINE_ID_FILE (def. /etc/machine-id) → $DATADIR/machine_id → gerado	^[0-9a-f]{32}$
AGENT_NAME	AGENT_NAME	$DATADIR/agent_name → argv[0] (base, sem .exe)	^[a-z0-9._-]+$
AGENT_UUID	AGENT_UUID	$DATADIR/agent_uuid → gerado (UUIDv7)	UUIDv7 canônico
HOSTNAME	HOSTNAME	os.Hostname()	^[a-z0-9.-]+$
WORKSPACE	WORKSPACE	$DATADIR/workspace → default	^[a-z0-9.-]+$

Persistência

• Apenas identidades geradas aleatoriamente (machine_id, agent_uuid) são gravadas em $DATADIR (permissão 0644), para que o mesmo valor seja reobtido em execuções futuras. Valores determinísticos (argv[0], default) nunca gravam arquivo.
• A biblioteca não cria o DATADIR; o container/orquestrador deve montar o volume. No caminho feliz (todas as envs presentes), $DATADIR nunca é tocado — compatível com filesystem read-only.

Diagnóstico

Defina a env LOGHUB_IDENT_DEBUG (qualquer valor não vazio) para que Initialize() escreva em stderr uma linha por campo indicando a origem do valor (env / file / generated / fallback).

Códigos de saída

Em qualquer falha, escreve lib-loghub-ident: <VARIÁVEL>: <motivo> em stderr e chama os.Exit(<código>).

Código	Variável	Motivo
100	DATADIR	diretório necessário não existe ou não é diretório
102	MACHINE_ID	env não casa com ^[0-9a-f]{32}$
103	AGENT_NAME	todas as fontes vazias (argv[0] ficou vazio)
104	AGENT_NAME	valor não casa com ^[a-z0-9._-]+$
105	AGENT_UUID	falha na geração local de UUIDv7
106	AGENT_UUID	gravação em $DATADIR/agent_uuid falhou
107	AGENT_UUID	valor não casa com a regex de UUIDv7
108	HOSTNAME	env vazia e os.Hostname() retornou erro
109	HOSTNAME	valor não casa com ^[a-z0-9.-]+$
111	WORKSPACE	valor não casa com ^[a-z0-9.-]+$
112	(geral)	Initialize() chamado mais de uma vez
113	MACHINE_ID	gravação em $DATADIR/machine_id falhou

Em relação ao rascunho original: removidos os códigos 101 (machine-id é sempre regenerável) e 110 (workspace tem fallback default); adicionado o 113 (falha de gravação do machine_id).

Exemplo

Veja examples/minimal para um programa executável.

Licença

Ver LICENSE.

Documentation

Overview

Package loghubident resolve e expõe a identidade de um software dentro do ecossistema Loghub. É carregado uma única vez no boot do processo (Initialize) e disponibiliza seis valores imutáveis por meio de getters de pacote.

Os seis campos resolvidos são:

• DataDir — diretório de dados persistente (env DATADIR ou /data)
• MachineID — identificador da máquina (env MACHINE_ID, arquivo configurável via MACHINE_ID_FILE, $DATADIR/machine_id, ou gerado)
• AgentName — nome do agente (env AGENT_NAME, $DATADIR/agent_name ou argv[0])
• AgentUUID — UUIDv7 persistente (env AGENT_UUID, $DATADIR/agent_uuid ou gerado)
• Hostname — hostname (env HOSTNAME ou os.Hostname)
• Workspace — workspace/tenant (env WORKSPACE, $DATADIR/workspace ou "default")

Precedência geral de cada campo: variável de ambiente → arquivo de disco → fallback do sistema. Uma fonte ausente cai para a próxima; uma env presente mas inválida encerra o processo com o código do campo. Todos os valores são normalizados para lowercase e validados por regex.

O UUIDv7 é gerado localmente via github.com/patrickbrandao/go-loghub-uuid, sem dependência de /proc, sendo portanto multiplataforma.

Uso rápido

package main

import (
    "fmt"

    lhident "github.com/patrickbrandao/go-loghub-ident"
)

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

Defina a variável de ambiente LOGHUB_IDENT_DEBUG para que Initialize escreva em stderr a origem de cada valor resolvido.

Index

• Constants
• func AgentName() string
• func AgentUUID() string
• func DataDir() string
• func Hostname() string
• func Initialize()
• func MachineID() string
• func Workspace() string

Constants

const DefaultDataDir = "/data"

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

const DefaultMachineIDFile = "/etc/machine-id"

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

const DefaultWorkspace = "default"

DefaultWorkspace é o valor usado para WORKSPACE quando nenhuma fonte fornece um valor.

const EnvDebug = "LOGHUB_IDENT_DEBUG"

EnvDebug é a variável de ambiente que, quando definida (valor não vazio), ativa o log de diagnóstico em stderr durante Initialize.

Functions

func AgentName

func AgentName() string

AgentName retorna o nome do agente.

func AgentUUID

func AgentUUID() string

AgentUUID retorna o UUIDv7 canônico do agente (com hífens).

func DataDir

func DataDir() string

DataDir retorna o diretório de dados resolvido.

func Hostname

func Hostname() string

Hostname retorna o hostname resolvido.

func Initialize

func Initialize()

Initialize resolve os seis campos de identidade a partir de variáveis de ambiente, arquivos e fallbacks do sistema, e os disponibiliza pelos getters de pacote (DataDir, MachineID, AgentName, AgentUUID, Hostname, Workspace).

Deve ser chamada UMA ÚNICA VEZ, no início de main(), ANTES de criar qualquer goroutine que vá ler os getters. Esse contrato estabelece a relação happens-before que torna a leitura posterior segura sem sincronização.

Em qualquer falha de resolução, escreve em stderr no formato

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

e encerra o processo com o código correspondente (ver SPEC.md / README). A segunda chamada encerra com código 112.

Se a variável de ambiente LOGHUB_IDENT_DEBUG estiver definida, escreve em stderr uma linha por campo indicando a origem do valor resolvido.

func MachineID

func MachineID() string

MachineID retorna o identificador da máquina (32 hex, sem hífen).

func Workspace

func Workspace() string

Workspace retorna o workspace (tenant) resolvido.