Skip to content

🐸 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.mdx
index 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:
```bash
curl -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.