Skip to main content
Traffic shields help you filter out unwanted traffic from your analytics, ensuring your data remains accurate and meaningful. Plausible supports four types of traffic filtering rules.

​
Shield Types

All shield rules support two actions:
  • Deny: Block traffic matching the rule (default)
  • Allow: Explicitly permit traffic matching the rule
Shield rules are cached for performance and updated automatically when you make changes.

​
IP Address Blocking

Block or allow traffic from specific IP addresses to filter out internal traffic, bots, or unwanted visitors.

​
Creating IP Rules

1

Navigate to Shields

Go to Site Settings > Shields > IP Addresses
2

Add IP Address

Enter the IP address you want to block or allow:
  • IPv4: 192.168.1.1
  • IPv6: 2001:0db8:85a3:0000:0000:8a2e:0370:7334
3

Add Description (Optional)

Add a description to remember why you created this rule, such as “Office IP” or “Known bot”.
4

Select Action

Choose whether to deny (block) or allow this IP address.

​
IP Rule Details

schema "shield_rules_ip" do
  belongs_to :site, Plausible.Site
  field :inet, EctoNetwork.INET
  field :action, Ecto.Enum, values: [:deny, :allow], default: :deny
  field :description, :string
  field :added_by, :string
end
Netmasks (CIDR notation) are not supported. You must specify individual IP addresses.

​
Common Use Cases

Block office traffic: 
IP: 203.0.113.0
Action: Deny
Description: Office IP - exclude from analytics
Block known bot: 
IP: 198.51.100.42
Action: Deny
Description: Scraper bot

​
Country Filtering

Block or allow traffic from entire countries using ISO country codes.

​
Creating Country Rules

1

Open Country Shields

Navigate to Site Settings > Shields > Countries
2

Select Country

Choose a country from the dropdown or enter its 2-letter ISO code (e.g., US, GB, FR).
3

Configure Action

Select whether to block or allow traffic from this country.

​
Country Rule Schema

schema "shield_rules_country" do
  belongs_to :site, Plausible.Site
  field :country_code, :string  # 2-letter ISO code
  field :action, Ecto.Enum, values: [:deny, :allow], default: :deny
  field :added_by, :string
end

​
Country Codes

  • Use standard 2-letter ISO country codes (ISO 3166-1 alpha-2)
  • Special code: ZZ represents unknown/undetected countries
The country code must be exactly 2 characters and match a valid ISO country code.

​
Example Rules

Block specific country: 
Country Code: CN
Action: Deny
Allow only specific countries: 
Country Code: US
Action: Allow

Country Code: GB
Action: Allow
Country detection is based on the visitor’s IP address. VPNs and proxies may affect accuracy.

​
Page Path Filtering

Filter traffic based on page paths using exact matches or wildcard patterns.

​
Creating Page Rules

1

Access Page Shields

Go to Site Settings > Shields > Pages
2

Enter Page Path

