Jitsu je open-source platforma pre zber eventov a alternatíva k Segmentu, ktorá vám pomáha budovať robustné dátové pipelines z vašich aplikácií do data warehouse. Na rozdiel od spravovaných riešení vám Jitsu dáva plnú kontrolu nad vašimi dátami a zároveň poskytuje enterprise-grade funkcie pre správu schém, transformácie a garancie doručenia. Podporovaný Y Combinator (S20) a licencovaný pod MIT, Jitsu je navrhnutý pre moderné dátové tímy, ktoré potrebujú real-time dátové pipelines.

Tento sprievodca pokrýva všetko, čo potrebujete na nasadenie Jitsu a vybudovanie production-ready event pipelines.

Čo je Jitsu?

Jitsu je moderná platforma pre zber a smerovanie eventov s niekoľkými kľúčovými schopnosťami:

  • Zber eventov: SDK pre web, mobilné a server-side sledovanie eventov
  • Real-time spracovanie: Transformujte a obohacujte eventy počas ich prietoku pomocou JavaScript funkcií
  • Viacero destinácií: Smerujte eventy do warehouses (ClickHouse, BigQuery, Snowflake, Postgres, Redshift), analytických nástrojov a vlastných endpointov
  • Správa schém: Automatická inferencia schém s JSON flatteningom a detekciou typov
  • Self-hosted: Prevádzkujte na vlastnej infraštruktúre s plnou kontrolou nad dátami, alebo použite Jitsu Cloud (zadarmo do 200k eventov/mesiac)
  • Identity stitching: Automatická real-time konštrukcia identity grafu

Prehľad architektúry

Jitsu 2.0 pozostáva z niekoľkých špecializovaných komponentov:

  • Console: Webové UI pre konfiguráciu a monitoring, postavené s Next.js
  • Ingest: API pre ingesciu eventov, ktoré prijíma a validuje prichádzajúce eventy, napísané v Go
  • Rotor: Engine pre vykonávanie funkcií, ktorý spúšťa JavaScript transformácie, postavený s Node.js
  • Bulker: Služba pre batch loading do warehouse destinácií s automatickou správou schém, napísaná v Go
  • Syncctl: Služba orchestrácie konektorov pre spúšťanie source syncs (vyžaduje Kubernetes)

Podporné služby zahŕňajú PostgreSQL (úložisko konfigurácie), Redis alebo MongoDB (caching a identity stitching) a voliteľne Kafka (message queuing pre high-volume nasadenia).

Možnosti nasadenia

Jitsu je možné nasadiť niekoľkými spôsobmi v závislosti od vašej škály a prevádzkových požiadaviek.

Docker Compose (Development/Malá škála)

Najrýchlejší spôsob inštalácie Jitsu je pomocou Docker Compose:

# Klonovanie repozitára
git clone --depth 1 https://github.com/jitsucom/jitsu
cd jitsu/docker

# Kopírovanie a konfigurácia environment premenných
cp .env.example .env
# Upravte súbor .env s vašimi nastaveniami

# Spustenie Jitsu
docker compose up -d

Kľúčové environment premenné na konfiguráciu v .env:

# Povinné tokeny (vygenerujte unikátne hodnoty)
CONSOLE_TOKEN=your-console-token
BULKER_TOKEN=your-bulker-token

# Databázové credentials
POSTGRES_PASSWORD=your-postgres-password
REDIS_PASSWORD=your-redis-password

# Voliteľné: seed admin používateľ
SEED_USER_EMAIL=admin@example.com
SEED_USER_PASSWORD=your-admin-password

Predvolené Docker Compose nastavenie zahŕňa všetky potrebné služby: Console, Ingest, Rotor, Bulker, PostgreSQL, Redis a voliteľne Kafka a ClickHouse.

Kubernetes (Produkcia)

Pre produkčné nasadenia môže Jitsu bežať na Kubernetes. Všimnite si, že neexistuje oficiálny Helm chart udržiavaný Jitsu. Existujú však komunitou udržiavané možnosti:

# Komunitný Helm chart (stafftastic/jitsu-chart)
helm install jitsu oci://registry-1.docker.io/stafftasticcharts/jitsu \
  --namespace analytics \
  --create-namespace \
  -f values.yaml

Alternatívne môžete nasadiť jednotlivé komponenty pomocou oficiálnych Docker obrazov:

  • jitsucom/console - Management UI
  • jitsucom/ingest - Event ingestion API
  • jitsucom/rotor - Vykonávanie funkcií
  • jitsucom/bulker - Warehouse loading
  • jitsucom/syncctl - Orchestrácia konektorov

