Analytics service setup with first use in Ping command

Author: firasrg

application/src/main/java/org/togetherjava/tjbot/features/Features.java

@@ -6,6 +6,7 @@
 import org.togetherjava.tjbot.config.FeatureBlacklist;
 import org.togetherjava.tjbot.config.FeatureBlacklistConfig;
 import org.togetherjava.tjbot.db.Database;
+import org.togetherjava.tjbot.features.analytics.AnalyticsService;
 import org.togetherjava.tjbot.features.basic.MemberCountDisplayRoutine;
 import org.togetherjava.tjbot.features.basic.PingCommand;
 import org.togetherjava.tjbot.features.basic.QuoteBoardForwarder;
@@ -128,6 +129,7 @@ public static Collection<Feature> createFeatures(JDA jda, Database database, Con
         TopHelpersService topHelpersService = new TopHelpersService(database);
         TopHelpersAssignmentRoutine topHelpersAssignmentRoutine =
                 new TopHelpersAssignmentRoutine(config, topHelpersService);
+        AnalyticsService analyticsService = new AnalyticsService(database);
 
         // NOTE The system can add special system relevant commands also by itself,
         // hence this list may not necessarily represent the full list of all commands actually
@@ -184,7 +186,7 @@ public static Collection<Feature> createFeatures(JDA jda, Database database, Con
 
         // Slash commands
         features.add(new LogLevelCommand());
-        features.add(new PingCommand());
+        features.add(new PingCommand(analyticsService));
         features.add(new TeXCommand());
         features.add(new TagCommand(tagSystem));
         features.add(new TagManageCommand(tagSystem, modAuditLogWriter));

application/src/main/java/org/togetherjava/tjbot/features/analytics/AnalyticsService.java

@@ -0,0 +1,84 @@
+package org.togetherjava.tjbot.features.analytics;
+
+import org.jetbrains.annotations.Nullable;
+import org.jooq.impl.DSL;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import org.togetherjava.tjbot.db.Database;
+
+/**
+ * Service for tracking and recording command usage analytics.
+ * <p>
+ * This service records every command execution along with its success/failure status, allowing for
+ * analysis of command usage patterns, popular commands, error rates, and activity over time.
+ * <p>
+ * Commands should call {@link #recordCommandExecution(long, String, long, boolean, String)} after
+ * execution to track their usage.
+ */
+public final class AnalyticsService {
+    private static final Logger logger = LoggerFactory.getLogger(AnalyticsService.class);
+
+    private final Database database;
+
+    /**
+     * Creates a new instance.
+     *
+     * @param database the database to use for storing and retrieving analytics data
+     */
+    public AnalyticsService(Database database) {
+        this.database = database;
+    }
+
+    /**
+     * Records a command execution with success/failure status.
+     * <p>
+     * This method should be called by commands after they complete execution to track usage
+     * patterns and error rates.
+     *
+     * @param guildId the guild ID where the command was executed
+     * @param commandName the name of the command that was executed
+     * @param userId the ID of the user who executed the command
+     * @param success whether the command executed successfully
+     * @param errorMessage optional error message if the command failed (null if successful)
+     */
+    public void recordCommandExecution(long guildId, String commandName, long userId,
+            boolean success, @Nullable String errorMessage) {
+
+        database.write(context -> context
+            .insertInto(DSL.table("command_usage"), DSL.field("guild_id"),
+                    DSL.field("command_name"), DSL.field("user_id"), DSL.field("executed_at"),
+                    DSL.field("success"), DSL.field("error_message"))
+            .values(guildId, commandName, userId, DSL.currentTimestamp(), success, errorMessage)
+            .execute());
+
+        if (!success && errorMessage != null) {
+            logger.warn("Command '{}' failed in guild {} with error: {}", commandName, guildId,
+                    errorMessage);
+        }
+    }
+
+    /**
+     * Records a successful command execution.
+     *
+     * @param guildId the guild ID where the command was executed
+     * @param commandName the name of the command that was executed
+     * @param userId the ID of the user who executed the command
+     */
+    public void recordCommandSuccess(long guildId, String commandName, long userId) {
+        recordCommandExecution(guildId, commandName, userId, true, null);
+    }
+
+    /**
+     * Records a failed command execution.
+     *
+     * @param guildId the guild ID where the command was executed
+     * @param commandName the name of the command that was executed
+     * @param userId the ID of the user who executed the command
+     * @param errorMessage a description of what went wrong
+     */
+    public void recordCommandFailure(long guildId, String commandName, long userId,
+            String errorMessage) {
+        recordCommandExecution(guildId, commandName, userId, false, errorMessage);
+    }
+}

application/src/main/java/org/togetherjava/tjbot/features/analytics/package-info.java

@@ -0,0 +1,13 @@
+/**
+ * Analytics system for collecting and persisting bot activity metrics.
+ * <p>
+ * This package provides services and components that record events for later analysis and reporting
+ * across multiple feature areas, not limited to commands.
+ */
+@MethodsReturnNonnullByDefault
+@ParametersAreNonnullByDefault
+package org.togetherjava.tjbot.features.analytics;
+
+import org.togetherjava.tjbot.annotations.MethodsReturnNonnullByDefault;
+
+import javax.annotation.ParametersAreNonnullByDefault;

application/src/main/java/org/togetherjava/tjbot/features/basic/PingCommand.java

@@ -1,21 +1,28 @@
 package org.togetherjava.tjbot.features.basic;
 
+import net.dv8tion.jda.api.entities.Guild;
 import net.dv8tion.jda.api.events.interaction.command.SlashCommandInteractionEvent;
 
 import org.togetherjava.tjbot.features.CommandVisibility;
 import org.togetherjava.tjbot.features.SlashCommandAdapter;
+import org.togetherjava.tjbot.features.analytics.AnalyticsService;
 
 /**
  * Implementation of an example command to illustrate how to respond to a user.
  * <p>
  * The implemented command is {@code /ping}, upon which the bot will respond with {@code Pong!}.
  */
 public final class PingCommand extends SlashCommandAdapter {
+    private final AnalyticsService analyticsService;
+
     /**
      * Creates an instance of the ping pong command.
+     *
+     * @param analyticsService the analytics service to track command usage
      */
-    public PingCommand() {
+    public PingCommand(AnalyticsService analyticsService) {
         super("ping", "Bot responds with 'Pong!'", CommandVisibility.GUILD);
+        this.analyticsService = analyticsService;
     }
 
     /**
@@ -25,6 +32,23 @@ public PingCommand() {
      */
     @Override
     public void onSlashCommand(SlashCommandInteractionEvent event) {
-        event.reply("Pong!").queue();
+        Guild guild = event.getGuild();
+        if (guild == null) {
+            event.reply("This command can only be used in a server!").setEphemeral(true).queue();
+            return;
+        }
+
+        try {
+            event.reply("Pong!").queue();
+
+            analyticsService.recordCommandSuccess(guild.getIdLong(), getName(),
+                    event.getUser().getIdLong());
+
+        } catch (Exception e) {
+            analyticsService.recordCommandFailure(guild.getIdLong(), getName(),
+                    event.getUser().getIdLong(),
+                    e.getMessage() != null ? e.getMessage() : e.getClass().getSimpleName());
+            throw e;
+        }
     }
 }

application/src/main/resources/db/V16__Add_Analytics_System.sql

@@ -0,0 +1,13 @@
+CREATE TABLE command_usage
+(
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    guild_id      INTEGER NOT NULL,
+    command_name  TEXT    NOT NULL,
+    user_id       INTEGER NOT NULL,
+    executed_at   DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    success       BOOLEAN NOT NULL DEFAULT TRUE,
+    error_message TEXT
+);
+
+CREATE INDEX idx_command_usage_guild ON command_usage(guild_id);
+CREATE INDEX idx_command_usage_command_name ON command_usage(command_name);

application/src/test/java/org/togetherjava/tjbot/features/basic/PingCommandTest.java

@@ -6,13 +6,16 @@
 import org.junit.jupiter.api.Test;
 
 import org.togetherjava.tjbot.features.SlashCommand;
+import org.togetherjava.tjbot.features.analytics.AnalyticsService;
 import org.togetherjava.tjbot.jda.JdaTester;
 
+import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.verify;
 
 final class PingCommandTest {
     private JdaTester jdaTester;
     private SlashCommand command;
+    private AnalyticsService analyticsService;
 
     private SlashCommandInteractionEvent triggerSlashCommand() {
         SlashCommandInteractionEvent event =
@@ -24,7 +27,8 @@ private SlashCommandInteractionEvent triggerSlashCommand() {
     @BeforeEach
     void setUp() {
         jdaTester = new JdaTester();
-        command = jdaTester.spySlashCommand(new PingCommand());
+        analyticsService = mock(AnalyticsService.class);
+        command = jdaTester.spySlashCommand(new PingCommand(analyticsService));
     }
 
     @Test