Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/vemetric/vemetric/llms.txt

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

​
What is Vemetric?

Vemetric is an open-source web and product analytics platform designed to help you understand your users’ behavior. Unlike traditional analytics tools, Vemetric combines simplicity with powerful features, giving you actionable insights without the complexity. Built with privacy in mind, Vemetric offers real-time analytics, custom event tracking, and advanced filtering mechanisms to see exactly how users interact with your product and website.
Vemetric is licensed under AGPLv3, making it free to use even commercially, while ensuring derivative works remain open source.

​
Why Choose Vemetric?

Vemetric stands out from other analytics platforms through several key benefits:

Real-time Insights

See user activity as it happens. Events appear in your dashboard within seconds, enabling immediate decision-making.

Privacy-First Design

GDPR and CCPA compliant out of the box. You control your data and can self-host for complete data ownership.

Powerful Filtering

Filter by country, device, browser, custom properties, and more. Combine multiple filters to drill down into specific user segments.

Cross-Subdomain Tracking

Track users seamlessly across multiple subdomains without losing session continuity.

​
Architecture Overview

Vemetric uses a modern, scalable architecture designed for high performance and real-time analytics:

​
Core Components

The Hub is the event ingestion service that receives all tracking events from your application. It handles:
  • Event validation and filtering
  • Bot detection and exclusion
  • IP and country-based filtering
  • Cookie management for user identification
  • Session handling
All events are queued for processing to ensure high throughput and reliability.
ClickHouse serves as the primary analytics database, optimized for:
  • Fast aggregation queries over millions of events
  • Real-time analytics with sub-second query times
  • Efficient storage of event data, user journeys, and sessions
  • Time-series analysis and trend detection
Events, sessions, users, and devices are all stored in separate tables for optimal query performance.
PostgreSQL handles transactional data including:
  • Projects and organizations
  • User authentication and permissions
  • API keys and access control
  • Funnel definitions
  • User identification mappings
Background job queues powered by BullMQ handle:
  • Event processing and enrichment
  • User identification and merging
  • Session creation and updates
  • Device fingerprinting
  • Email notifications
Queues ensure reliable processing even under heavy load.
The API service provides:
  • REST endpoints for analytics queries
  • Real-time data aggregation
  • Advanced filtering and segmentation
  • Funnel analysis
  • User journey visualization
The dashboard is a React SPA that visualizes your analytics data.

​
How Vemetric Works

Here’s what happens when you track an event:
1

Event Capture

Your application sends an event to the Hub service via the tracking SDK:
track('button_clicked', {
  button_name: 'signup',
  location: 'header'
});
The Hub validates the event and extracts metadata like user agent, IP address, and referrer.
2

User Identification

Vemetric automatically assigns each visitor a unique user ID, stored in a cookie (if allowed). When you identify a user:
identify('user@example.com', {
  displayName: 'Jane Doe',
  plan: 'premium'
});
All anonymous events are merged with the identified user, creating a complete user journey.
3

Session Management

Sessions are automatically created and maintained. A session continues as long as there’s activity within 30 minutes. Session data includes:
  • Start and end times
  • Duration
  • Geographic location
  • Referrer and UTM parameters
  • Device and browser information
4

Data Processing

Background workers process queued events:
  • Extract device information (browser, OS, device type)
  • Resolve geographic location from IP
  • Parse referrer and classify traffic sources
  • Update user properties
  • Extend or create sessions
5

Real-time Analytics

Processed data is immediately available in ClickHouse. You can query it through:
  • The dashboard for visual analytics
  • The REST API for programmatic access
  • Direct ClickHouse queries for advanced analysis

​
Key Capabilities

​
Event Tracking

Track any user action with custom events and properties: 
// Automatic page view tracking
// No code needed - happens automatically

// Track custom events
vemetric.track('purchase_completed', {
  product_id: '12345',
  amount: 99.99,
  currency: 'USD'
});

// Track with user properties
vemetric.track('feature_used', 
  { feature: 'export' },
  {
    userData: {
      set: { last_export: new Date() },
      setOnce: { first_export: new Date() }
    }
  }
);

​
User Journeys

Visualize the complete path users take through your product, from first touch to conversion. See every page view, event, and interaction in chronological order.

​
Funnel Analysis

Define multi-step funnels to track conversion rates: 
// Example funnel definition stored in PostgreSQL
{
  name: 'Signup Funnel',
  steps: [
    { 
      name: 'Landing Page',
      filter: { type: 'page', pathFilter: { operator: 'is', value: '/landing' } }
    },
    {
      name: 'Signup Started',
      filter: { type: 'event', nameFilter: { operator: 'is', value: 'signup_started' } }
    },
    {
      name: 'Signup Completed',
      filter: { type: 'event', nameFilter: { operator: 'is', value: 'signup_completed' } }
    }
  ]
}
Vemetric calculates drop-off rates at each step, helping you identify where users abandon the flow.

​
Advanced Filtering

Filter your analytics data by multiple dimensions:
  • Geographic: Country, city
  • Device: Browser, OS, device type (mobile/desktop/tablet)
  • Traffic Source: Direct, referral, search, social, UTM parameters
  • User Properties: Anonymous vs identified, custom user data
  • Event Properties: Any custom property you track
  • Time: Date ranges with various granularities

​
Self-Hosting

Vemetric is built to be self-hosted, giving you complete control over your analytics data:

Deploy Anywhere

Run on your own infrastructure using Docker, Kubernetes, or bare metal servers.

Data Ownership

Your data stays on your servers. No third-party access, no data sharing.

Customize Freely

Modify the source code to fit your specific needs. AGPLv3 license allows commercial use.

Scale Independently

Scale each component independently based on your traffic and query patterns.
Self-hosting documentation is currently in development. The Community Edition will support all web analytics features and user journeys.

​
Technology Stack

Vemetric is built with modern, battle-tested technologies:
  • Runtime: Bun for fast JavaScript/TypeScript execution
  • Backend: Hono web framework for event ingestion and API
  • Frontend: React with Vite for the dashboard
  • Analytics DB: ClickHouse for high-performance time-series queries
  • Metadata DB: PostgreSQL with Prisma ORM
  • Queue: BullMQ with Redis for reliable job processing
  • Monorepo: Turborepo for efficient builds and development

​
Next Steps

Now that you understand what Vemetric is and how it works, here’s how to get started:

Quickstart

Set up Vemetric in your application in under 5 minutes

Key Concepts

Learn about projects, events, sessions, and user identification

Integration Guide

Integrate Vemetric with JavaScript, React, or Node.js

API Reference

Explore the REST API for programmatic access