Files
skills/public/hanzo-insights.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

366 lines
24 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hanzo-insights</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/hanzo-insights.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hanzo-insights">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hanzo-insights.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>hanzo-insights</h1><p class="lede">Hanzo Insights is a full product analytics platform with product analytics, feature flags, session recording, A/B testing, heatmaps, LLM analytics, error tracking, surveys, web analytics, and a custom query language (InsightsQL).</p><h1>Hanzo Insights - Product Analytics Platform</h1>
<p><strong>Category</strong>: Hanzo Ecosystem <strong>Related Skills</strong>: <code>hanzo/hanzo-cloud.md</code>, <code>hanzo/hanzo-o11y.md</code>, <code>hanzo/hanzo-console.md</code></p>
<h2>Overview</h2>
<p>Hanzo Insights is a <strong>full product analytics platform</strong> with product analytics, feature flags, session recording, A/B testing, heatmaps, LLM analytics, error tracking, surveys, web analytics, and a custom query language (InsightsQL). Polyglot monorepo: Django/Python backend, React/TypeScript frontend, Rust high-performance services, Go livestream server. ClickHouse for event storage, PostgreSQL for metadata, Kafka for event streaming, Redis for caching. Self-hostable with Docker Compose or K8s.</p>
<h3>Why Hanzo Insights?</h3>
<ul><li><strong>Hanzo brand</strong>: Full product analytics suite under <code>@hanzo/</code> namespace</li><li><strong>40+ product modules</strong>: analytics, feature flags, experiments, session replay, error tracking, LLM analytics, surveys, web analytics, notebooks, workflows, data warehouse, CDP</li><li><strong>InsightsQL</strong>: Custom SQL-like query language (ANTLR grammar, Python + C++ parsers)</li><li><strong>Multi-language SDKs</strong>: JavaScript (<code>@hanzo/insights</code>), Node.js (<code>@hanzo/insights-node</code>), Python (<code>hanzo_insights</code>), Go (<code>insights-go</code>), Rust (<code>insights-rs</code>)</li><li><strong>Rust services</strong>: High-performance capture, feature-flag evaluation, webhook delivery, error symbolication (cymbal), Kafka dedup, person resolution</li><li><strong>MCP server</strong>: Model Context Protocol integration for AI agent access to analytics data</li><li><strong>CLI</strong>: Rust CLI (<code>insights-cli</code>) for queries, sourcemap uploads, endpoint management</li></ul>
<h3>Tech Stack</h3>
<ul><li><strong>Backend</strong>: Django 4.2 + DRF on Python 3.12 (Granian ASGI server)</li><li><strong>Frontend</strong>: React 18 + TypeScript + Kea state management + Vite + Tailwind</li><li><strong>Rust services</strong>: axum, rdkafka, sqlx, clickhouse-rs (workspace with 30+ crates)</li><li><strong>Livestream</strong>: Go service for real-time event streaming</li><li><strong>Query engine</strong>: InsightsQL (ANTLR4 grammar -&gt; Python3 + C++ targets)</li><li><strong>Databases</strong>: ClickHouse (events), PostgreSQL (metadata), Kafka (streaming), Redis (cache)</li><li><strong>Task queue</strong>: Celery + Temporal (batch exports, async workflows)</li><li><strong>Data pipelines</strong>: Dagster (orchestration), dlt (data loading)</li><li><strong>Build</strong>: pnpm workspace + Turborepo (JS), uv (Python), Cargo workspace (Rust)</li><li><strong>Package manager</strong>: pnpm 10.x, Node 24, Python 3.12.12, uv 0.10.x</li></ul>
<h3>OSS Base</h3>
<p>Repo: <code>hanzoai/insights</code>. License: MIT.</p>
<h2>When to use</h2>
<ul><li>Product analytics and event tracking for any application</li><li>Feature flag management and gradual rollouts</li><li>A/B testing / experimentation with statistical analysis</li><li>Session recording and user behavior replay</li><li>LLM/AI application observability and analytics</li><li>Error tracking with sourcemap support</li><li>Web analytics (privacy-first alternative to GA)</li><li>User surveys and feedback collection</li><li>Data warehouse querying (Snowflake, BigQuery, Postgres, S3)</li><li>Self-hosted analytics with full data ownership</li></ul>
<h2>Hard requirements</h2>
<ol><li><strong>ClickHouse</strong> for event storage (columnar analytics)</li><li><strong>PostgreSQL</strong> for metadata and Django ORM</li><li><strong>Kafka</strong> (Redpanda) for event streaming pipeline</li><li><strong>Redis</strong> for caching and task queues</li><li><strong>Object storage</strong> (Hanzo S3) for session recordings and batch exports</li></ol>
<h2>Quick reference</h2>
<p>| Item | Value | |------|-------| | Repo | <code>github.com/hanzoai/insights</code> | | License | MIT | | Dashboard | <code>https://insights.hanzo.ai</code> | | API | <code>https://insights.hanzo.ai/api/</code> | | CLI host | <code>https://insights.hanzo.ai</code> | | Python | 3.12.12 | | Node | &gt;=24 &lt;25 | | pnpm | 10.29.3 | | uv | ~0.10.2 |</p>
<h3>SDKs</h3>
<p>| Language | Package | Repo | |----------|---------|------| | JavaScript (browser) | <code>@hanzo/insights</code> v6.0.0 | in-repo <code>common/insights-js</code> | | JavaScript (lite) | <code>@hanzo/insights-lite</code> | in-repo <code>common/insights-js-lite</code> | | Node.js | <code>@hanzo/insights-node</code> v6.0.0 | in-repo <code>common/insights-node</code> | | Python | <code>hanzo_insights</code> | <code>hanzoai/insights-python</code> | | Go | <code>github.com/hanzoai/insights-go</code> | <code>hanzoai/insights-go</code> | | Rust | <code>insights-rs</code> | <code>hanzoai/insights-rs</code> |</p>
<h2>Monorepo structure</h2>
<pre><code>insights/
insights/ # Django app (Python backend)
api/ # REST API views (DRF)
insightsql/ # Query language (ANTLR grammar + interpreter)
models/ # Django models
clickhouse/ # ClickHouse query builders
session_recordings/
heatmaps/
batch_exports/
cdp/ # Customer Data Platform
llm/ # LLM integration helpers
warehouse/ # Data warehouse connectors
tasks/ # Celery tasks
temporal/ # Temporal workflow definitions
frontend/ # React + TypeScript (Vite, Kea, Tailwind)
src/
@hanzo/ # Shared frontend packages
products/ # Product modules (each has backend/ + frontend/)
product_analytics/
feature_flags/
experiments/
replay/ # Session recording
error_tracking/
llm_analytics/ # LLM observability (Dockerfile.llm-analytics)
web_analytics/
surveys/
cohorts/
dashboards/
notebooks/
workflows/
data_warehouse/
marketing_analytics/
revenue_analytics/
customer_analytics/
cdp/
...40+ total
rust/ # Rust workspace (30+ crates)
capture/ # High-performance event capture (axum)
feature-flags/ # Rust feature flag evaluator
hook-worker/ # Webhook delivery
hook-api/ # Webhook API
cymbal/ # Error symbolication
cyclotron-core/ # Job scheduler
embedding-worker/ # Embedding generation
kafka-deduplicator/
personinsights-*/ # Person resolution services
property-defs-rs/
common/ # Shared Rust libs (kafka, redis, metrics, health, etc.)
livestream/ # Go service (real-time event streaming)
cli/ # Rust CLI (insights-cli)
funnel-udf/ # Rust ClickHouse UDF for funnels
common/ # Shared packages
insights-js/ # Browser SDK wrapper (@hanzo/insights)
insights-js-lite/ # Lightweight browser SDK
insights-node/ # Node.js SDK wrapper (@hanzo/insights-node)
insightsql_parser/ # InsightsQL parser (Python package)
insightscli/ # Internal dev CLI tooling
design-system/ # Shared UI components
tailwind/ # Tailwind config
storybook/
siphash/ # SipHash implementation
scriptvm/ # Script VM (TypeScript + Rust)
ingestion/ # Shared ingestion code
services/
mcp/ # MCP server (Cloudflare Worker, TypeScript)
llm-gateway/ # LLM gateway integration
nodejs/ # Node.js plugin server
docs/ # Internal documentation
docker/ # Docker configs (ClickHouse, Caddy, Temporal, etc.)
proto/ # Protobuf definitions
terraform/ # Infrastructure as code
playwright/ # E2E tests</code></pre>
<h2>Development commands</h2>
<pre><code class="lang-bash"># Python backend
uv sync --all-extras # Install Python deps
pytest # Run all backend tests
pytest path/to/test.py::TestClass::test_method # Single test
ruff check . --fix &amp;&amp; ruff format . # Lint + format Python
python manage.py migrate # Run Django migrations
# Frontend
pnpm install # Install JS deps
pnpm --filter=@hanzo/frontend build # Build frontend
pnpm --filter=@hanzo/frontend test # Run frontend tests
pnpm --filter=@hanzo/frontend format # Format frontend
# Full stack
./bin/start # Start dev server (backend + frontend)
# InsightsQL grammar
pnpm grammar:build:python # Rebuild ANTLR Python parser
pnpm grammar:build:cpp # Rebuild ANTLR C++ parser
# Schema / OpenAPI
pnpm schema:build # Build TypeScript schema from Django serializers
pnpm openapi:build # Generate OpenAPI spec + TS types via Orval
# Rust services
cd rust &amp;&amp; cargo build # Build all Rust services
cd rust &amp;&amp; cargo test # Test all Rust services
# CLI
cd cli &amp;&amp; cargo build # Build insights-cli
# Docker (self-host)
docker compose -f docker-compose.hobby.yml up # Full self-hosted stack</code></pre>
<h2>Self-hosting</h2>
<p>The <code>docker-compose.hobby.yml</code> runs the complete stack:</p>
<ul><li><code>web</code>: Django app (Granian ASGI)</li><li><code>worker</code>: Celery worker</li><li><code>plugins</code>: Node.js plugin server</li><li><code>db</code>: PostgreSQL (<code>ghcr.io/hanzoai/sql</code>)</li><li><code>kv</code>: Redis</li><li><code>datastore</code>: ClickHouse</li><li><code>kafka</code>: Redpanda</li><li><code>capture</code>: Rust event capture</li><li><code>feature-flags</code>: Rust flag evaluator</li><li><code>property-defs-rs</code>: Rust property definitions</li><li><code>livestream</code>: Go real-time events</li><li><code>cymbal</code>: Rust error symbolication</li><li><code>objectstorage</code>: Hanzo S3</li><li><code>seaweedfs</code>: Session recording storage</li><li><code>temporal</code>: Workflow orchestration</li><li><code>proxy</code>: Caddy reverse proxy</li></ul>
<pre><code class="lang-bash"># Minimal self-host
export DOMAIN=insights.example.com
export INSIGHTS_SECRET=$(openssl rand -hex 32)
docker compose -f docker-compose.hobby.yml up -d</code></pre>
<h2>InsightsQL</h2>
<p>Custom query language with ANTLR4 grammar. Two parser targets: Python3 (backend queries) and C++ (ClickHouse UDFs). Supports:</p>
<ul><li>Event queries with property filters</li><li>Funnel analysis</li><li>Retention cohorts</li><li>Path analysis</li><li>Aggregations, breakdowns, sampling</li></ul>
<p>Security: never interpolate user data into InsightsQL f-strings. Use <code>ast.Constant()</code> placeholders or pass entire expressions through the parser.</p>
<h2>CLI</h2>
<pre><code class="lang-bash">insights-cli login # Authenticate interactively
insights-cli query &quot;SELECT count() FROM events&quot; # Run InsightsQL query
insights-cli sourcemap upload ./dist # Upload sourcemaps for error tracking
insights-cli exp endpoints list # List data endpoints</code></pre>
<p>Environment variables: <code>INSIGHTS_CLI_HOST</code>, <code>INSIGHTS_CLI_API_KEY</code>, <code>INSIGHTS_CLI_PROJECT_ID</code>.</p>
<h2>Architecture guidelines</h2>
<ul><li>API views declare request/response schemas via <code>@validated_request</code> or <code>@extend_schema</code></li><li>Django serializers are source of truth for frontend types (auto-generated via drf-spectacular + Orval)</li><li>New features go in <code>products/</code> directory (each has <code>backend/</code>, <code>frontend/</code>, <code>manifest.tsx</code>)</li><li>Always filter querysets by <code>team_id</code></li><li>Do not add domain-specific fields to <code>Team</code> model -- use Team Extension pattern</li><li>Frontend state management: Kea (not React hooks for business logic)</li><li>Conventional commits: <code>feat(scope):</code>, <code>fix(scope):</code>, <code>chore(scope):</code></li></ul>
<h2>Related Skills</h2>
<ul><li><code>hanzo/hanzo-o11y.md</code> - Technical observability (metrics, traces -- different from product analytics)</li><li><code>hanzo/hanzo-console.md</code> - LLM-specific observability</li><li><code>hanzo/hanzo-cloud.md</code> - Dashboard with analytics views</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2026-03-13 <strong>Category</strong>: Hanzo Ecosystem <strong>Related</strong>: analytics, insights, feature-flags, ab-testing, session-recording, clickhouse, insightsql, llm-analytics, error-tracking <strong>Prerequisites</strong>: Python, TypeScript, Docker, analytics concepts</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/hanzo-insights.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>