Agent Analytics Setup
Get agent traffic tracking live on your docs in under an hour. This playbook walks you through installing the Lightsage middleware, verifying detection, and creating your first analytics dashboard.
Prerequisites
Make sure you have these before starting.
Vercel, Cloudflare Pages, or any Node.js-compatible server
The 7-day trial works for getting started
Ability to deploy middleware changes
What you'll do
Install Lightsage middleware
Configure environment variables
Verify agent detection is working
Set up conversion tracking
Create first dashboard
Install Lightsage middleware
~5 minutes
The Lightsage middleware runs at the edge and detects AI agent traffic by analyzing request headers and patterns. It adds minimal latency (typically under 5ms) and works with any JavaScript runtime.
Install the package
npm install @lightsage/middlewareOr use yarn: yarn add @lightsage/middleware
Create the middleware file
Create a middleware.ts file in your project root (for Next.js) or the appropriate location for your framework.
import { lightsage } from '@lightsage/middleware';
export const middleware = lightsage({
publicKey: process.env.LIGHTSAGE_PUBLIC_KEY!,
});
export const config = {
matcher: [
// Match all paths except static files and API routes
'/((?!_next/static|_next/image|favicon.ico|api/).*)',
],
};Tip: The matcher configuration ensures the middleware only runs on content pages, not static assets. This keeps performance optimal.
Configure environment variables
~2 minutes
Get your public key from the Lightsage dashboard and add it to your environment configuration.
Get your public key
- Log in to the Lightsage dashboard
- Navigate to Settings > API Keys
- Copy your public key (starts with
pk_)
Add to your environment
LIGHTSAGE_PUBLIC_KEY=pk_live_your_key_herePlatform-specific configuration
Vercel
Add the environment variable in Project Settings > Environment Variables. Make sure to add it to all environments (Production, Preview, Development).
Cloudflare Pages
Add the variable in Settings > Environment variables. Use the wrangler CLI for local development: wrangler secret put LIGHTSAGE_PUBLIC_KEY
Self-hosted
Set the environment variable in your deployment configuration, Docker compose file, or server environment.
Verify agent detection is working
~5 minutes
After deploying, verify that the middleware is correctly detecting traffic. You can test this locally or in production.
Test locally with curl
Simulate an AI agent request to verify detection:
# Simulate Claude Code user agent
curl -H "User-Agent: claudebot/1.0" http://localhost:3000/docs
# Simulate Cursor agent
curl -H "User-Agent: cursor-ai/1.0" http://localhost:3000/docs
# Simulate ChatGPT plugin
curl -H "User-Agent: ChatGPT-User" http://localhost:3000/docsCheck the Lightsage dashboard
- Open the Lightsage dashboard
- Navigate to Analytics > Real-time
- You should see your test requests appear within 30 seconds
- Verify the agent type is correctly identified
Enable debug mode (optional)
For troubleshooting, enable debug logging:
export const middleware = lightsage({
publicKey: process.env.LIGHTSAGE_PUBLIC_KEY!,
debug: process.env.NODE_ENV === 'development',
});Debug mode logs detected agents and attribution data to the console.
At this point, you should see test requests in your Lightsage dashboard. If not, check the Troubleshooting section below.
Set up conversion tracking
~10 minutes
Connect agent visits to actual conversions like signups, API key generation, or purchases. This lets you attribute revenue to specific agents.
Install the client SDK
npm install @lightsage/clientTrack a signup conversion
Call trackConversion when a user completes a valuable action:
import { trackConversion } from '@lightsage/client';
async function handleSignup(formData: FormData) {
// Your existing signup logic
const user = await createUser(formData);
// Track the conversion
await trackConversion({
event: 'signup',
userId: user.id,
properties: {
plan: 'free',
source: 'docs',
},
});
}Common conversion events
| Event | When to fire |
|---|---|
| signup | User creates an account |
| api_key_created | User generates their first API key |
| first_api_call | User makes their first successful API request |
| upgrade | User upgrades to a paid plan |
Server-side tracking (recommended for revenue)
For purchase events, use server-side tracking for accuracy:
import { Lightsage } from '@lightsage/node';
const lightsage = new Lightsage({
secretKey: process.env.LIGHTSAGE_SECRET_KEY!,
});
export async function POST(req: Request) {
const event = await parseStripeWebhook(req);
if (event.type === 'checkout.session.completed') {
await lightsage.trackConversion({
event: 'purchase',
userId: event.data.object.client_reference_id,
revenue: event.data.object.amount_total / 100,
currency: 'USD',
});
}
}Create first dashboard
~8 minutes
Set up a dashboard to monitor agent traffic patterns and conversion attribution.
Key metrics to track
Agent Traffic Share
What percentage of your docs traffic comes from AI agents vs browsers?
Top Agents
Which agents visit most: Claude Code, Cursor, ChatGPT, Codex?
Top Pages
Which documentation pages do agents visit most frequently?
Conversion Rate
How often do agent sessions lead to signups vs browser sessions?
Create your first chart
- Go to Analytics > Dashboards in Lightsage
- Click Create Dashboard
- Add a Time Series chart
- Set metric to Page Views
- Group by Agent Type
- Set time range to Last 7 days
Set up alerts (optional)
Get notified when agent traffic patterns change significantly:
- Alert when agent traffic share drops below 10%
- Alert when a new agent type starts visiting
- Weekly digest of agent traffic trends
Agent analytics is now live. Give it 24-48 hours to collect meaningful data, then review your dashboard to understand how AI agents interact with your docs.
Platform-specific setup
Vercel (Next.js)
If you have existing middleware, compose them together:
import { lightsage } from '@lightsage/middleware';
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
const lightsageMiddleware = lightsage({
publicKey: process.env.LIGHTSAGE_PUBLIC_KEY!,
});
export async function middleware(request: NextRequest) {
// Run Lightsage first
const response = await lightsageMiddleware(request);
// Add your custom middleware logic
// Example: Add security headers
response.headers.set('X-Frame-Options', 'DENY');
return response;
}Cloudflare Pages
Use the Cloudflare-specific adapter for optimal edge performance:
import { lightsageCloudflare } from '@lightsage/middleware/cloudflare';
export const onRequest = lightsageCloudflare({
publicKey: env.LIGHTSAGE_PUBLIC_KEY,
});Mintlify
Add the Lightsage script to your Mintlify configuration:
{
"integrations": {
"lightsage": {
"publicKey": "pk_live_your_key_here"
}
}
}Note: Mintlify's built-in integration handles agent detection automatically. No middleware setup required.
Troubleshooting
No agent traffic showing up
- Verify middleware is deployed and running
- Check that LIGHTSAGE_PUBLIC_KEY is set correctly
- Confirm the middleware file is in the correct location
- Wait 2-3 minutes for data to appear in dashboard
Middleware conflicts with existing middleware
- Ensure lightsage middleware runs first in the chain
- Use the compose pattern shown in the Vercel section
- Check for path conflicts in matcher config
High latency after adding middleware
- Enable async mode: async: true in config
- Check if your edge location is far from Lightsage servers
- Verify you're using the edge-compatible package version
Conversions not being attributed
- Ensure trackConversion is called after user action completes
- Check that the same session ID is being used
- Verify event names match your dashboard configuration
Still stuck? Check the Agent Analytics overview or contact support.
Ready to see your agent traffic?
Set up takes 30 minutes. Start tracking which AI agents visit your docs today.