Toda la documentaciónBuscar

Empezar

  1. 01Primeros pasos
  2. 02Instalación
  3. 03Seguimiento

Funciones

  1. 04El panel
  2. 05Objetivos
  3. 06Enlaces cortos
  4. 07Fuentes y agentes de IA
  5. 08Informes por email
  6. 09Comprobación programada
  7. 10Pregunta a tu IA

Referencia

  1. 11Rendimiento
  2. 12Configuración
  3. 13API HTTP

Plataformas

  1. 14Servidor independiente
  2. 15ClickHouse
  3. 16PHP
  4. 17WordPress
  5. 18Drupal
  6. 19Craft CMS
  7. 20Webflow
  8. 21Python
  9. 22Rails
  10. 23Ruby
  11. 24Go
  12. 25Java
  13. 26.NET
  14. 27Elixir
  15. 28Rust

Confianza

  1. 29Privacidad

Plataformas

ClickHouse

Guarda las visitas y los eventos del servidor independiente en ClickHouse para tener informes filtrados rápidos en sitios grandes, y pasa una instalación existente sin interrupciones.

El servidor independiente puede guardar sus visitas y eventos en ClickHouse, una base de datos hecha para leer millones de filas a la vez. Todo lo demás se queda donde está, en SQLite, Postgres o MySQL, desde los sitios, los objetivos, los embudos y los enlaces hasta las cuentas y los ajustes. Solo se mueven las dos tablas más grandes.

Cuándo merece la pena

SQLite, Postgres y MySQL responden a un panel sin filtro a partir de las agregaciones diarias, así que siguen siendo rápidos con cualquier tamaño. Un filtro tiene que leer las visitas que elige, y ahí es donde ayuda ClickHouse. Con un año de un sitio con mucho tráfico, un panel filtrado por una página se abre en 0,65 segundos, mientras que las demás bases tardan de 9 a 24 segundos. La página de rendimiento tiene todas las mediciones.

Merece la pena a partir de unos pocos millones de visitas al mes, o cuando se filtran a menudo periodos largos. Un sitio pequeño gana poco y tiene una base de datos más que mantener.

ClickHouse necesita al menos 4 GB de memoria, y 8 GB para un año de 10 millones de visitas. Runlight necesita la versión 25.8 o posterior, en tu propio servidor o en ClickHouse Cloud.

Hasta dónde llega

Estas son mediciones en una sola máquina, un Apple M4 Max con 14 núcleos, con ClickHouse 25.8 en Docker y un servidor de Runlight al lado. Cada sitio tenía un año de tráfico sintético, con unos cuatro eventos por visita. Cada tiempo abarca todas las peticiones que hace el panel al abrirse, enviadas a la vez, sin nada más escribiendo. Tu hardware y tu tráfico darán otras cifras, así que tómalas como punto de partida y mide las tuyas.

Visitas al año Memoria de ClickHouse Últimos 7 días Últimos 30 días Últimos 12 meses 12 meses, con filtro
10 millones 8 GB 0,14 s 0,4 s 2,8 s 2,2 a 2,7 s
180 millones 8 GB 0,9 s 3,7 s 38 a 40 s 30 a 55 s

180 millones de visitas al año son unos 10 millones de visitantes únicos al mes. A ese tamaño, 14 GB de memoria no fueron más rápidos que 8 GB, porque ClickHouse estaba ocupado en todos los núcleos, no corto de memoria, pero 8 GB va justo: en dos pasadas de una docena, con otro trabajo al lado, a algunos recuadros de 12 meses se les acabó la memoria. Dale 14 GB o más para tener margen. Con 4 GB, un año de 10 millones de visitas abría en 7 y 30 días, pero los recuadros de canal, país, dispositivo y campaña fallaban en 12 meses.

Cada evento en ClickHouse lleva la fuente, la campaña, el lugar y el dispositivo de su visita, así que un filtro sobre uno de ellos lee solo los eventos. Un filtro sobre una página lee cada página vista del periodo para encontrar las visitas que la vieron, lo que la convierte en la vista más lenta sobre un año del sitio más grande. Los periodos cortos son rápidos, con filtro o sin él.

Disco

ClickHouse usó unos 0,4 GB por cada millón de visitas con sus eventos, comprimidos: 3,7 GB para 10 millones y 75 GB para 180 millones. Las visitas con más eventos ocupan más.

