Analytics in CommandKit
The analytics plugin for CommandKit enables analytics in your project. It provides a simple and efficient way to track events and metrics. CommandKit itself does not store any analytics data - it acts as a bridge between your application and your chosen analytics provider.
How it Works
CommandKit's analytics system is designed to be provider-agnostic. This means:
- CommandKit doesn't store any analytics data itself
- All data is sent directly to your configured analytics provider
- You can easily switch between different providers or use multiple providers
- The system is extensible, allowing you to create custom providers
Automatic Tracking
CommandKit automatically tracks various anonymous metrics:
- Command execution events (
command_execution
) - Cache performance metrics:
- Cache hits (
cache_hit
) - Cache misses (
cache_miss
) - Cache revalidations (
cache_revalidated
)
- Cache hits (
- Feature flag metrics:
- Feature flag metrics (
feature_flag_metrics
) - Feature flag decisions (
feature_flag_decision
)
- Feature flag metrics (
- Anonymous interaction patterns
Installation
npm install @commandkit/analytics
Basic Usage
To track custom events in your Discord bot:
import { track } from 'commandkit/analytics';
// Track a custom event with anonymous data
await track({
name: 'button_interaction',
data: {
buttonType: 'verification',
// Use hashed or anonymous identifiers if needed
interactionType: 'button',
// Track timing for performance metrics
responseTime: 150,
},
});
Filtering Events
You can filter out specific events using the setFilter
function:
import { useAnalytics } from 'commandkit/analytics';
const analytics = useAnalytics();
// Filter out events based on anonymous criteria
analytics.setFilter((engine, event) => {
// Skip events from development environments
if (process.env.NODE_ENV === 'development') {
return false; // false means skip this event
}
// Skip specific event types
if (event.name === 'debug_event') {
return false;
}
return true; // true means track this event
});
Available Providers
CommandKit comes with built-in support for popular analytics providers:
Creating Custom Providers
You can create your own analytics provider by implementing the AnalyticsProvider
interface. See our Custom Providers guide for detailed instructions.
Disabling Analytics
You can disable analytics for specific requests (i.e. command or event scoped) using the noAnalytics
function:
import { noAnalytics } from 'commandkit/analytics';
// Disable analytics for specific commands or events
if (interaction.commandName === 'debug') {
noAnalytics();
}
Privacy Considerations
When implementing analytics in your bot, consider:
- Only track anonymous, aggregated data
- Avoid storing personal information
- Use hashed identifiers when necessary
- Be transparent about what data you collect
- Respect user privacy and Discord's Terms of Service
Next Steps
- Learn how to set up PostHog
- Learn how to set up Umami
- Learn how to create custom providers