Telemetria

O Archgate coleta dados de uso anônimos para nos ajudar a entender como a CLI é utilizada, priorizar funcionalidades e corrigir falhas. Esta página explica exatamente o que é coletado, o que não é, e como desativar.

O que coletamos

Análise de uso (PostHog)

Quando você executa um comando do Archgate, registramos:

• Nome do comando e quais flags foram usadas (ex: check --json, apenas a presença da flag, nunca valores)
• Código de saída (0, 1, 2 ou 130) e duração da execução (milissegundos), além de um tag de desfecho resumida (success, user_error, internal_error, cancelled)
• Ambiente: SO, arquitetura, versão do Bun, versão do Archgate, detecção de CI (incluindo provedor: GitHub Actions / GitLab CI / CircleCI, etc.), detecção de TTY, detecção de WSL, shell (bash, zsh, pwsh…) e locale
• Contexto de instalação: como a CLI foi instalada (binário, proto, dependência local ou gerenciador de pacotes global)
• Contexto do projeto: se existe um projeto Archgate no diretório atual, quantas ADRs possui, quantas têm regras automatizadas e quantos domínios distintos de ADR estão em uso
• Contexto do repositório (não identificável): se o diretório atual é um repositório git, o bucket do host (github / gitlab / bitbucket / azure-devops / other), um repo_id com hash (SHA-256 da URL remota normalizada, truncado em 16 caracteres hex, não reversível) e o nome do branch padrão
• Localização aproximada: país e região, resolvidos no servidor a partir do seu IP (descartado em seguida; veja Anonimização de IP)
• ID de instalação anônimo: um UUID aleatório gerado na primeira execução, não derivado de nenhum dado pessoal

Além dos eventos gerais do ciclo de vida do comando (command_executed / command_completed), comandos específicos enviam eventos enriquecidos:

• check: contagens agregadas de regras (total, aprovadas, reprovadas, avisos, erros), formato de saída usado, se filtros foram aplicados, arquivos analisados, duração de carregamento, duração da verificação. Sem caminhos de arquivo ou conteúdo de violação
• init: escolha do editor, se o plugin foi instalado, se o projeto já existia. Um evento separado project_initialized é enviado uma única vez, contendo o bucket do host do repositório, repo_is_git e uma flag repo_public. Para repositórios confirmados como públicos no GitHub / GitLab / Bitbucket / Azure DevOps, esse evento também leva URL remota, owner e nome do repositório; veja Identidade do repositório. Repositórios privados e auto-hospedados nunca têm identidade compartilhada.
• upgrade: transição de versão (de → para), método de instalação, sucesso/falha e uma razão de falha opcional
• login: subcomando usado (login, logout, refresh, status), sucesso/falha e um bucket de falha (network, tls, denied, other) quando falha
• telemetry_preference_changed: disparado uma vez quando você ativa ou desativa a telemetria, para que possamos entender as taxas de opt-out

Identidade do repositório

O Archgate envia um repo_id com hash em todo evento para que possamos contar repositórios distintos usando a CLI sem aprender seus nomes. A URL remota bruta, o owner e o nome do repositório não são incluídos no fluxo comum de eventos.

Em archgate init, um evento project_initialized único é enviado. Se, e somente se, o repositório for confirmado como público no GitHub, GitLab, Bitbucket ou Azure DevOps (via consulta não autenticada à API do host), esse evento também inclui remote_url, repo_owner e repo_name. Isso nos permite ver quais repositórios públicos estão adotando o Archgate sem jamais expor os privados.

O que nunca é compartilhado:

• Repositórios privados (a consulta retorna 404, 401 ou private: true)
• Hosts Git auto-hospedados (a verificação pula esses completamente)
• Repositórios em que a consulta expira, é limitada por rate-limit ou não retorna uma resposta pública definitiva

Não quer o evento de forma alguma? Desative a telemetria por completo. O evento project_initialized é suprimido quando você desativa a telemetria:

# Por shell / por invocação
export ARCHGATE_TELEMETRY=0

# Ou persistentemente
archgate telemetry disable

Veja Como desativar abaixo para detalhes completos.

Rastreamento de erros (Sentry)

Quando a CLI falha (código de saída 2), enviamos:

• Tipo do erro, mensagem e stack trace (caminhos de arquivos são reduzidos para caminhos relativos como src/cli.ts)
• Contexto de execução: SO, arquitetura, versão do Bun, versão do Archgate
• ID de instalação anônimo (mesmo UUID aleatório da análise)

O que NÃO coletamos

• Nenhuma informação pessoal: nenhum email, senha, segredo ou endereço IP. O evento único project_initialized pode incluir repo_owner e repo_name para repositórios confirmados como públicos pelo host; veja Identidade do repositório. Repositórios privados e auto-hospedados nunca têm identidade compartilhada.
• Nenhum conteúdo de arquivo: nenhum conteúdo de ADR ou código-fonte. Relatórios de erro (Sentry) podem incluir caminhos relativos em stack traces, mas nunca caminhos absolutos ou conteúdos de arquivo.
• Nenhum contexto de IA: nada de interações com agentes, prompts ou conteúdo gerado por IA
• Nenhum valor de flag: registramos que --json foi usado, não o conteúdo da saída JSON
• Nenhuma atividade de rede: nenhuma URL, chave de API ou token

Anonimização de IP

O Archgate usa a anonimização de IP nativa do PostHog:

1. Sua CLI envia um evento ao PostHog com $ip: null
2. O PostHog resolve seu IP para um país e região (ex: “BR”, “São Paulo”) no servidor
3. O endereço IP é então descartado. Ele nunca é armazenado no PostHog

Para o rastreamento de erros do Sentry, o projeto tem “Prevent Storing of IP Addresses” habilitado, então os IPs são removidos antes do armazenamento.

Como desativar

Você pode desativar toda a telemetria (análise e rastreamento de erros) de duas formas:

Variável de ambiente

export ARCHGATE_TELEMETRY=0

Valores aceitos: 0, false, no, off (sem diferenciação de maiúsculas/minúsculas).

Adicione ao seu perfil de shell (.bashrc, .zshrc, etc.) para desativar permanentemente.

Comando da CLI

archgate telemetry disable

Para reativar:

archgate telemetry enable

Para verificar o status atual:

archgate telemetry status

A variável de ambiente tem prioridade sobre a configuração da CLI. Se ARCHGATE_TELEMETRY=0 estiver definida, a telemetria é desativada independentemente da configuração da CLI.

Onde os dados são armazenados

• Análise: PostHog Cloud (região da UE). Dados retidos conforme a política de retenção padrão do PostHog.
• Rastreamento de erros: Sentry Cloud (região da UE). Eventos de erro retidos por 90 dias.
• Configuração local: ~/.archgate/config.json armazena sua preferência de telemetria e o ID de instalação anônimo.

Código aberto

A implementação da telemetria é totalmente open source. Você pode inspecionar exatamente quais dados são coletados lendo:

• src/helpers/telemetry.ts: rastreamento de eventos PostHog
• src/helpers/sentry.ts: captura de erros Sentry
• src/helpers/telemetry-config.ts: configuração e lógica de desativação