Hits

Un servidor registró 600 hits por segundo y respondió a cada uno en menos de 0,3 segundos, con ClickHouse ocupado en unos 9 núcleos. A 800 por segundo, ClickHouse estaba ocupado en los 14, y los hits esperaban y agotaban el tiempo de espera. Un año de 180 millones de visitas con cuatro eventos cada una da una media de unos 25 hits por segundo, así que un servidor tiene margen para picos de varias veces la media. Para más, ejecuta varias copias del servidor detrás de un balanceador de carga.

Cuando ClickHouse no responde, está ocupado o reiniciándose, el servidor guarda cada hit en SQLite, Postgres o MySQL, sin dirección ni user agent, y los envía en el orden en que llegaron en cuanto ClickHouse vuelve a responder. Mientras haya hits esperando, los nuevos se ponen detrás, para que los de un visitante sigan en orden. Un hit espera un día como mucho, y esperan dos millones como mucho, cerca de un gigabyte. Pasado cualquiera de los dos, los hits se pierden y quedan en el registro como «could not record an event», así que vigila el registro y la salud de ClickHouse.

Configurarlo

Pon en CLICKHOUSE_URL el ClickHouse que quieras usar, con su usuario, su contraseña y el nombre de una base de datos, y arranca el servidor.

bash

CLICKHOUSE_URL=https://runlight:password@clickhouse.example.com:8443/runlight npx @runlight/server

El servidor crea la base de datos si aún no existe, crea sus tablas y anota en el log adónde van las visitas. Si no puede llegar a ClickHouse, el servidor se detiene y dice por qué, en lugar de perder visitas.

Usa https:// cuando ClickHouse esté en otra máquina, porque la contraseña va con cada petición. Dentro de una misma red de Docker, como abajo, basta con http://. El servidor avisa al arrancar si la dirección empieza por http:// y podría pasar por internet.

El usuario de ClickHouse necesita estos permisos sobre su base de datos. Solo necesita además CREATE DATABASE si la base de datos aún no existe.

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;

La segunda línea es opcional. Con ella, un borrado grande (un sitio, o visitas antiguas pasada su retención) se ejecuta en segundo plano en ClickHouse mientras el servidor lo espera, tarde lo que tarde. Sin ella, el servidor espera en la petición, que se rinde a los cinco minutos.

Con Docker Compose

Esto ejecuta Runlight y ClickHouse uno al lado del otro, cada uno con sus datos en un volumen.

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:

Aquí solo se llega a ClickHouse desde dentro de la red de Compose, así que no necesita un puerto propio.

Con ClickHouse Cloud

Crea un servicio y copia su dirección HTTPS y su contraseña desde Connect. La dirección va en CLICKHOUSE_URL, con el usuario, la contraseña y el nombre de una base de datos añadidos.

bash

CLICKHOUSE_URL=https://default:password@abc123.eu-west-1.aws.clickhouse.cloud:8443/runlight

Pasar una instalación existente

Añade CLICKHOUSE_URL a un servidor que ya tiene visitas y reinícialo. En ese primer arranque copia a ClickHouse las visitas de los dos últimos días antes de contar nada, así que una visita en curso en ese momento continúa. En un sitio con mucho tráfico eso tarda unos segundos. Desde entonces, cada visita va a ClickHouse.

El resto se copia en segundo plano, de lo más reciente a lo más antiguo, un día cada vez, así que los informes que más se miran están bien casi enseguida. Un millón de visitas tarda menos de un minuto en un portátil. Hasta que termina, el panel dice hasta dónde llegan por ahora los informes y se rechazan las importaciones de visitas y de enlaces, porque una importación en ese momento podría contar dos veces las mismas visitas.

La copia anota hasta dónde ha llegado después de cada día, así que tras un reinicio o una conexión cortada sigue desde ahí sin contar ninguna visita dos veces. Cuando varias copias del servidor comparten una base de datos, una de ellas hace la copia y las demás siguen contando. Si esa se detiene, otra toma el relevo en menos de dos minutos.

Para tenerlo todo hecho antes de que el servidor reciba visitas, detén el servidor, pon CLICKHOUSE_URL y ejecuta tú la copia. Después arranca el servidor.

bash

npx @runlight/server clickhouse copy

En Docker, ejecuta los comandos de esta página dentro del contenedor, como el comando password.