Specify the page path to filter. Must start with /.Examples:
  • /admin
  • /api/*
  • /blog/**
3

Choose Action

Select deny to exclude or allow to include only matching pages.

​
Wildcard Patterns

Page rules support wildcard matching:
  • * - Matches any characters in a single path segment
  • ** - Matches any characters across multiple path segments
Examples:
PatternMatchesDoesn’t Match
/admin/admin/admin/users
/admin/*/admin/users, /admin/settings/admin/users/edit
/admin/**/admin/users, /admin/users/edit/123/api/admin
/blog/*/comments/blog/post-1/comments/blog/nested/post/comments

​
Page Rule Schema

schema "shield_rules_page" do
  belongs_to :site, Plausible.Site
  field :page_path, :string  # Max 250 characters
  field :page_path_pattern, :string  # Compiled regex
  field :action, Ecto.Enum, values: [:deny, :allow], default: :deny
  field :added_by, :string
end
Page patterns are automatically compiled to regular expressions for efficient matching.

​
Validation Rules

  • Page paths must start with /
  • Maximum length: 250 characters
  • Pattern must compile to a valid regular expression
If your pattern creates an invalid regex, you’ll receive an error: “could not compile regular expression”

​
Common Use Cases

Exclude admin pages: 
Page Path: /admin/**
Action: Deny
Exclude API endpoints: 
Page Path: /api/**
Action: Deny
Track only blog posts: 
Page Path: /blog/**
Action: Allow

​
Hostname Allowlist

Control which hostnames can send events to your site. This is an allowlist-only feature (default action is allow).

​
Creating Hostname Rules

1

Navigate to Hostname Shields

Go to Site Settings > Shields > Hostnames
2

Add Allowed Hostname

Enter the hostname that should be allowed to send events.Examples:
  • example.com
  • *.example.com
  • app.example.com
3

Save Rule

The hostname will be added to your allowlist.

​
Wildcard Support

Hostname rules support wildcard patterns:
  • example.com - Matches exactly example.com
  • *.example.com - Matches all subdomains
  • ** - Matches any hostname (not recommended)
Examples:
PatternMatchesDoesn’t Match
example.comexample.comwww.example.com
*.example.comapp.example.com, api.example.comexample.com
www.example.comwww.example.comexample.com

​
Hostname Rule Schema

schema "shield_rules_hostname" do
  belongs_to :site, Plausible.Site
  field :hostname, :string  # Max 250 characters
  field :hostname_pattern, :string  # Compiled regex
  field :action, Ecto.Enum, values: [:deny, :allow], default: :allow
  field :added_by, :string
end
Hostname shields prevent event spoofing by ensuring events only come from your legitimate domains.

​
Use Cases

Allow main domain and www: 
Hostname: example.com
Hostname: www.example.com
Allow all subdomains: 
Hostname: *.example.com
Multi-domain setup: 
Hostname: example.com
Hostname: example.org
Hostname: example.net
If you have hostname shields configured, only events from explicitly allowed hostnames will be recorded.

​
Shield Performance

All shield rules are cached for optimal performance:
  • IP rules use Plausible.Shield.IPRuleCache
  • Country rules use Plausible.Shield.CountryRuleCache
  • Page rules use Plausible.Shield.PageRuleCache
  • Hostname rules use Plausible.Shield.HostnameRuleCache
Caches are automatically updated when you add, modify, or remove shield rules.

​
Managing Shield Rules

​
Viewing Active Rules

See all active shield rules for your site:
  1. Navigate to Site Settings > Shields
  2. View rules organized by type
  3. See who added each rule and when

​
Editing Rules

To modify a rule:
  1. Remove the existing rule
  2. Create a new rule with updated settings
Shield rules cannot be directly edited. Delete and recreate the rule with your desired changes.

​
Removing Rules

Delete a shield rule:
  1. Find the rule in your shields list
  2. Click the delete/remove button
  3. Confirm removal
The rule is removed immediately and the cache is updated.

​
Best Practices

1

Start with IP Blocking

Block your office/development IPs first to exclude internal traffic.
2

Test Before Blocking Countries

Review your country distribution before blocking entire countries.
3

Use Specific Patterns

Make page and hostname patterns as specific as possible to avoid over-filtering.
4

Document Your Rules

Use descriptions to explain why each rule exists for future reference.
5

Monitor Impact

Check your analytics after adding rules to ensure you’re not blocking legitimate traffic.

​
Troubleshooting

Rule not working?
  • Verify the pattern syntax is correct
  • Check that the rule action (deny/allow) is what you intended
  • Wait a few moments for cache updates to propagate
Accidentally blocking too much?
  • Review your wildcard patterns
  • Remove overly broad rules
  • Consider using more specific patterns
Pattern won’t save?
  • Ensure page paths start with /
  • Check pattern length (max 250 characters)
  • Verify the pattern compiles to valid regex

Build docs developers (and LLMs) love

Get started for freeTalk to us