Kľúčové produkčné úvahy:

  • Použite spravované databázy (RDS, Cloud SQL) pre PostgreSQL
  • Použite spravovaný Redis (ElastiCache, Cloud Memorystore) alebo MongoDB Atlas
  • Nakonfigurujte horizontálne škálovanie podov na základe CPU/pamäte
  • Nastavte ingress s TLS termináciou
  • Syncctl vyžaduje Kubernetes cluster na spúšťanie connector sync jobov

Jitsu Cloud

Spravovaná cloudová verzia je dostupná na use.jitsu.com:

  • Zadarmo do 200,000 eventov mesačne
  • Zahŕňa bezplatnú ClickHouse inštanciu
  • Žiadna správa infraštruktúry

Dimenzovanie zdrojov

  • Malé (< 1M eventov/deň): 2 CPU, 4GB RAM na službu
  • Stredné (1-10M eventov/deň): 4 CPU, 8GB RAM, 2+ repliky
  • Veľké (10M+ eventov/deň): 8 CPU, 16GB RAM, 4+ repliky s autoscalingom, odporúča sa Kafka

Integrácia SDK

Jitsu poskytuje SDK pre viacero platforiem. Všimnite si, že Jitsu 2.0 používa iné balíčky ako Jitsu Classic.

JavaScript SDK (Web) - Jitsu 2.0

// Inštalácia cez npm
npm install @jitsu/js

// Inicializácia klienta
import { jitsuAnalytics } from '@jitsu/js';

const jitsu = jitsuAnalytics({
  host: 'https://your-jitsu-instance.com',
  writeKey: 'your-write-key',
  debug: process.env.NODE_ENV === 'development'
});

// Sledovanie eventov
jitsu.track('Button Clicked', {
  button_id: 'signup-cta',
  page_path: window.location.pathname
});

// Identifikácia používateľov
jitsu.identify('user_123', {
  email: 'user@example.com',
  plan: 'pro',
  created_at: '2025-01-15T10:30:00Z'
});

// Sledovanie zobrazení stránok
jitsu.page({
  title: document.title,
  url: window.location.href,
  referrer: document.referrer
});

HTML Snippet (Bez build stepu)

<script src="https://your-jitsu-instance.com/s/lib.js"
        data-write-key="your-write-key"></script>
<script>
  // jitsu je dostupný globálne
  jitsu.track('Page Loaded');
</script>

React integrácia

// Inštalácia balíčkov
npm install @jitsu/js @jitsu/react

// Použitie React providera
import { JitsuProvider, useJitsu } from '@jitsu/react';
import { jitsuAnalytics } from '@jitsu/js';

const jitsuClient = jitsuAnalytics({
  host: 'https://your-jitsu-instance.com',
  writeKey: 'your-write-key'
});

function App() {
  return (
    <JitsuProvider client={jitsuClient}>
      <YourApp />
    </JitsuProvider>
  );
}

function SignupButton() {
  const { track } = useJitsu();

  const handleClick = () => {
    track('Signup Button Clicked', {
      location: 'header',
      variant: 'primary'
    });
  };

  return <button onClick={handleClick}>Sign Up</button>;
}

Server-Side SDK (Node.js)

// Balíček @jitsu/js je izomorfný a funguje v Node.js
import { jitsuAnalytics } from '@jitsu/js';

const jitsu = jitsuAnalytics({
  host: 'https://your-jitsu-instance.com',
  writeKey: 'server-write-key'
});

// Sledovanie server-side eventov
async function trackPurchase(userId, order) {
  await jitsu.track('Order Completed', {
    user_id: userId,
    order_id: order.id,
    total: order.total,
    currency: order.currency,
    items: order.items.map(item => ({
      product_id: item.productId,
      quantity: item.quantity,
      price: item.price
    }))
  });
}

HTTP API (Akýkoľvek jazyk)

# Priame HTTP API volanie
curl -X POST https://your-jitsu-instance.com/api/s/s2s/track \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: your-write-key" \
  -d '{
    "type": "track",
    "event": "API Event",
    "userId": "user_123",
    "properties": {
      "source": "backend",
      "value": 42
    },
    "context": {
      "library": {
        "name": "http-api",
        "version": "1.0.0"
      }
    }
  }'

Segment Proxy Mode

Jitsu môže fungovať ako Segment-kompatibilný endpoint, čo vám umožňuje migrovať zo Segmentu bez zmeny existujúcej implementácie SDK.

Konfigurácia destinácií

Jitsu podporuje viacero typov destinácií konfigurovaných cez Console UI alebo API.

Data Warehouse destinacie

