PHPackages                             spyglasses/spyglasses - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. spyglasses/spyglasses

ActiveDrupal-module[Logging & Monitoring](/categories/logging)

spyglasses/spyglasses
=====================

Spyglasses AI Traffic Analytics for Drupal - Detect, block and log your website's AI traffic using Drupal's middleware API.

v1.0.13(11mo ago)024GPL-2.0-or-laterPHPPHP >=7.4

Since Sep 15Pushed 11mo agoCompare

[ Source](https://github.com/orchestra-code/spyglasses-drupal)[ Packagist](https://packagist.org/packages/spyglasses/spyglasses)[ Docs](https://www.spyglasses.io)[ RSS](/packages/spyglasses-spyglasses/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (1)Versions (15)Used By (0)

Spyglasses for Drupal
=====================

[](#spyglasses-for-drupal)

[![License: GPL v2+](https://camo.githubusercontent.com/4c3bbb2162df305f1122d9aecffe3ac70c0464a1a77ba5b35bb83269084815a4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d47504c25323076322b2d626c75652e737667)](https://www.gnu.org/licenses/gpl-2.0)[![Drupal](https://camo.githubusercontent.com/e1695958ecbd946b03cfbbe082d3672dcdb5554ec6ae87b71ad3f0260efe1d29/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f44727570616c2d3825323025374325323039253230253743253230313025323025374325323031312d626c7565)](https://www.drupal.org)

Spyglasses provides AI traffic analytics for Drupal by detecting, blocking, and logging bot traffic from AI assistants and crawlers using Drupal's middleware API.

Features
--------

[](#features)

- **AI Bot Detection**: Detect traffic from ChatGPT, Claude, Perplexity, and other AI assistants
- **AI Referrer Tracking**: Track visitors coming from AI platforms
- **Model Training Crawler Detection**: Identify and optionally block AI training crawlers like GPTBot, CCBot, and ClaudeBot
- **Middleware-Based**: Uses Drupal's StackPHP middleware for high-performance request processing
- **Configurable Blocking**: Block or allow specific bots based on your preferences
- **Real-time Analytics**: Log all detected traffic to the Spyglasses platform for analysis
- **Automatic Pattern Updates**: Keep bot detection patterns up-to-date automatically
- **Cache-Aware**: Properly handles caching to avoid false positives

Installation
------------

[](#installation)

### Via Composer (Recommended)

[](#via-composer-recommended)

```
composer require spyglasses/drupal
```

### Manual Installation

[](#manual-installation)

1. Download the module from [GitHub](https://github.com/orchestra-code/spyglasses-drupal)
2. Extract to your `modules/contrib` directory
3. Enable the module via Drupal admin or drush:

```
drush en spyglasses
```

Configuration
-------------

[](#configuration)

### 1. Get Your API Key

[](#1-get-your-api-key)

Sign up for a free account at [spyglasses.io](https://www.spyglasses.io) to get your API key.

### 2. Configure the Module

[](#2-configure-the-module)

1. Navigate to **Configuration > Web Services > Spyglasses** (`/admin/config/services/spyglasses`)
2. Enter your API key
3. Configure your settings:
    - **Debug Mode**: Enable for troubleshooting (logs detailed information)
    - **Auto-sync Patterns**: Automatically update bot patterns daily
    - **Advanced Settings**: Customize endpoints and cache settings if needed

### 3. Sync Patterns

[](#3-sync-patterns)

Click "Sync Patterns Now" to fetch the latest bot detection patterns from the Spyglasses API.

How It Works
------------

[](#how-it-works)

Spyglasses uses Drupal's middleware API to intercept HTTP requests early in the request lifecycle. For each request:

1. **Pattern Matching**: Checks the User-Agent against known AI bot patterns
2. **Referrer Detection**: Analyzes the HTTP Referer for AI platform origins
3. **Blocking Decision**: Applies your blocking rules (if configured)
4. **Logging**: Sends detection data to Spyglasses for analytics
5. **Cache Headers**: Sets appropriate cache headers to prevent false positives

### Detected Traffic Types

[](#detected-traffic-types)

- **AI Assistants**: ChatGPT-User, Claude-User, Perplexity-User, etc.
- **AI Crawlers**: GPTBot, ClaudeBot, CCBot, Applebot-Extended, etc.
- **AI Referrers**: Traffic from chat.openai.com, claude.ai, perplexity.ai, etc.

Performance
-----------

[](#performance)

- **Minimal Overhead**: Middleware runs before full Drupal bootstrap
- **Efficient Caching**: Patterns cached for 24 hours by default
- **Non-blocking Logging**: API calls don't slow down your site
- **Smart Exclusions**: Skips static files and admin pages automatically

Blocking Configuration
----------------------

[](#blocking-configuration)

Configure blocking rules in your Spyglasses dashboard:

- **Block AI Model Trainers**: Block crawlers that train AI models
- **Custom Block Rules**: Block specific bots, categories, or patterns
- **Custom Allow Rules**: Always allow specific bots (overrides blocks)

Debugging
---------

[](#debugging)

Enable debug mode in the module settings to see detailed logs:

```
# View Drupal logs
drush watchdog:show --filter=spyglasses

# Or check the database
SELECT * FROM watchdog WHERE type = 'spyglasses' ORDER BY timestamp DESC;
```

Requirements
------------

[](#requirements)

- **Drupal**: 8.8+ | 9.x | 10.x | 11.x
- **PHP**: 7.4+
- **Extensions**: cURL, JSON
- **Permissions**: `administer site configuration` to configure

Compatibility
-------------

[](#compatibility)

### Cache Compatibility

[](#cache-compatibility)

- **Drupal Core Cache**: ✅ Full support
- **Varnish**: ✅ Uses Vary headers
- **Cloudflare**: ✅ Compatible
- **Redis/Memcache**: ✅ Compatible

### Module Compatibility

[](#module-compatibility)

- **BigPipe**: ✅ Compatible
- **Dynamic Page Cache**: ✅ Compatible
- **Internal Page Cache**: ✅ Compatible
- **Ban Module**: ✅ Can be used together

API Reference
-------------

[](#api-reference)

### Services

[](#services)

```
// Get the Spyglasses client
$client = \Drupal::service('spyglasses.client');

// Detect bot traffic
$result = $client->detect($user_agent, $referrer);

// Sync patterns manually
$sync_service = \Drupal::service('spyglasses.pattern_sync');
$sync_service->syncIfNeeded();
```

### Configuration

[](#configuration-1)

```
// Get configuration
$config = \Drupal::config('spyglasses.settings');
$api_key = $config->get('api_key');
$debug_mode = $config->get('debug_mode');
```

Troubleshooting
---------------

[](#troubleshooting)

### Common Issues

[](#common-issues)

**No API Key Error**

- Ensure your API key is set in the configuration
- Check that the key doesn't contain invalid characters

**Patterns Not Syncing**

- Verify your API key is valid
- Check network connectivity to spyglasses.io
- Enable debug mode to see detailed error messages

**High Memory Usage**

- Reduce cache TTL if you have many patterns
- Check for conflicting modules that might interfere

### Debug Information

[](#debug-information)

```
# Check module status
drush pm:list | grep spyglasses

# View recent logs
drush watchdog:show --filter=spyglasses --count=20

# Clear caches
drush cache:rebuild

# Test pattern sync
drush php:eval "\Drupal::service('spyglasses.pattern_sync')->syncIfNeeded();"
```

Development
-----------

[](#development)

### Running Tests

[](#running-tests)

```
# PHPUnit tests
vendor/bin/phpunit modules/contrib/spyglasses/tests/

# Code standards
vendor/bin/phpcs --standard=Drupal modules/contrib/spyglasses/
```

### Contributing

[](#contributing)

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Security
--------

[](#security)

This module processes HTTP requests and makes external API calls. Security considerations:

- **API Key**: Store securely, never commit to version control
- **Input Validation**: All user input is sanitized
- **HTTPS**: All API communication uses HTTPS
- **Permissions**: Requires admin permissions to configure

Support
-------

[](#support)

- **Documentation**: [docs.spyglasses.io](https://www.spyglasses.io/docs/platforms/drupal)
- **Issues**: [GitHub Issues](https://github.com/orchestra-code/spyglasses-drupal/issues)
- **Email**:
- **Community**: [Drupal.org](https://www.drupal.org/project/spyglasses)

License
-------

[](#license)

This project is licensed under the GPL-2.0-or-later license. See the [LICENSE](LICENSE) file for details.

---

Made with ❤️ by [Orchestra AI](https://www.spyglasses.io)

###  Health Score

29

—

LowBetter than 57% of packages

Maintenance52

Moderate activity, may be stable

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

14

Last Release

335d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/234620130ee10b051af10cd66b794c208b087b59b8b2bcf361807188c6ce319e?d=identicon)[spyglasses](/maintainers/spyglasses)

---

Top Contributors

[![jwrubel](https://avatars.githubusercontent.com/u/1226418?v=4)](https://github.com/jwrubel "jwrubel (18 commits)")

---

Tags

middlewareaidrupalcrawleranalyticsbotdetectionclaudeChatGptperplexity

### Embed Badge

![Health badge](/badges/spyglasses-spyglasses/health.svg)

```
[![Health](https://phpackages.com/badges/spyglasses-spyglasses/health.svg)](https://phpackages.com/packages/spyglasses-spyglasses)
```

###  Alternatives

[helsingborg-stad/municipio

A bootstrap theme for creating municipality sites.

4028.6k10](/packages/helsingborg-stad-municipio)[pressbooks/pressbooks-book

This theme is named after Canadian media theorist Marshall McLuhan, who coined the phrase “the medium is the message.” It is designed for academic writing and is also suitable for fiction. Headings are set in Cormorant Garamond, and body type is set in Lora.

226.7k](/packages/pressbooks-pressbooks-book)[iamfarhad/laravel-prometheus

Production-ready Laravel Prometheus metrics package with built-in collectors for HTTP, database, cache, queue, events, errors, filesystem, and mail monitoring

112.2k](/packages/iamfarhad-laravel-prometheus)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)