Plataformas
ClickHouse
Guarde as visitas e os eventos do servidor independente no ClickHouse para relatórios filtrados rápidos em sites grandes, e leve uma instalação existente para ele sem tirar nada do ar.
O servidor independente pode guardar as visitas e os eventos no ClickHouse, um banco de dados feito para ler milhões de linhas de uma vez. Todo o resto continua onde está, no SQLite, no Postgres ou no MySQL, incluindo sites, metas, funis, links, contas e configurações. Só as duas maiores tabelas mudam de lugar.
Quando vale a pena
O SQLite, o Postgres e o MySQL respondem a um painel sem filtro a partir das agregações diárias, então continuam rápidos em qualquer tamanho. Um filtro precisa ler as visitas que escolhe, e é aí que o ClickHouse ajuda. Em um ano de um site movimentado, um painel filtrado para uma página abre em 0,65 segundo, enquanto os outros levam de 9 a 24 segundos. A página de desempenho traz as medições completas.
Vale a pena a partir de alguns milhões de visitas por mês, ou quando as pessoas filtram períodos longos com frequência. Um site pequeno ganha pouco e passa a ter mais um banco de dados para cuidar.
O ClickHouse precisa de pelo menos 4 GB de memória, e de 8 GB para um ano de 10 milhões de visitas. O Runlight exige a versão 25.8 ou mais recente, hospedada por você ou no ClickHouse Cloud.
Até onde vai
Estas são medições em uma só máquina, um Apple M4 Max com 14 núcleos, com o ClickHouse 25.8 no Docker e um servidor do Runlight ao lado. Cada site tinha um ano de tráfego sintético, com cerca de quatro eventos por visita. Cada tempo cobre todas as requisições que o painel faz ao abrir, enviadas juntas, sem mais nada gravando. Seu hardware e seu tráfego vão dar outros números, então use estes como ponto de partida e meça os seus.
| Visitas por ano | Memória do ClickHouse | Últimos 7 dias | Últimos 30 dias | Últimos 12 meses | 12 meses, com filtro |
|---|---|---|---|---|---|
| 10 milhões | 8 GB | 0,14 s | 0,4 s | 2,8 s | 2,2 a 2,7 s |
| 180 milhões | 8 GB | 0,9 s | 3,7 s | 38 a 40 s | 30 a 55 s |
180 milhões de visitas por ano são cerca de 10 milhões de visitantes únicos por mês. Nesse tamanho, 14 GB de memória não foram mais rápidos que 8 GB, porque o ClickHouse estava ocupado em todos os núcleos, e não com pouca memória, mas 8 GB fica no limite: em duas rodadas de uma dúzia, com outro trabalho rodando ao lado, alguns quadros de 12 meses ficaram sem memória. Dê 14 GB ou mais a ele para ter folga. Com 4 GB, um ano de 10 milhões de visitas abria em 7 e 30 dias, mas os quadros de canal, país, dispositivo e campanha falhavam em 12 meses.
Cada evento no ClickHouse leva a fonte, a campanha, o lugar e o dispositivo da sua visita, então um filtro sobre um deles lê só os eventos. Um filtro sobre uma página lê cada visualização do período para achar as visitas que a viram, o que a torna a visão mais lenta em um ano do maior site. Períodos curtos são rápidos, com filtro ou sem.
Disco
O ClickHouse usou cerca de 0,4 GB para cada milhão de visitas com seus eventos, comprimidos: 3,7 GB para 10 milhões e 75 GB para 180 milhões. Visitas com mais eventos ocupam mais.
Hits
Um servidor registrou 600 hits por segundo e respondeu a cada um em até 0,3 segundo, com o ClickHouse ocupado em cerca de 9 núcleos. A 800 por segundo, o ClickHouse estava ocupado nos 14, e os hits esperavam e estouravam o tempo limite. Um ano de 180 milhões de visitas com quatro eventos cada dá em média cerca de 25 hits por segundo, então um servidor tem folga para picos de várias vezes a média. Para mais, rode várias cópias do servidor atrás de um balanceador de carga.
Quando o ClickHouse está fora do ar, ocupado ou reiniciando, o servidor guarda cada hit no SQLite, Postgres ou MySQL, sem endereço e sem user agent, e os envia na ordem em que chegaram assim que o ClickHouse volta a responder. Enquanto houver hits esperando, os novos entram na fila atrás deles, para que os hits de um visitante continuem em ordem. Um hit espera no máximo um dia, e esperam no máximo dois milhões, cerca de um gigabyte. Passado qualquer um dos dois, os hits se perdem e vão para o log como "could not record an event", então acompanhe o log e a saúde do ClickHouse.
Configure
Defina CLICKHOUSE_URL com o ClickHouse a usar, com o usuário, a senha e o nome de um banco de dados, e inicie o servidor.
bash
CLICKHOUSE_URL=https://runlight:password@clickhouse.example.com:8443/runlight npx @runlight/serverO servidor cria o banco de dados se ele ainda não existir, cria as tabelas e registra no log para onde vão as visitas. Se o ClickHouse não puder ser alcançado, o servidor para e diz o motivo, em vez de perder visitas.
Use https:// quando o ClickHouse estiver em outra máquina, já que a senha vai junto em cada requisição. Dentro de uma mesma rede do Docker, como abaixo, http:// basta. O servidor avisa ao iniciar se o endereço começa com http:// e pode passar pela internet.
O usuário do ClickHouse precisa destas permissões no banco dele. Só precisa também de CREATE DATABASE se o banco ainda não existir.
sql
GRANT CREATE TABLE, CREATE VIEW, INSERT, SELECT, ALTER DELETE, ALTER UPDATE, OPTIMIZE, TRUNCATE ON runlight.* TO runlight;
GRANT SELECT ON system.mutations TO runlight;A segunda linha é opcional. Com ela, uma exclusão grande (um site, ou visitas antigas além da retenção) roda em segundo plano no ClickHouse enquanto o servidor espera, pelo tempo que for preciso. Sem ela, o servidor espera na requisição, que desiste depois de cinco minutos.
Com Docker Compose
Isto roda o Runlight e o ClickHouse lado a lado, cada um com seus dados em um volume.
compose.yaml
services:
runlight:
image: ghcr.io/runlightsh/runlight
ports: ["127.0.0.1:3000:3000"]
volumes: ["runlight:/data"]
environment:
CLICKHOUSE_URL: http://runlight:change-me@clickhouse:8123/runlight
depends_on:
clickhouse:
condition: service_healthy
clickhouse:
image: clickhouse/clickhouse-server:25.8
environment:
CLICKHOUSE_USER: runlight
CLICKHOUSE_PASSWORD: change-me
ulimits:
nofile: { soft: 262144, hard: 262144 }
volumes: ["clickhouse:/var/lib/clickhouse"]
healthcheck:
test: ["CMD", "clickhouse-client", "--user", "runlight", "--password", "change-me", "-q", "SELECT 1"]
interval: 5s
volumes:
runlight:
clickhouse:Aqui o ClickHouse só é acessado de dentro da rede do Compose, então não precisa de uma porta própria.
Com o ClickHouse Cloud
Crie um serviço e copie o endereço HTTPS e a senha em Connect. O endereço vai em CLICKHOUSE_URL, com o usuário, a senha e o nome de um banco de dados acrescentados.
bash
CLICKHOUSE_URL=https://default:password@abc123.eu-west-1.aws.clickhouse.cloud:8443/runlightLeve uma instalação existente
Adicione CLICKHOUSE_URL a um servidor que já tem visitas e reinicie. Nessa primeira inicialização ele copia as visitas dos últimos dois dias para o ClickHouse antes de contar qualquer coisa, então uma visita em andamento naquele momento continua. Isso leva alguns segundos em um site movimentado. A partir daí, cada acesso vai para o ClickHouse.
O resto é copiado em segundo plano, das visitas mais novas para as mais antigas, um dia por vez, então os relatórios mais vistos ficam certos quase na hora. Um milhão de visitas leva menos de um minuto em um notebook. Até terminar, o painel mostra até onde os relatórios já chegam, e importações de visitas e de links são recusadas, já que uma importação nesse meio-tempo poderia contar as mesmas visitas duas vezes.
A cópia registra até onde chegou depois de cada dia, então uma reinicialização ou uma conexão perdida continua dali sem contar nenhuma visita duas vezes. Quando várias cópias do servidor compartilham um banco de dados, uma delas faz a cópia e as outras continuam contando. Se essa parar, outra assume em menos de dois minutos.
Para deixar tudo pronto antes de o servidor receber qualquer visita, pare o servidor, defina CLICKHOUSE_URL e rode a cópia você mesmo. Depois inicie o servidor.
bash
npx @runlight/server clickhouse copyNo Docker, rode os comandos desta página dentro do contêiner, como no comando password.
bash
docker exec runlight node node_modules/.bin/runlight.sh clickhouse statusVeja até onde chegou
bash
npx @runlight/server clickhouse statusEle mostra quantas visitas e eventos o ClickHouse guarda, até onde a cópia já chegou e se as tabelas antigas ainda têm visitas.
Esvazie as tabelas antigas
Quando a cópia termina, as visitas antigas continuam no SQLite, no Postgres ou no MySQL, e nada as lê. Esvazie essas tabelas quando estiver satisfeito com o ClickHouse.
bash
npx @runlight/server clickhouse drop-oldEle diz o que vai apagar e pede que você digite yes. Adicione --yes para pular a pergunta em um script. Ele se recusa enquanto a cópia ainda está em andamento.
Ele só esvazia as visitas que começaram antes de o ClickHouse assumir, que estão todas no ClickHouse. Um servidor que continua rodando sem CLICKHOUSE_URL depois da troca, como um que ainda não foi reiniciado, grava as visitas dele nas tabelas antigas, onde o ClickHouse nunca as vê. O status as conta, e o drop-old as deixa onde estão.
Volte atrás
Para deixar de usar o ClickHouse, pare todos os servidores e copie tudo de volta.
bash
npx @runlight/server clickhouse copy --backIsso substitui as visitas e os eventos no SQLite, no Postgres ou no MySQL por tudo o que o ClickHouse guarda, incluindo as visitas desde a troca, e depois esvazia o ClickHouse. Ele pergunta antes, e se recusa enquanto algum servidor ainda estiver recebendo acessos. Um servidor que parou sem desligar direito conta como encerrado um minuto e meio depois do último sinal. Em seguida, remova CLICKHOUSE_URL e inicie o servidor, que monta as agregações diárias de novo enquanto roda. Ativar o ClickHouse outra vez depois copia tudo do zero.
Se ele parar no meio, rode de novo. Assim que o banco antigo tem tudo, ele registra isso antes de esvaziar o ClickHouse, então uma segunda execução termina o trabalho em vez de copiar de um ClickHouse vazio. Até terminar, nenhum servidor inicia com CLICKHOUSE_URL.
No seu próprio app
Um app Node que roda o Runlight como biblioteca pode fazer o mesmo. Envolva o armazenamento que ele já usa.
ts
import { runlight } from "@runlight/sdk";
import { postgres } from "@runlight/sdk/postgres";
import { clickhouse } from "@runlight/sdk/clickhouse";
export const rl = runlight({
store: clickhouse({ url: process.env.CLICKHOUSE_URL!, store: postgres({ url: process.env.DATABASE_URL! }) }),
});A cópia roda no processo do app, como no servidor. clickhouse() aceita estas opções além de url e store.
| Opção | Padrão | O que faz |
|---|---|---|
maxQueries |
2 | Quantas consultas de relatório vão ao ClickHouse ao mesmo tempo, no máximo; as outras esperam a vez. As leituras e gravações de cada hit têm filas próprias. |
queryTimeout |
120000 | O tempo máximo de uma consulta de relatório, em milissegundos. 0 significa sem limite. |
copyInBackground |
true | Com false, a cópia fica para store.copy(), rodado por um script seu. Os últimos dois dias são copiados antes de o armazenamento ficar pronto de qualquer forma. |
O que muda
No ClickHouse, os relatórios leem as próprias visitas, então não há agregações diárias para montar. Visões sem filtro de um período longo levam um pouco mais do que com as agregações, cerca de 0,4 segundo para um ano de um milhão de visitas, e as filtradas ficam muito mais rápidas.
Os visitantes de vários dias são contados a partir das visitas, enquanto as agregações somam os de cada dia. As duas contas só diferem quando uma visita passa da meia-noite e a mesma pessoa volta no dia seguinte, então o ClickHouse pode mostrar alguns a menos.
Visitantes são contados com exatidão até cerca de 4.000 em cada número e estimados acima disso, com margem de cerca de 1%. Uma contagem exata dos visitantes de um ano para cada página de um site grande precisa de vários gigabytes de memória, e a estimativa precisa de uma fração disso. Uma estimativa nunca mostra mais visitantes do que as visitas, visualizações ou conversões cujos visitantes ela conta.
Nada novo é guardado. As colunas são as mesmas que os outros bancos guardam, sem endereço IP e sem o user agent completo, e os sais diários continuam no SQLite, no Postgres ou no MySQL. Uma visita apagada some dos relatórios na hora, e o ClickHouse reescreve em até um dia as partes da tabela que a guardavam, então ela sai do disco também.