ClickHouse (odporúča sa pre high-volume analytiku):

  • Natívna podpora batch loadingu
  • Automatická tvorba tabuliek a evolúcia schémy
  • Bezplatná ClickHouse inštancia zahrnutá v Jitsu Cloud

BigQuery:

  • Streaming a batch módy
  • Automatické partitioning podľa času eventu
  • Podpora clusteringu pre optimalizáciu queries

PostgreSQL:

  • COPY príkaz pre efektívny batch loading
  • Automatická správa schémy
  • Vhodné pre menšie nasadenia

Snowflake:

  • Stage-based loading
  • Podpora automatického škálovania warehouse

Amazon Redshift:

  • S3-based batch loading
  • Inferencia a správa schémy

Destinacie analytických nástrojov

  • Amplitude: Preposielanie eventov pre produktovú analytiku
  • Mixpanel: Real-time event streaming
  • Google Analytics 4: Server-side measurement protocol
  • Facebook Conversion API: Server-side conversion tracking
  • HubSpot: CRM event integrácia

Vlastné webhooky

Posielajte eventy na akýkoľvek HTTP endpoint s konfigurovateľným batchingom, hlavičkami a retry politikami.

Jitsu Functions (Transformácie)

Jitsu Functions vám umožňujú transformovať, filtrovať alebo obohacovať eventy pomocou JavaScriptu predtým, než dosiahnu destinacie.

Štruktúra funkcie

// Základná štruktúra funkcie
export default async function transform(event, context) {
  // Prístup k context utilitám
  const { log, props, store, geo, ua, fetch } = context;

  // Filter: vráťte "drop" na zahodenie eventu
  if (event.properties?.internal === true) {
    return "drop";
  }

  // Obohatenie o geo a user agent dáta
  event.properties = event.properties || {};
  event.properties.country = geo?.country;
  event.properties.browser = ua?.browser?.name;
  event.properties.processed_at = new Date().toISOString();

  // Vráťte modifikovaný event
  return event;
}

Context objekt

Context objekt poskytuje niekoľko utilít:

  • log: Logovacia funkcia pre debugging
  • props: Vlastné properties nakonfigurované pre funkciu
  • store: Perzistentné key-value úložisko medzi volaniami funkcií
  • geo: Geolokačné dáta na základe IP adresy
  • ua: Parsované informácie o user agentovi
  • fetch: HTTP klient pre externé API volania

Bežné use cases

// PII Maskovanie
export default async function transform(event, { log }) {
  if (event.properties?.email) {
    event.properties.email_domain = event.properties.email.split('@')[1];
    delete event.properties.email;
  }
  return event;
}

// Normalizácia eventov
export default async function transform(event) {
  // Normalizácia typov eventov
  if (['page_view', 'pageview', 'pageView'].includes(event.type)) {
    event.type = 'page';
  }
  return event;
}

// Zmena cieľovej tabuľky
export default async function transform(event) {
  // Smerovanie rôznych typov eventov do rôznych tabuliek
  if (event.type === 'purchase') {
    event.JITSU_TABLE_NAME = 'purchases';
  }
  return event;
}

// Použitie perzistentného úložiska
export default async function transform(event, { store }) {
  const userId = event.userId;
  const existingUser = await store.get(`user:${userId}`);

  if (!existingUser) {
    await store.set(`user:${userId}`, { first_seen: new Date().toISOString() });
    event.properties.is_new_user = true;
  }

  return event;
}

Podpora NPM balíčkov

Funkcie môžu importovať NPM balíčky. Použite Jitsu CLI na bundling a nasadenie:

# Vytvorenie nového projektu funkcie
npx create-jitsu-app --name my-function

# Build a nasadenie
npm run build
jitsu-cli login
npm run deploy

Správa schém

Jitsu poskytuje automatickú správu schém cez svoj Bulker komponent.

Automatická inferencia schém

  • JSON Flattening: Vnorené objekty ako {"a": {"b": 1}} sa stanú stĺpcami a_b
  • Detekcia typov: Typy stĺpcov sú odvodené z JSON hodnôt
  • Evolúcia schémy: Nové stĺpce sú pridávané automaticky keď sa objavia nové polia
  • Spracovanie polí: Polia sú ukladané ako JSON alebo array typy v závislosti od destinacie

Explicitné type hinty

// Použite prefix __sql_type_ pre explicitné typovanie
{
  "revenue": 99.99,
  "__sql_type_revenue": "decimal(10,2)",
  "description": "A short text",
  "__sql_type_description": "varchar(500)"
}

