🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
Revise filter traffic documentation to enhance clarity and detail
Bill Yang7a7938f85307
diff --git a/docs/content/docs/filter-traffic.mdx b/docs/content/docs/filter-traffic.mdxindex 2f364e02e..7dd9f5f0b 100644--- a/docs/content/docs/filter-traffic.mdx+++ b/docs/content/docs/filter-traffic.mdx@@ -1,84 +1,148 @@---title: Filter traffic-description: Block traffic from specific IP addresses or countries to improve analytics accuracy+description: Exclude traffic by IP address, country, path, hostname, or user agent---import { Callout } from 'fumadocs-ui/components/callout';-Rybbit provides server-side filtering to exclude traffic from your analytics. This helps you maintain accurate data by blocking unwanted visits, bot traffic, or your own pageviews.+Rybbit provides server-side traffic filtering to keep unwanted data out of your analytics. You can exclude your own traffic, staging and preview environments, internal tools, monitoring checks, or entire countries.-## IP Exclusion+Filters are configured from **Site Settings → Exclusions**.-Block traffic from specific IP addresses or ranges at the server level. For detailed information on IP exclusion including setup instructions, supported formats (CIDR, ranges), and best practices, see [Hiding Your Own Traffic](/docs/hiding-own-traffic).+## Available Filters-**Quick overview:**-- Supports single IPs, CIDR notation, and IPv4 ranges-- Maximum 100 IP exclusions per site-- Works at server level before data reaches your database-- Configure in Site Settings → IP Exclusions section+| Filter | Use it for | Matching behavior | Limit |+| --- | --- | --- | --- |+| **IP Exclusions** | Your home, office, VPN, or internal network traffic | Single IPs, CIDR ranges, and IPv4 ranges | 100 entries |+| **Country Exclusions** | Regional filtering or compliance requirements | Two-letter ISO country codes, such as `US`, `GB`, or `DE` | 250 entries |+| **Path Exclusions** | Admin pages, private pages, preview routes, or test pages | Case-insensitive glob patterns using `*` | 100 entries |+| **Hostname Exclusions** | Localhost, staging domains, preview deployments, or temporary domains | Case-insensitive glob patterns using `*` | 100 entries |+| **User Agent Exclusions** | Monitoring tools, headless browsers, or custom crawlers | Case-insensitive substring matching | 100 entries |-## Country Exclusion+When a request matches an exclusion, Rybbit returns a successful response but does not write the event to analytics storage.-Block all traffic from specific countries to filter out unwanted analytics data or comply with regional requirements.+## IP Exclusions-### Setting Up Country Exclusion+Block traffic from specific IP addresses or ranges at the server level. This is usually the best way to hide your own traffic.-1. **Navigate to Site Settings**: Go to your site's settings page in the Rybbit dashboard-2. **Find Country Exclusions section**: Scroll down to the "Country Exclusions" configuration-3. **Select countries to exclude**: Use the searchable dropdown to select countries you want to block+Supported formats:-### How It Works+- **Single IPv4**: `192.168.1.1`+- **Single IPv6**: `2001:db8::1`+- **CIDR notation**: `192.168.1.0/24`, `2001:db8::/32`+- **IPv4 ranges**: `192.168.1.1-192.168.1.10`-When an event is received, Rybbit:-1. Extracts the visitor's IP address-2. Performs a GeoIP lookup using the MaxMind GeoLite2 database-3. Checks if the country matches your exclusion list-4. Blocks the event if the country is excluded (returns 200 response but doesn't track)+For setup instructions and best practices, see [Hiding Your Own Traffic](/docs/hiding-own-traffic).-### Supported Country Codes+## Country Exclusions-All countries are supported using 2-letter ISO country codes (ISO 3166-1 alpha-2):+Block all traffic geolocated to specific countries. Rybbit resolves the visitor IP address with the MaxMind GeoLite2 database, then compares the resulting country code to your exclusion list.-- **Examples**: `US` (United States), `GB` (United Kingdom), `CN` (China), `RU` (Russia), `IN` (India), `DE` (Germany)-- **Case-insensitive**: Both `US` and `us` are accepted-- **Maximum**: Up to 250 countries can be excluded+Use two-letter ISO country codes:-### Key Features+- `US` for United States+- `GB` for United Kingdom+- `CN` for China+- `DE` for Germany-- **Server-side filtering**: Traffic is blocked before it reaches your analytics database-- **GeoIP-based**: Uses MaxMind GeoLite2 for accurate country detection-- **Near real-time updates**: Changes take effect within 60 seconds (cache TTL)-- **No browser dependency**: Works regardless of browser or device-- **Applies to all events**: Blocks pageviews, custom events, session replay, and performance metrics+Country codes are stored as uppercase values in the dashboard and API.<Callout type="warning">-**Private IP addresses**: Country exclusion won't work for private IP addresses (e.g., `127.0.0.1`, `192.168.x.x`, `10.x.x.x`, `172.16.x.x`) as these cannot be geolocated. This includes localhost and Docker container IPs during local development.+**Private IP addresses**: Country exclusion cannot work for private IP addresses such as `127.0.0.1`, `192.168.x.x`, `10.x.x.x`, or `172.16.x.x` because they cannot be geolocated. This includes localhost and Docker container IPs during local development.</Callout><Callout type="info">-**Testing locally**: To test country exclusion during development, send events with a public IP address using the `ip_address` field in your event payload. The GeoIP lookup will use the custom IP instead of the request IP.+**VPNs and proxies**: Visitors using VPNs or proxies are detected based on the VPN or proxy server location, not their physical location.+</Callout>++## Path Exclusions++Exclude traffic to specific page paths. Path exclusions match the pathname only, not the query string.++Examples:++```txt+/admin/*+/preview+/internal/*+```++Matching is case-insensitive. A `*` wildcard matches any sequence of characters, so `/admin/*` matches `/admin/users` and `/admin/settings`.++Use path exclusions for pages that should not appear in analytics at all, such as admin dashboards, internal previews, or test routes.++<Callout type="info">+For client-side-only pageview skipping, you can also use the tracking script's `data-skip-patterns` option. Site-level path exclusions are enforced on the server and also apply to session replay ingestion.+</Callout>++## Hostname Exclusions++Exclude traffic from specific hostnames. This is useful when the same site ID is used across production, staging, preview, and local environments.++Examples:++```txt+localhost+staging.example.com+*.vercel.app+*.netlify.app+```++Matching is case-insensitive. A `*` wildcard matches any sequence of characters, so `*.vercel.app` matches `my-preview.vercel.app` but not `vercel.app`.++## User Agent Exclusions++Exclude traffic from requests whose user agent contains a configured substring.++Examples:++```txt+HeadlessChrome+MyMonitor+Pingdom+```++Matching is case-insensitive and uses substring matching, so `HeadlessChrome` matches `Mozilla/5.0 HeadlessChrome/120`.++Use user-agent exclusions for uptime monitors, synthetic checks, internal crawlers, or other tools with predictable user-agent strings.++## What Filters Apply To++Traffic filters run before normal analytics data is stored. They apply to:++- Pageviews+- Custom events+- Performance and Web Vitals events+- Error events+- Autocapture events+- Session replay batches++## How Filters Are Evaluated++Rybbit checks exclusions in this order:++1. IP address+2. Country+3. Path+4. Hostname+5. User agent++If any filter matches, the event is accepted with a `200` response but is not tracked. Changes usually take effect within 60 seconds because site configuration is cached briefly on the server.++## Testing Filters Locally++To test country filtering locally, send a public IP through the `X-Real-IP` header:-Example:```bashcurl -X POST http://localhost:3000/track \-H "Content-Type: application/json" \+ -H "X-Real-IP: 8.8.8.8" \-d '{"type": "pageview","site_id": "your-site-id",- "ip_address": "8.8.8.8",- "url": "https://example.com/test"+ "hostname": "example.com",+ "pathname": "/test"}'```-</Callout>--<Callout type="info">-**VPNs and proxies**: Visitors using VPNs or proxies will be detected based on the VPN/proxy server location, not their actual physical location.-</Callout>--## Combining Filters--You can use both IP and country exclusions together for comprehensive filtering:-- **IP exclusions** are checked first, then **country exclusions**-- Both filters work at the server level before data reaches your database-- Excluded events return a `200` status code but with a message indicating they were not tracked+For path and hostname filters, set `pathname` and `hostname` in the event payload to values that should match your configured exclusions.