Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.kodus.io/llms.txt

Use this file to discover all available pages before exploring further.

O analytics worker é um add-on exclusivo do Enterprise. Ele roda o cron de ingestão que alimenta os dashboards do Cockpit (métricas tipo DORA, ciclo de vida de PR, classifier de PR baseado em LLM).
O instalador padrão não inclui esse worker. Deploys self-hosted da versão community não precisam dele e essas vars são filtradas do .env.example padrão. Pare por aqui a menos que você tenha uma licença self-hosted Enterprise e queira os relatórios do Cockpit.

​
O que ele faz

Um processo Node separado rodando a mesma imagem do worker (kodus-ai-worker), selecionado no boot via WORKER_ROLE=analytics. Dois crons disparam desse processo e somente dele:
  • Ingestão (ANALYTICS_INGESTION_CRON, default */30 * * * *) — lê pull requests e sessões de review do Mongo + do Postgres OLTP, projeta no schema analytics.
  • Classifier (ANALYTICS_CLASSIFIER_CRON, default */15 * * * *) — chama uma LLM pra classificar cada PR (feature/bugfix/refactor/etc).
Isolar do worker principal mantém o event loop de code review livre de queries de ingestão longas.

​
Topologia

O warehouse de analytics é um schema Postgres, não um banco separado. Dois layouts suportados:
  • Postgres compartilhado (recomendado para self-hosted) — deixe ANALYTICS_PG_DB_HOST vazio. O config loader cai no fallback das vars API_PG_DB_* e cria o schema analytics na mesma instância. Um banco só pra fazer backup e operar.
  • Postgres dedicado — preencha o bloco ANALYTICS_PG_DB_* apontando pra outra instância. Use isso quando quer queries analíticas totalmente isoladas do write path do OLTP.

​
Habilitando no self-hosted Enterprise

​
1. Adicione o serviço ao docker-compose.yml

worker-analytics:
    image: ghcr.io/kodustech/kodus-ai-worker:latest
    platform: linux/amd64
    container_name: kodus-worker-analytics
    environment:
        - ENV=production
        - NODE_ENV=production
        - WORKER_ROLE=analytics
    networks:
        - shared-network
        - kodus-backend-services
    restart: unless-stopped
    env_file:
        - .env
    depends_on:
        - db_kodus_postgres
        - db_kodus_mongodb
        - rabbitmq
A imagem é idêntica à do serviço worker — só WORKER_ROLE=analytics muda pra modo ingestão.

​
2. Adicione o bloco de analytics ao .env

Postgres compartilhado (recomendado): 
# ANALYTICS_PG_DB_HOST vazio → loader reusa API_PG_DB_* e cria o
# schema `analytics` na instância principal.
ANALYTICS_PG_DB_HOST=
ANALYTICS_PG_DB_SCHEMA=analytics

# Cron schedules (UTC).
ANALYTICS_INGESTION_CRON=*/30 * * * *
ANALYTICS_CLASSIFIER_CRON=*/15 * * * *
Postgres dedicado: 
ANALYTICS_PG_DB_HOST=seu-host-de-analytics
ANALYTICS_PG_DB_PORT=5432
ANALYTICS_PG_DB_USERNAME=analytics
ANALYTICS_PG_DB_PASSWORD=...
ANALYTICS_PG_DB_DATABASE=kodus_analytics
ANALYTICS_PG_DB_SCHEMA=analytics

ANALYTICS_INGESTION_CRON=*/30 * * * *
ANALYTICS_CLASSIFIER_CRON=*/15 * * * *

​
3. Boot — migrations rodam automaticamente

O container worker-analytics compartilha o mesmo prod-entrypoint.sh do api/worker/webhooks. Com RUN_MIGRATIONS=true (default do installer), as migrations do warehouse de analytics (yarn analytics:migration:run:prod) rodam no primeiro boot, criando o schema analytics e suas tabelas.

​
Referência

VariávelDescriçãoDefault
WORKER_ROLETem que ser analytics nesse container.obrigatório
ANALYTICS_PG_DB_HOSTHost do Postgres de analytics. Vazio → reusa o Postgres principal.vazio
ANALYTICS_PG_DB_PORTPorta do Postgres de analytics.5432
ANALYTICS_PG_DB_USERNAMEUsuário do Postgres de analytics. Vazio → reusa API_PG_DB_USERNAME.vazio
ANALYTICS_PG_DB_PASSWORDSenha do Postgres de analytics. Vazio → reusa API_PG_DB_PASSWORD.vazio
ANALYTICS_PG_DB_DATABASEBanco do Postgres de analytics. Vazio → reusa API_PG_DB_DATABASE.vazio
ANALYTICS_PG_DB_SCHEMANome do schema das tabelas do warehouse.analytics
ANALYTICS_PG_POOL_MAXLimite superior do pool do Postgres de analytics.5
ANALYTICS_INGESTION_CRONCron schedule da ingestão (UTC).*/30 * * * *
ANALYTICS_CLASSIFIER_CRONCron schedule do classifier de tipo de PR via LLM (UTC).*/15 * * * *

​
Pausando a ingestão (avançado)

Pra parar a ingestão em runtime sem remover o container, defina ANALYTICS_INGESTION_DISABLED=true e/ou ANALYTICS_CLASSIFIER_DISABLED=true e reinicie o worker-analytics. O cron continua agendado mas cada tick faz short-circuit. Use isso pra triagem de incidente, não como config de longo prazo — essas vars são gerenciadas primariamente para cloud e podem não aparecer no template do installer.

​
Verificando que está funcionando

Após o boot, acompanhe os logs do analytics worker: 
docker compose logs -f worker-analytics
Você deve ver linhas como analytics ingestion done in NNNms — {...} a cada 30 minutos e analytics classifier done ... a cada 15 minutos. Se não, confirme que WORKER_ROLE=analytics está setado só nesse container (não no worker principal — esse tem que continuar code-review).