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 --output json; a presença da flag mais o formato selecionado em --output — uma escolha fixa entre console/json/github/sarif — nunca valores livres de flags)
• 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, e linguagens/runtimes/frameworks detectados no projeto (comparados com uma lista fixa de sinais conhecidos de dependências e arquivos de configuração, ex.: typescript, bun, nextjs). 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, incluindo os caminhos de arquivo do local da falha. Para o binário compilado (a instalação padrão), esses são caminhos internos do bundle do Bun (ex.: /$bunfs/root/cli.js), não caminhos do seu sistema de arquivos. Para uma instalação local (dependência de desenvolvimento) ou global-pm, os frames do stack podem incluir o caminho absoluto real do arquivo da CLI instalado na sua máquina
• Caminho de instalação: o caminho absoluto do executável archgate instalado ou do script de entrada, enviado como uma tag do Sentry em cada relatório de falha
• Contexto de execução: SO, arquitetura, versão do Bun, versão do Archgate, método de instalação
• 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. Duas exceções qualificadas: o evento único project_initialized pode incluir a URL remota, 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), e relatórios de falha incluem o caminho absoluto de instalação do executável archgate, que pode conter o nome da sua conta no sistema operacional (veja Rastreamento de erros).
• Nenhum conteúdo de arquivo: nenhum conteúdo de ADR ou código-fonte. Relatórios de erro (Sentry) incluem os caminhos de arquivo do local da falha no stack trace e o caminho absoluto de instalação do executável archgate (veja Rastreamento de erros para saber exatamente como isso aparece em cada método de instalação), mas nunca conteúdos de arquivo.
• Nenhum contexto de IA: nada de interações com agentes, prompts ou conteúdo gerado por IA
• Nenhum valor livre de flag: a única exceção é o formato selecionado em --output (um enum fixo: console/json/github/sarif); nunca registramos valores fornecidos pelo usuário nem o conteúdo da saída
• Nenhuma atividade de rede: nenhuma chave de API ou token, e nenhuma URL — com uma exceção: a URL remota de um repositório confirmado como público pelo host, no evento único project_initialized (veja Identidade do repositório)

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