counterscale

Counterscale é um rastreador e painel de análise web de código aberto que os usuários hospedam por conta própria no Cloudflare. É lançado sob a licença MIT e projetado para ser fácil de implantar e manter, com o README observando que o custo de operação deve ser próximo de zero, mesmo em níveis de tráfego elevados. É alimentado principalmente por Cloudflare Workers e Workers Analytics Engine. A partir de fevereiro de 2025, o Workers Analytics Engine possui uma retenção máxima de 90 dias, portanto, o painel só pode exibir os últimos 90 dias de dados registrados. O Counterscale também fornece armazenamento de dados a longo prazo em um bucket R2 usando arquivos Apache Arrow. Este armazenamento de longo prazo é habilitado por padrão e pode ser desativado através da CLI. A instalação requer macOS ou Linux, Node v20 ou superior e uma conta ativa no Cloudflare. Antes da implantação, os usuários precisam de um subdomínio do Cloudflare Workers, o beta do Analytics Engine habilitado na conta e um token de API do Cloudflare com, no mínimo, permissões de Account.Account Analytics. A implantação começa com npx wrangler login, seguido por npx @counterscale/cli@latest install. O instalador solicita o token de API e pergunta se o painel deve ser protegido por senha. Escolher sim é recomendado para implantações públicas; escolher não deixa o painel publicamente acessível. Após a instalação, a aplicação do servidor é implantada em um subdomínio workers.dev. Para registrar o tráfego do site, o Counterscale oferece vários métodos de integração. O carregador de script torna o tracker.js disponível na URL implantada. Os usuários podem adicionar uma tag de script com um id de counterscale-script, um atributo data-site-id e a fonte do tracker.js. O rastreador também é publicado como um pacote npm, @counterscale/tracker. Ele pode ser inicializado com um site ID e uma URL de reporter. O módulo de cliente expõe métodos como init, isInitialized, getInitializedClient, trackPageview e cleanup. Um módulo de servidor separado, @counterscale/tracker/server, suporta rastreamento de análises de backend. Ele utiliza a API fetch em vez de XMLHttpRequest, não possui recursos dependentes de DOM, requer parâmetros explícitos de URL e hostname, e é do tipo fire-and-forget, para que erros de rastreamento não lancem exceções. O Counterscale inclui opções avançadas. O rastreamento automático de pageviews pode ser desativado definindo autoTrackPageviews como false, após o qual o trackPageview pode ser chamado manualmente. A URL de implantação também pode ser colocada atrás de um domínio personalizado. A CLI fornece comandos para instalação, autenticação e gerenciamento de armazenamento. O comando install suporta o modo avançado para personalizar o nome do worker e o conjunto de dados de análise, bem como logs detalhados. Os subcomandos de autenticação incluem enable, disable e roll. Os subcomandos de armazenamento incluem enable e disable. A atualização geralmente significa executar novamente o instalador da CLI; versões principais podem ter etapas extras descritas nas notas de lançamento. Para desenvolvimento local, o Counterscale possui apenas um banco de dados: o conjunto de dados do Cloudflare Analytics Engine, comunicado via HTTP usando a API do Cloudflare. Não há banco de dados de teste local, portanto, gravações locais não produzem efeito (no-op) e as leituras vêm do conjunto de dados de produção do Analytics Engine. O Cloudflare Analytics Engine utiliza amostragem para tornar a ingestão e a consulta de alto volume acessíveis em escala, semelhante a outras ferramentas de análise.