Skip to main content
Version: Next

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:

  1. CommandKit doesn't store any analytics data itself
  2. All data is sent directly to your configured analytics provider
  3. You can easily switch between different providers or use multiple providers
  4. 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)
  • Feature flag metrics:
    • Feature flag metrics (feature_flag_metrics)
    • Feature flag decisions (feature_flag_decision)
  • 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:

  1. Only track anonymous, aggregated data
  2. Avoid storing personal information
  3. Use hashed identifiers when necessary
  4. Be transparent about what data you collect
  5. Respect user privacy and Discord's Terms of Service

Next Steps​