Pomenovanie tabuliek

  • Predvolený názov tabuľky je events
  • Prepíšte per-event pomocou JITSU_TABLE_NAME property
  • Nakonfigurujte šablóny názvov tabuliek v nastaveniach destinacie

Monitoring a observabilita

Produkčné nasadenia vyžadujú komplexný monitoring pre zabezpečenie spoľahlivosti.

Console Dashboard

Jitsu Console poskytuje vstavaný monitoring:

  • Live Events prehliadač pre real-time debugging
  • Metriky objemu eventov podľa zdroja a destinacie
  • Logy vykonávania funkcií
  • Sledovanie chýb a alerty

Health endpointy

# Liveness probe
GET /health/live

# Readiness probe
GET /health/ready

# API status
GET /api/status

Prometheus metriky

Jitsu vystavuje Prometheus-kompatibilné metriky na /metrics:

  • Počítadlá prijatých/spracovaných/zlyhaných eventov
  • Histogramy latencie spracovania
  • Veľkosti front destinácií
  • Metriky vykonávania funkcií

Logovanie

  • Nastavte úroveň logov cez environment premennú (LOG_LEVEL=info|debug|warn|error)
  • JSON-formátované logy pre jednoduchú analýzu
  • Correlation IDs pre sledovanie požiadaviek

Spracovanie chýb a spoľahlivosť

Garancie doručenia

  • At-least-once doručenie: Eventy sú opakované pokým nie sú úspešne doručené
  • Kafka buffering: High-volume nasadenia používajú Kafka pre trvalé message queuing
  • Lokálny buffering: Eventy sú bufferované lokálne ak sú destinacie dočasne nedostupné

Retry správanie

  • Automatické retry s exponenciálnym backoffom
  • Konfigurovateľný počet pokusov a oneskorení
  • Retryable chyby (timeouty, rate limity) vs permanentné zlyhania

Dead Letter spracovanie

Eventy, ktoré zlyhajú pri všetkých pokusoch o opakovanie, môžu byť:

  • Zalogované pre manuálnu inšpekciu
  • Odoslané do separátnej destinacie pre analýzu
  • Prehrané po oprave podkladového problému

Bezpečnostné úvahy

Autentifikácia

  • Použite separátne write keys pre rôzne zdroje (web, mobilné, server)
  • Write keys môžu byť scoped na špecifické destinacie
  • Console prístup je chránený autentifikáciou používateľov
  • API tokeny pre programatický prístup

Ochrana súkromia dát

  • Použite Functions na maskovanie alebo odstránenie PII pred uložením
  • Podpora IP anonymizácie pre GDPR compliance
  • Self-hosted nasadenie uchováva všetky dáta na vašej infraštruktúre
  • Nakonfigurujte politiky uchovávania dát podľa destinacie

Sieťová bezpečnosť

  • TLS šifrovanie pre všetky pripojenia
  • Podpora vlastnej domény pre minimalizáciu dopadu ad-blockerov
  • Možnosti VPC nasadenia pre privátne siete

Migrácia zo Segmentu

Jitsu je navrhnutý ako alternatíva k Segmentu s migračnými cestami:

Segment Proxy Mode

Nasmerujte váš existujúci Segment SDK na Jitsu Segment-kompatibilný endpoint:

analytics.load("your-jitsu-write-key", {
  integrations: {
    "Segment.io": {
      apiHost: "your-jitsu-instance.com/api/s/segment"
    }
  }
});

SDK migrácia

Nahraďte Segment SDK Jitsu SDK — API je z veľkej časti kompatibilné:

  • analytics.track() → jitsu.track()
  • analytics.identify() → jitsu.identify()
  • analytics.page() → jitsu.page()

Zhrnutie

Budovanie event pipelines s Jitsu poskytuje:

  1. Vlastníctvo dát: Plná kontrola nad vašimi event dátami s možnosťou self-hostingu
  2. Flexibilita: Smerovanie do akejkoľvek destinacie s výkonnými JavaScript transformáciami
  3. Spoľahlivosť: At-least-once doručenie s automatickými retry a bufferingom
  4. Škálovateľnosť: Zvládnutie miliónov eventov denne s horizontálnym škálovaním
  5. Nákladová efektívnosť: MIT-licencovaný, vyhnutie sa per-event pricingu spravovaných riešení
  6. Developer experience: Čisté API, komplexné SDK a debugovacie nástroje

Začnite s Docker Compose pre development, migrujte na Kubernetes pre produkciu, alebo použite Jitsu Cloud pre plne spravovaný zážitok. So správnym monitoringom a governance schém sa Jitsu stane základom spoľahlivej, privacy-respecting analytickej infraštruktúry.

Zdroje