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, que é 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 um flag repo_public. Para repositórios confirmados como públicos no GitHub / GitLab / Bitbucket, 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 junto com todos os outros:

# 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 nome de usuário, email ou endereço IP. Owners e nomes de repositórios no GitHub / GitLab / Bitbucket só são enviados no evento único project_initialized 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, código-fonte ou caminho 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 — 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 dos EUA). Dados retidos conforme a política de retenção padrão do PostHog.
• Rastreamento de erros: Sentry Cloud (região dos EUA). 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