bash

docker exec runlight node node_modules/.bin/runlight.sh clickhouse status

Ver hasta dónde ha llegado

bash

npx @runlight/server clickhouse status

Dice cuántas visitas y eventos tiene ClickHouse, hasta dónde ha llegado la copia y si las tablas antiguas todavía tienen visitas.

Vaciar las tablas antiguas

Cuando termina la copia, las visitas antiguas se quedan en SQLite, Postgres o MySQL, y nada las lee. Vacíalas cuando estés contento con ClickHouse.

bash

npx @runlight/server clickhouse drop-old

Dice lo que va a borrar y te pide que escribas yes. Añade --yes para saltarte la pregunta en un script. Se niega mientras la copia sigue en marcha.

Solo vacía las visitas que empezaron antes de que ClickHouse tomara el relevo, que están todas en ClickHouse. Un servidor que sigue funcionando sin CLICKHOUSE_URL después del cambio, como uno que aún no se ha reiniciado, escribe sus visitas en las tablas antiguas, donde ClickHouse nunca las ve. status las cuenta, y drop-old las deja donde están.

Volver atrás

Para dejar de usar ClickHouse, detén todos los servidores y cópialo todo de vuelta.

bash

npx @runlight/server clickhouse copy --back

Esto sustituye las visitas y los eventos de SQLite, Postgres o MySQL por todo lo que tiene ClickHouse, incluidas las visitas desde el cambio, y después vacía ClickHouse. Antes pregunta, y se niega mientras algún servidor siga recibiendo visitas. Un servidor que se detuvo sin apagarse bien cuenta como desaparecido un minuto y medio después de su última señal. Luego quita CLICKHOUSE_URL y arranca el servidor, que vuelve a crear las agregaciones diarias mientras funciona. Si más adelante vuelves a activar ClickHouse, se copia todo de nuevo.

Si se detiene a medias, ejecútalo otra vez. En cuanto la base de datos antigua lo tiene todo, lo anota antes de vaciar ClickHouse, así que una segunda ejecución termina el trabajo en lugar de copiar desde un ClickHouse vacío. Hasta que termina, ningún servidor arranca con CLICKHOUSE_URL.

En tu propia aplicación

Una aplicación Node que ejecuta Runlight como biblioteca puede hacer lo mismo. Envuelve el almacenamiento que ya tiene.

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! }) }),
});

La copia se ejecuta en el proceso de la aplicación, igual que en el servidor. clickhouse() acepta estas opciones además de url y store.

Opción Por defecto Qué hace
maxQueries 2 Cuántas consultas de informes van a la vez a ClickHouse como mucho; las demás esperan su turno. Las lecturas y escrituras de cada hit tienen sus propios carriles.
queryTimeout 120000 Lo máximo que puede durar una consulta de informe, en milisegundos. 0 significa sin límite.
copyInBackground true Con false, la copia queda para store.copy(), ejecutado desde un script tuyo. Los dos últimos días se copian antes de que el almacenamiento esté listo en cualquier caso.

Qué cambia

Los informes leen las propias visitas en ClickHouse, así que no hay agregaciones diarias que crear. Las vistas sin filtro de un periodo largo tardan un poco más que con agregaciones, unos 0,4 segundos para un año con un millón de visitas, y las filtradas son mucho más rápidas.

Los visitantes de varios días se cuentan a partir de las visitas, mientras que las agregaciones suman los de cada día. Los dos números solo difieren cuando una visita pasa de medianoche y la misma persona vuelve al día siguiente, así que ClickHouse puede mostrar unos pocos menos.

Los visitantes se cuentan con exactitud hasta unos 4.000 en cada número, y por encima se estiman, con un margen de alrededor del 1 %. Un recuento exacto de los visitantes de un año para cada página de un sitio grande necesita varios gigabytes de memoria, y la estimación necesita una fracción de eso. Una estimación nunca muestra más visitantes que las visitas, páginas vistas o conversiones de las que cuenta los visitantes.

No se guarda nada nuevo. Las columnas son las mismas que guardan las otras bases de datos, sin dirección IP ni agente de usuario completo, y las sales diarias se quedan en SQLite, Postgres o MySQL. Una visita borrada desaparece de los informes enseguida, y ClickHouse reescribe en menos de un día las partes de la tabla que la tenían, así que también sale del disco.