llms.txt
Compare with other sites' llms.txt files →# Pug - Open Source Product Analytics
> Pug is an open-source product analytics platform with unified user profiles. It records page views, clicks, scrolls, and custom events and answers questions with trends, funnels, retention cohorts, segmentation, user flows (Sankey), and top-K rankings. Identity resolution merges anonymous and identified activity into a single timeline per user.
There are two ways to run it: self-hosted, free forever under AGPL-3.0, or managed cloud (Pug Cloud), free up to 100,000 events a month with no credit card. Past that, Pug Cloud costs $1 a month plus $40 per million events, with the rate falling in graduated tiers to $7 per million past 250 million, so a million events a month comes to $37 in total. There are no per-seat fees and every plan has every feature, so the bill depends only on event volume. SSO is included on every plan of both: Google Workspace, or any OIDC identity provider such as Okta, Microsoft Entra ID, or Keycloak. The backend is Go, PostgreSQL, ClickHouse, NATS, and Connect RPC. Pug is built by Tshoka Pvt Ltd.
Six SDKs ship today. The Web SDK (`@pug-sh/browser`, TypeScript) auto-captures page views, clicks, scrolls, form interactions, rage clicks, and dead clicks. The Flutter SDK (`pug_flutter`, Dart) auto-tracks screen views and lifecycle from `init()` and exposes typed methods for the well-known events. The Android SDK (`sh.pug:android` on Maven Central, Kotlin, callable from Java) tracks app opens, activity screen views, and installs on its own, with the same typed methods. The Node SDK (`@pug-sh/node`) handles server-side event tracking, profile identify, and analytics reads; the Ruby SDK (`pug-sh` on RubyGems, Ruby 3.3+) does the same from Rails or plain Ruby, and the Go SDK (`github.com/pug-sh/sdk-go`, Go 1.26+) from Go services. Native iOS and React Native SDKs are in active development. There is no per-framework SDK: every framework integration below uses one of these six.
## Product
- [Pug](https://pug.sh/): What Pug captures, the six insight types, the privacy defaults, and the six SDKs, on one page
- [Product analytics](https://pug.sh/product-analytics): What product analytics is, and how Pug does it
- [Analytics](https://pug.sh/analytics): The six insight types: trends, funnels, retention, segmentation, user flow, and top-K
- [Dashboards](https://pug.sh/analytics-dashboard): Dashboards and tiles built from saved insights
- [User analytics](https://pug.sh/user-analytics): Unified profiles and identity resolution
- [Platform](https://pug.sh/platform): The event pipeline and architecture end to end
- [SDKs](https://pug.sh/sdks): Web, Android, Flutter, Node, Go, and Ruby SDKs; native iOS and React Native in development
- [MCP server](https://pug.sh/mcp): Twelve read-only MCP tools over the analytics API, private-key auth, one project
- [Pricing](https://pug.sh/pricing): Pug Cloud is free up to 100,000 events a month, then pay as you go per event in graduated tiers, with a bill estimator; self-hosting is free forever; SSO on every plan, with no SSO tax
- [Open source](https://pug.sh/open-source-analytics): What AGPL-3.0 open-source analytics means in practice
- [Self-hosted](https://pug.sh/self-hosted-analytics): Running the whole stack on your own infrastructure
- [About](https://pug.sh/about): Who builds Pug and why (Tshoka Pvt Ltd)
- [Campaigns](https://pug.sh/campaigns): Web push, email, and SMS composed from profiles and events (in active development, not yet available in the dashboard)
## Comparisons
Each comparison keeps an honest "where they win" section.
- [All comparisons](https://pug.sh/compare): Index of every comparison page
- [PostHog alternative](https://pug.sh/compare/posthog-alternative): Pug vs PostHog
- [Mixpanel alternative](https://pug.sh/compare/mixpanel-alternative): Pug vs Mixpanel
- [Amplitude alternative](https://pug.sh/compare/amplitude-alternative): Pug vs Amplitude
- [Heap alternative](https://pug.sh/compare/heap-alternative): Pug vs Heap
- [Plausible alternative](https://pug.sh/compare/plausible-alternative): Pug vs Plausible
- [Matomo alternative](https://pug.sh/compare/matomo-alternative): Pug vs Matomo
- [Umami alternative](https://pug.sh/compare/umami-alternative): Pug vs Umami
- [Segment alternative](https://pug.sh/compare/segment-alternative): Pug vs Segment
- [Google Analytics alternative](https://pug.sh/compare/google-analytics-alternative): Pug vs Google Analytics 4
- [Google Analytics replacement](https://pug.sh/compare/google-analytics-replacement): Replacing GA4, step by step
- [Firebase Analytics alternative](https://pug.sh/compare/firebase-analytics-alternative): Pug vs Firebase Analytics on the mobile (Flutter and Android) angle, not a Firebase platform replacement
- [Aptabase alternative](https://pug.sh/compare/aptabase-alternative): Pug vs Aptabase, also AGPL-3.0 and self-hostable; the difference is identity, not openness
- [Countly alternative](https://pug.sh/compare/countly-alternative): Pug vs Countly: open Lite edition vs paid editions, and Countly's modified AGPL §7 branding clause
## Integrations
- [All integrations](https://pug.sh/integrations): Index of every integration guide
- [Next.js](https://pug.sh/integrations/nextjs): App Router setup with the Web SDK, including the page-view caveat
- [React](https://pug.sh/integrations/react): Web SDK in a React app
- [Vue](https://pug.sh/integrations/vue): Web SDK in a Vue app
- [Node.js](https://pug.sh/integrations/nodejs): Trusted server-side events with the Node SDK
- [Flutter](https://pug.sh/integrations/flutter): Auto-tracking and typed events with the Flutter SDK
- [Android](https://pug.sh/integrations/android): Native Kotlin SDK: automatic lifecycle, screen, and install events, typed events, and consent
## Use cases
- [All use cases](https://pug.sh/use-cases): Index of every use-case page
- [SaaS](https://pug.sh/use-cases/saas): Activation funnels, retention cohorts, and a profile per account
- [Mobile apps](https://pug.sh/use-cases/mobile-apps): Flutter and Android SDKs today, install-week retention, onboarding funnels; iOS and React Native in development
- [Ecommerce](https://pug.sh/use-cases/ecommerce): Checkout funnel, standard commerce events, repeat-purchase retention
## Free tools
Every tool runs entirely in the browser. No signup, no data leaves the page.
- [All tools](https://pug.sh/tools): Index of every free tool
- [UTM builder](https://pug.sh/tools/utm-builder): Build trackable campaign URLs with consistent UTM parameters
- [A/B test calculator](https://pug.sh/tools/ab-test-calculator): Sample-size planner and significance checker
- [Conversion rate calculator](https://pug.sh/tools/conversion-rate-calculator): Visitors and conversions to a rate, plus the traffic needed for a target
- [Funnel calculator](https://pug.sh/tools/funnel-calculator): Step conversion, drop-off, and overall funnel rate
- [Retention rate calculator](https://pug.sh/tools/retention-rate-calculator): Retention rate, churn, and implied customer lifetime
- [Cohort retention visualizer](https://pug.sh/tools/cohort-retention-visualizer): Render cohort retention as a heatmap curve
- [Analytics cost calculator](https://pug.sh/tools/analytics-cost-calculator): Estimate Mixpanel, Amplitude, and Segment cost at your event volume, next to Pug Cloud's exact rates and $0 self-hosted Pug
- [CLV calculator](https://pug.sh/tools/clv-calculator): Customer lifetime value from ARPU, margin, and churn
- [CAC calculator](https://pug.sh/tools/cac-calculator): Customer acquisition cost, LTV:CAC ratio, and payback period
- [NPS calculator](https://pug.sh/tools/nps-calculator): Net Promoter Score from promoter, passive, and detractor counts
- [Event tracking plan generator](https://pug.sh/tools/event-tracking-plan-generator): A tracking plan with real event names, typed properties, and PII flags
- [Event naming linter](https://pug.sh/tools/event-naming-linter): Check event names against a snake_case object_action convention
- [PII event auditor](https://pug.sh/tools/pii-event-auditor): Flag event properties that likely carry PII under GDPR
- [UUID generator](https://pug.sh/tools/uuid-generator): Generate and inspect v4, v7, v1/v6, and deterministic v3/v5 UUIDs
- [OG preview](https://pug.sh/tools/og-preview): Preview a URL's Open Graph and Twitter Card share cards
## Glossary
Plain-English definitions of product-analytics concepts.
- [Glossary index](https://pug.sh/glossary): Every term
- [Autocapture](https://pug.sh/glossary/autocapture): Collecting events without instrumenting each one by hand
- [Funnel analysis](https://pug.sh/glossary/funnel-analysis): Measuring step-by-step conversion through an ordered sequence
- [Retention cohort](https://pug.sh/glossary/retention-cohort): Grouping users by start period to measure how many return
- [User flow analysis](https://pug.sh/glossary/user-flow-analysis): Mapping the paths people actually take through a product
- [Unified customer profile](https://pug.sh/glossary/unified-customer-profile): One record per person across sources, sessions, and devices
- [Event tracking](https://pug.sh/glossary/event-tracking): Recording user actions as named events with typed properties
- [Identity resolution](https://pug.sh/glossary/identity-resolution): Merging anonymous and identified activity into one person
- [PII](https://pug.sh/glossary/pii): What counts as personally identifiable information in an event stream
- [Bot traffic](https://pug.sh/glossary/bot-traffic): Automated visits, how they are detected, and tag vs drop
- [Session](https://pug.sh/glossary/session): One continuous visit, and the inactivity rules that bound it
- [Bounce rate](https://pug.sh/glossary/bounce-rate): Single-interaction sessions, and the two competing definitions
- [UTM parameters](https://pug.sh/glossary/utm-parameters): The five link tags and the naming rules that keep them usable
- [Marketing attribution](https://pug.sh/glossary/attribution): Channel classification, credit models, and why Direct is large
- [Conversion rate](https://pug.sh/glossary/conversion-rate): The share of users who complete a target action
- [Churn rate](https://pug.sh/glossary/churn-rate): The share of users or revenue lost over a period
- [Active users](https://pug.sh/glossary/active-users): DAU, WAU, and MAU, and how each is counted
- [North star metric](https://pug.sh/glossary/north-star-metric): The single metric that best captures delivered value
## Learn
Concepts, roundups, and benchmarks.
- [Learn index](https://pug.sh/learn): The whole Learn library
- [Open-source product analytics](https://pug.sh/learn/open-source-product-analytics): What it is and what the licenses actually mean
- [Product analytics vs web analytics](https://pug.sh/learn/product-analytics-vs-web-analytics): Two different questions, two different tools
- [Event tracking with open source](https://pug.sh/learn/event-tracking-open-source): Designing an event schema you can live with
- [Privacy-first analytics](https://pug.sh/learn/privacy-first-analytics): Measuring product usage without collecting more than you need
- [Cookieless analytics](https://pug.sh/learn/cookieless-analytics): How rotating identifiers differ from fingerprinting
- [Best cookieless analytics tools](https://pug.sh/learn/best-cookieless-analytics-tools): Roundup, compared by salt-rotation period
- [Cookieless vs fingerprinting](https://pug.sh/learn/cookieless-vs-fingerprinting): Where ePrivacy Art. 5(3) actually applies
- [Cookieless funnels and retention](https://pug.sh/learn/cookieless-funnels-and-retention): What daily-rotating identity costs your multi-day reports
- [What an analytics MCP server does](https://pug.sh/learn/mcp-analytics-server): Tools, schema discovery, and what should never be agent-callable
- [How to filter bot traffic in GA4](https://pug.sh/learn/filter-bot-traffic-ga4): What GA4's always-on bot filter catches, and what runs your tag anyway
- [Bot traffic, funnels and retention](https://pug.sh/learn/bot-traffic-funnels-retention): How automated traffic biases each product metric, and which way
- [AI crawlers and your analytics](https://pug.sh/learn/ai-crawlers-analytics): GPTBot and ClaudeBot don't execute JavaScript, so they never reach the tag
- [How analytics tools filter bots](https://pug.sh/learn/analytics-bot-filtering-compared): Roundup: which signals each tool trusts, and drop vs tag
- [The DPDP Act and analytics](https://pug.sh/learn/dpdp-act-analytics): India's data protection law, applied to product analytics
- [GDPR analytics compliance](https://pug.sh/learn/gdpr-analytics): Lawful basis, consent, retention, and data subject rights
- [CCPA analytics compliance](https://pug.sh/learn/ccpa-analytics): Opt-out rights, sale vs sharing, and Global Privacy Control
- [Free analytics for startups](https://pug.sh/learn/free-analytics-for-startups): What is genuinely free, and where the free tiers stop
- [Heap pricing explained](https://pug.sh/learn/heap-pricing): How the session-based model prices out
- [Product analytics for mobile apps](https://pug.sh/learn/product-analytics-for-mobile-apps): What to measure in an app, and why
- [Best Firebase Analytics alternatives](https://pug.sh/learn/best-firebase-analytics-alternatives): Roundup: GA4 is the same backend, not an escape
- [Best product analytics tools](https://pug.sh/learn/best-product-analytics-tools): Roundup of the main options
- [Best open-source analytics tools](https://pug.sh/learn/best-open-source-analytics-tools): Roundup, by license and hosting model
- [Best self-hosted analytics](https://pug.sh/learn/best-self-hosted-analytics): Roundup, by what it takes to actually run
- [Best PostHog alternatives](https://pug.sh/learn/best-posthog-alternatives): Roundup
- [Best Mixpanel alternatives](https://pug.sh/learn/best-mixpanel-alternatives): Roundup
- [What is a good retention rate?](https://pug.sh/learn/good-retention-rate): Benchmarks by product type
- [What is a good conversion rate?](https://pug.sh/learn/good-conversion-rate): Benchmarks by funnel stage
- [LTV:CAC ratio explained](https://pug.sh/learn/ltv-cac-ratio): How to compute it and what the number means
- [What is a good NPS score?](https://pug.sh/learn/nps-benchmarks): Benchmarks by industry
## Blog
Engineering and SDK deep-dives.
- [Blog index](https://pug.sh/blog): Every post
- [Inside the Pug Web SDK](https://pug.sh/blog/web-analytics-sdk): How autocapture and batching work
- [Reliable event delivery](https://pug.sh/blog/reliable-event-delivery): Retries, unload beacons, and not losing events
- [Well-known events](https://pug.sh/blog/well-known-events): Why standard event names beat bespoke naming
- [Product analytics for developers](https://pug.sh/blog/product-analytics-for-developers): Instrumenting a product without a data team
- [Cookieless identity and the self-deleting salt](https://pug.sh/blog/cookieless-identity-daily-rotating-salt): How the daily-rotating salt works
- [Server-side event tracking in Ruby and Rails](https://pug.sh/blog/ruby-event-tracking): The `pug-sh` gem: a track call that never blocks or raises, well-known events validated in-process, fork-safe batching under Puma
## Guides
- [All guides](https://pug.sh/guides): Index of every guide
- [Self-hosting setup](https://pug.sh/guides/self-hosted-analytics-setup): Step-by-step self-hosted install
- [Migrate from Heap to Pug](https://pug.sh/guides/migrate-from-heap-to-pug): Inventory reports, swap the SDK, dual-run, rebuild insights
## Pricing
Prices are in US dollars. Pug Cloud is free up to 100,000 events a month, with
every feature and no credit card. Past that, the Pay as you go plan is a $1
monthly fee plus usage, billed per event in graduated tiers: each tier bills only
the events inside it, so reaching a new tier never reprices the events below it,
and the rate falls as volume grows.
| Events per month | Price per million events |
|---|---|
| First 100k | Free |
| 100k to 2M | $40 |
| 2M to 15M | $23 |
| 15M to 50M | $15 |
| 50M to 100M | $14 |
| 100M to 250M | $10 |
| Over 250M | $7 |
The whole monthly bill, fee included:
| Events per month | Monthly bill |
|---|---|
| 100,000 | $0 |
| 500,000 | $17 |
| 1,000,000 | $37 |
| 5,000,000 | $146 |
| 20,000,000 | $451 |
| 100,000,000 | $1,601 |
There are no per-seat or per-project fees: members are free, and every project in
an organization shares the one allowance. Every plan has every feature, SSO
included. Past the free allowance no event is dropped, throttled, or delayed: the
dashboard shows a banner and an admin can subscribe. Pay as you go keeps 5 years
of history (1 year on the free allowance), is billed monthly, and can be
cancelled at any time in the billing portal; the organization then returns to
the free allowance and keeps its events. Very high volume, longer history, or an
annual contract gets a custom plan with its own rates: email hello@pug.sh.
Self-hosting is free forever under AGPL-3.0, with every feature and no event
limits: the only cost is the servers it runs on.
## Quickstart
Six SDKs ship today: Web (browser), Android and Flutter (mobile), and Node,
Go, and Ruby (server). Every framework integration uses one of these six: there
is no per-framework SDK. Native iOS and React Native SDKs are in active
development; until they ship, iOS means Flutter.
Two key types. A **public** key (`pub_`) ships inside client code and can only
write events. A **private** key (`prv_`) is server-side only and can also read:
profiles, insight queries, and the MCP server below. Never put a private key in a
browser bundle or a mobile app.
Web: `@pug-sh/browser`, TypeScript. Autocaptures page views, clicks, scrolls,
form interactions, rage clicks, and dead clicks after one `init()`:
```bash
npm install @pug-sh/browser
```
```ts
import { init, identify, track } from '@pug-sh/browser'
init('your-project-id', { apiKey: 'pub_your_key' })
identify('user_123', { email: 'ada@example.com', plan: 'pro' })
track('signup', { plan: 'pro' })
track('order_completed', { amount: 49.0, currency: 'USD' })
```
Mobile (Android): `sh.pug:android` on Maven Central, Kotlin (callable from
Java), minSdk 21. Call `Pug.init` once in `Application.onCreate`: app opens,
activity screen views, and installs are tracked from there, and typed methods
cover the well-known events. Consent is granted by default; there is no
cookieless mode on Android.
```kotlin
// app/build.gradle.kts
dependencies {
implementation("sh.pug:android:0.1.0")
}
```
```kotlin
import sh.pug.android.Options
import sh.pug.android.Pug
Pug.init(this, "your-project-id", Options("pub_your_key"))
Pug.identify("user_123", mapOf("plan" to "pro"))
Pug.track.purchase(amount = 49.0, currency = "USD")
Pug.screen("Settings") // composables and fragments are not activities
```
Mobile (Flutter): `pug_flutter`, Dart. Auto-tracks screen views and lifecycle
from `init()`, with typed methods for the well-known events:
```bash
flutter pub add pug_flutter
```
```dart
import 'package:pug_flutter/pug_flutter.dart';
await Pug.init('your-project-id', const PugOptions(apiKey: 'pub_your_key'));
await Pug.identify('user_123', traits: {'plan': 'pro'});
Pug.track.signup(extras: {'plan': 'pro'});
```
Server (Node): `@pug-sh/node`. Trusted events name the user explicitly (no
ambient session), and a private key can read back:
```bash
npm install @pug-sh/node
```
```ts
import { Pug } from '@pug-sh/node'
const pug = new Pug({ apiKey: process.env.PUG_API_KEY }) // private key, prv_...
pug.track('user_123', 'order_completed', { amount: 49.0, currency: 'USD' })
await pug.identify('user_123', { email: 'ada@example.com', plan: 'pro' })
const profile = await pug.profiles.getByExternalId('user_123')
```
Server (Go): `github.com/pug-sh/sdk-go`, Go 1.26+, imported as package `pug`.
The same model as Node. `pug.New` returns an error for a missing or non-`prv_`
key. `Track` and `Identify` never fail or block: background goroutines send
them in batch