AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.
feat(backend): add bot usage analytics (events + presence) (#13325)
Bentlya66aa2558de3
diff --git a/autogpt_platform/backend/backend/copilot/bot/adapters/discord/adapter.py b/autogpt_platform/backend/backend/copilot/bot/adapters/discord/adapter.pyindex ad8fca7a0d..80d48e788b 100644--- a/autogpt_platform/backend/backend/copilot/bot/adapters/discord/adapter.py+++ b/autogpt_platform/backend/backend/copilot/bot/adapters/discord/adapter.py@@ -211,6 +211,13 @@ class DiscordAdapter(PlatformAdapter):# rows that pre-date name capture. Cheap: in-memory cache only,# no Discord API calls.await self._refresh_known_server_names()+ # Reconcile presence analytics: record every server we're currently+ # in and mark any we've left while disconnected. Drives the admin+ # server-count / sharding-prediction charts.+ self._api.sync_guilds(+ "discord",+ [(str(guild.id), guild.name) for guild in self._client.guilds],+ )# Sync slash commands once per process — on_ready fires on every# gateway reconnect, but the command tree only needs uploading once.if self._commands_synced:@@ -225,6 +232,7 @@ class DiscordAdapter(PlatformAdapter):@self._client.eventasync def on_guild_join(guild: discord.Guild) -> None:await self._refresh_server_name(guild)+ self._api.track_guild_joined("discord", str(guild.id), guild.name)channel = intro.pick_intro_channel(guild)if channel is None:logger.info(@@ -245,6 +253,12 @@ class DiscordAdapter(PlatformAdapter):if before.name != after.name:await self._refresh_server_name(after)+ @self._client.event+ async def on_guild_remove(guild: discord.Guild) -> None:+ # Bot was kicked or the server was deleted — mark presence as left+ # so the live server count and sharding prediction stay accurate.+ self._api.track_guild_left("discord", str(guild.id))+@self._client.eventasync def on_thread_remove(thread: discord.Thread) -> None:# Fires when a thread is removed from the client's cache — thediff --git a/autogpt_platform/backend/backend/copilot/bot/adapters/discord/commands.py b/autogpt_platform/backend/backend/copilot/bot/adapters/discord/commands.pyindex 1c35f1bcb1..768abbdf81 100644--- a/autogpt_platform/backend/backend/copilot/bot/adapters/discord/commands.py+++ b/autogpt_platform/backend/backend/copilot/bot/adapters/discord/commands.py@@ -22,16 +22,26 @@ logger = logging.getLogger(__name__)def register(tree: app_commands.CommandTree, api: BotBackend) -> None:"""Register all slash commands on the given CommandTree."""+ def _track(interaction: discord.Interaction, command_name: str) -> None:+ api.track_event(+ platform="discord",+ event_type="command_used",+ server_id=str(interaction.guild.id) if interaction.guild else None,+ command_name=command_name,+ )+@tree.command(name="setup",description="Link this server to an AutoGPT account for AutoPilot",)@app_commands.default_permissions(manage_guild=True)async def setup_command(interaction: discord.Interaction) -> None:+ _track(interaction, "setup")await _handle_setup(interaction, api)@tree.command(name="help", description="Show AutoPilot bot usage info")async def help_command(interaction: discord.Interaction) -> None:+ _track(interaction, "help")await _handle_help(interaction)@tree.command(@@ -39,6 +49,7 @@ def register(tree: app_commands.CommandTree, api: BotBackend) -> None:description="Manage linked servers from your AutoGPT settings",)async def unlink_command(interaction: discord.Interaction) -> None:+ _track(interaction, "unlink")await _handle_unlink(interaction)@tree.command(@@ -46,6 +57,7 @@ def register(tree: app_commands.CommandTree, api: BotBackend) -> None:description="Start a fresh AutoPilot conversation in this DM or thread",)async def new_command(interaction: discord.Interaction) -> None:+ _track(interaction, "new")await _handle_new(interaction)@tree.command(@@ -53,6 +65,7 @@ def register(tree: app_commands.CommandTree, api: BotBackend) -> None:description="Resume one of your past AutoPilot conversations (DMs only)",)async def resume_command(interaction: discord.Interaction) -> None:+ _track(interaction, "resume")await _handle_resume(interaction, api)@tree.command(@@ -60,6 +73,7 @@ def register(tree: app_commands.CommandTree, api: BotBackend) -> None:description="Stop AutoPilot from auto-replying in this thread",)async def leave_command(interaction: discord.Interaction) -> None:+ _track(interaction, "leave")await _handle_leave(interaction)diff --git a/autogpt_platform/backend/backend/copilot/bot/bot_backend.py b/autogpt_platform/backend/backend/copilot/bot/bot_backend.pyindex d13d5d1a15..a006605c2a 100644--- a/autogpt_platform/backend/backend/copilot/bot/bot_backend.py+++ b/autogpt_platform/backend/backend/copilot/bot/bot_backend.py@@ -25,6 +25,8 @@ from backend.copilot.response_model import ()from backend.platform_linking.models import (BotChatRequest,+ BotEventInput,+ BotGuildInput,CreateLinkTokenRequest,CreateUserLinkTokenRequest,Platform,@@ -44,8 +46,22 @@ STREAM_CHUNK_TIMEOUT_SECONDS = 120logger = logging.getLogger(__name__)++class BotStreamError(Exception):+ """A copilot stream couldn't produce a successful reply.++ Carries a bounded ``error_kind`` so the handler can attribute analytics+ accurately instead of guessing from the inline text.+ """++ def __init__(self, error_kind: str, message: str):+ super().__init__(message)+ self.error_kind = error_kind++__all__ = ["BotBackend",+ "BotStreamError","ChatSummary","DuplicateChatMessageError","LinkAlreadyExistsError",@@ -84,12 +100,104 @@ class BotBackend:def __init__(self):self._client = get_platform_linking_manager_client()+ self._analytics_tasks: set[asyncio.Task] = set()async def close(self) -> None:# The client's lifecycle is owned by the thread-cached factory; nothing# to close here. Kept for API compatibility with older bot code.pass+ # ── Analytics (fire-and-forget) ──────────────────────────────────────+ # Usage telemetry must never block or break a user's reply, so every+ # write is scheduled as a background task that swallows its own errors.+ # No message content is ever sent — only counts, enums and metrics.++ def _fire_and_forget(self, coro: Awaitable[None]) -> None:+ task = asyncio.ensure_future(coro)+ self._analytics_tasks.add(task)+ task.add_done_callback(self._on_analytics_done)++ def _on_analytics_done(self, task: asyncio.Task) -> None:+ self._analytics_tasks.discard(task)+ if task.cancelled():+ return+ exc = task.exception()+ if exc is not None:+ logger.warning("Bot analytics write failed: %s", exc)++ # NOTE: each track method defers Platform() and Pydantic construction into+ # the background coroutine — that way a bad platform string or validation+ # error fails the analytics task (which is swallowed) instead of leaking+ # back into the caller's reply path.++ def track_event(+ self,+ *,+ platform: str,+ event_type: str,+ server_id: str | None = None,+ channel_type: str | None = None,+ command_name: str | None = None,+ error_kind: str | None = None,+ char_count: int | None = None,+ duration_ms: int | None = None,+ ) -> None:+ async def _send() -> None:+ await self._client.record_bot_event(+ event=BotEventInput(+ platform=Platform(platform.upper()),+ event_type=event_type,+ server_id=server_id,+ channel_type=channel_type,+ command_name=command_name,+ error_kind=error_kind,+ char_count=char_count,+ duration_ms=duration_ms,+ )+ )++ self._fire_and_forget(_send())++ def track_guild_joined(+ self, platform: str, server_id: str, name: str | None = None+ ) -> None:+ async def _send() -> None:+ await self._client.record_guild_joined(+ guild=BotGuildInput(+ platform=Platform(platform.upper()),+ server_id=server_id,+ name=name,+ )+ )++ self._fire_and_forget(_send())++ def track_guild_left(self, platform: str, server_id: str) -> None:+ async def _send() -> None:+ await self._client.mark_guild_left(+ platform=Platform(platform.upper()),+ server_id=server_id,+ )++ self._fire_and_forget(_send())++ def sync_guilds(self, platform: str, guilds: list[tuple[str, str | None]]) -> None:+ async def _send() -> None:+ platform_enum = Platform(platform.upper())+ await self._client.sync_guild_presence(+ platform=platform_enum,+ guilds=[+ BotGuildInput(+ platform=platform_enum,+ server_id=server_id,+ name=name,+ )+ for server_id, name in guilds+ ],+ )++ self._fire_and_forget(_send())+async def resolve_server(self, platform: str, platform_server_id: str) -> ResolveResult:@@ -234,8 +342,10 @@ class BotBackend:last_message_id=handle.subscribe_from,)if queue is None:- yield "\n[Error: failed to subscribe to response stream]"- return+ raise BotStreamError(+ "subscribe_failed",+ "failed to subscribe to response stream",+ )setup_notified = False@@ -251,8 +361,10 @@ class BotBackend:STREAM_CHUNK_TIMEOUT_SECONDS,handle.session_id,)- yield "\n[Error: response timed out]"- return+ raise BotStreamError(+ "stream_timeout",+ "response timed out",+ )if isinstance(chunk, StreamTextDelta):if chunk.delta:yield chunk.delta@@ -269,8 +381,10 @@ class BotBackend:returnelif isinstance(chunk, StreamError):logger.error("Stream error from backend: %s", chunk.errorText)- yield f"\n[Error: {chunk.errorText}]"- return+ raise BotStreamError(+ "backend_stream_error",+ chunk.errorText,+ )# Other StreamX types (StreamStart, StreamTextStart, tool events,# etc.) are emitted by the executor for the frontend UI and# aren't useful for the plain-text bot transcript.diff --git a/autogpt_platform/backend/backend/copilot/bot/bot_backend_analytics_test.py b/autogpt_platform/backend/backend/copilot/bot/bot_backend_analytics_test.pynew file mode 100644index 0000000000..0e572e95e3--- /dev/null+++ b/autogpt_platform/backend/backend/copilot/bot/bot_backend_analytics_test.py@@ -0,0 +1,114 @@+"""Tests for BotBackend fire-and-forget analytics methods."""++import asyncio+from unittest.mock import AsyncMock++import pytest++from backend.copilot.bot.bot_backend import BotBackend+from backend.platform_linking.models import BotEventInput, BotGuildInput, Platform+++def _backend() -> tuple[BotBackend, AsyncMock]:+ backend = BotBackend.__new__(BotBackend)+ client = AsyncMock()+ backend._client = client+ backend._analytics_tasks = set()+ return backend, client+++async def _drain(backend: BotBackend) -> None:+ if backend._analytics_tasks:+ await asyncio.gather(*backend._analytics_tasks, return_exceptions=True)+++async def test_track_event_records_bot_event():+ backend, client = _backend()+ backend.track_event(+ platform="discord",+ event_type="message_received",+ server_id="42",+ channel_type="thread",+ char_count=12,+ )+ await _drain(backend)++ client.record_bot_event.assert_awaited_once()+ event = client.record_bot_event.await_args.kwargs["event"]+ assert isinstance(event, BotEventInput)+ assert event.platform == Platform.DISCORD+ assert event.event_type == "message_received"+ assert event.server_id == "42"+ assert event.channel_type == "thread"+ assert event.char_count == 12+++async def test_track_guild_joined_and_left():+ backend, client = _backend()+ backend.track_guild_joined("discord", "7", "Cool Server")+ backend.track_guild_left("discord", "7")+ await _drain(backend)++ guild = client.record_guild_joined.await_args.kwargs["guild"]+ assert isinstance(guild, BotGuildInput)+ assert guild.server_id == "7"+ assert guild.name == "Cool Server"+ client.mark_guild_left.assert_awaited_once_with(+ platform=Platform.DISCORD, server_id="7"+ )+++async def test_sync_guilds_maps_all_servers():+ backend, client = _backend()+ backend.sync_guilds("discord", [("1", "A"), ("2", None)])+ await _drain(backend)++ kwargs = client.sync_guild_presence.await_args.kwargs+ assert kwargs["platform"] == Platform.DISCORD+ guilds = kwargs["guilds"]+ assert [g.server_id for g in guilds] == ["1", "2"]+ assert guilds[1].name is None+++async def test_analytics_failure_is_swallowed():+ backend, client = _backend()+ client.record_bot_event.side_effect = RuntimeError("rpc down")+ backend.track_event(platform="discord", event_type="message_received")+ # A failing write must never propagate into the caller's reply path.+ await _drain(backend)+ assert backend._analytics_tasks == set()+++async def test_bad_platform_string_is_swallowed():+ # Platform(...) raises ValueError on an unknown string. That must fail the+ # background task — never the synchronous caller in the reply path.+ backend, client = _backend()+ backend.track_event(platform="myspace", event_type="message_received")+ await _drain(backend)+ assert backend._analytics_tasks == set()+ # The bad platform must short-circuit before the RPC; the client must not+ # have been called.+ client.record_bot_event.assert_not_called()+++async def test_cancelled_analytics_task_is_silent():+ # Cancelled tasks during shutdown must not raise CancelledError from the+ # done-callback (which would print as an unhandled exception by asyncio).+ backend, client = _backend()++ async def hang() -> None:+ await asyncio.sleep(3600)++ client.record_bot_event.side_effect = lambda **_: hang()+ backend.track_event(platform="discord", event_type="message_received")+ task = next(iter(backend._analytics_tasks))+ task.cancel()+ with pytest.raises(asyncio.CancelledError):+ await task+ assert backend._analytics_tasks == set()diff --git a/autogpt_platform/backend/backend/copilot/bot/bot_backend_test.py b/autogpt_platform/backend/backend/copilot/bot/bot_backend_test.pyindex d998494309..b5f3e39c91 100644--- a/autogpt_platform/backend/backend/copilot/bot/bot_backend_test.py+++ b/autogpt_platform/backend/backend/copilot/bot/bot_backend_test.py@@ -24,7 +24,7 @@ from backend.util.exceptions import (NotFoundError,)-from .bot_backend import BotBackend+from .bot_backend import BotBackend, BotStreamError@pytest.fixture@@ -180,14 +180,15 @@ class TestStreamChat:"backend.copilot.bot.bot_backend.stream_registry.unsubscribe_from_session",new=AsyncMock(),),+ pytest.raises(BotStreamError) as excinfo,):- chunks: list[str] = []- async for chunk in api.stream_chat(+ async for _ in api.stream_chat(platform="discord", platform_user_id="u1", message="hi"):- chunks.append(chunk)+ pass- assert any("executor crashed" in c for c in chunks)+ assert excinfo.value.error_kind == "backend_stream_error"+ assert "executor crashed" in str(excinfo.value)@pytest.mark.asyncioasync def test_notifies_setup_requirements_tool_output(self, api: BotBackend):@@ -266,7 +267,7 @@ class TestStreamChat:pass@pytest.mark.asyncio- async def test_subscribe_returns_none_yields_error(self, api: BotBackend):+ async def test_subscribe_returns_none_raises(self, api: BotBackend):handle = ChatTurnHandle(session_id="sess", turn_id="turn", user_id="u1")api._client.start_chat_turn = AsyncMock(return_value=handle)@@ -279,11 +280,11 @@ class TestStreamChat:"backend.copilot.bot.bot_backend.stream_registry.unsubscribe_from_session",new=AsyncMock(),),+ pytest.raises(BotStreamError) as excinfo,):- chunks: list[str] = []- async for chunk in api.stream_chat(+ async for _ in api.stream_chat(platform="discord", platform_user_id="u1", message="hi"):- chunks.append(chunk)+ pass- assert any("failed to subscribe" in c.lower() for c in chunks)+ assert excinfo.value.error_kind == "subscribe_failed"diff --git a/autogpt_platform/backend/backend/copilot/bot/handler.py b/autogpt_platform/backend/backend/copilot/bot/handler.pyindex 627c92d111..e6865de01c 100644--- a/autogpt_platform/backend/backend/copilot/bot/handler.py+++ b/autogpt_platform/backend/backend/copilot/bot/handler.py@@ -7,6 +7,7 @@ persistent typing indicator.import asyncioimport logging+import timefrom dataclasses import dataclass, fieldfrom typing import Anyfrom urllib.parse import quote@@ -25,7 +26,7 @@ from backend.util.settings import Settingsfrom . import sessions, threadsfrom .adapters.base import FileAttachment, MessageContext, PlatformAdapter-from .bot_backend import BotBackend+from .bot_backend import BotBackend, BotStreamErrorfrom .config import SESSION_TTLfrom .text import format_batch, split_at_boundary@@ -90,6 +91,14 @@ class MessageHandler:if not target_id:return # Thread not subscribed, ignore silently+ self._api.track_event(+ platform=ctx.platform,+ event_type="message_received",+ server_id=ctx.server_id,+ channel_type=ctx.channel_type,+ char_count=len(ctx.text),+ )+message_text = self._message_text(ctx) if include_thread_history else ctx.textawait self._enqueue_and_process(ctx, adapter, target_id, message_text)@@ -353,6 +362,8 @@ class MessageHandler:link_url=session_url,)+ started_at = time.monotonic()+ reply_chars = 0typing_task = asyncio.create_task(_keep_typing(adapter, target_id))try:async for chunk in self._api.stream_chat(@@ -365,6 +376,7 @@ class MessageHandler:on_setup_required=_on_setup_required,):buffer += chunk+ reply_chars += len(chunk)if len(buffer) >= flush_at:post, buffer = split_at_boundary(buffer, flush_at)if post and post.strip():@@ -377,8 +389,25 @@ class MessageHandler:# stay quiet so the user doesn't get a double response.logger.info("Duplicate message dropped for target %s", target_id)return+ except BotStreamError as exc:+ # Stream couldn't complete (timeout, subscribe fail, backend stream+ # error). Track the specific kind, surface a generic message, and+ # do NOT fire reply_sent below.+ logger.warning(+ "Stream failed for target %s: %s (%s)",+ target_id,+ exc,+ exc.error_kind,+ )+ self._track_stream_error(ctx, exc.error_kind)+ await adapter.send_message(+ target_id,+ "AutoPilot ran into an error. Try again in a moment.",+ )+ returnexcept NotFoundError:logger.exception("Chat turn rejected")+ self._track_stream_error(ctx, "chat_turn_rejected")await adapter.send_message(target_id, "AutoPilot ran into an error. Try again later.")@@ -387,6 +416,7 @@ class MessageHandler:logger.exception("Unexpected error during streaming for target %s", target_id)+ self._track_stream_error(ctx, "stream_exception")await adapter.send_message(target_id,"Something went wrong. Try again in a moment.",@@ -411,6 +441,17 @@ class MessageHandler:target_id,"AutoPilot didn't produce a response. Try rephrasing your question.",)+ self._track_stream_error(ctx, "empty_reply")+ return++ self._api.track_event(+ platform=ctx.platform,+ event_type="reply_sent",+ server_id=ctx.server_id,+ channel_type=ctx.channel_type,+ char_count=reply_chars,+ duration_ms=int((time.monotonic() - started_at) * 1000),+ )if (ctx.channel_type == "channel"@@ -450,6 +491,15 @@ class MessageHandler:if attempt < TITLE_RENAME_ATTEMPTS - 1:await asyncio.sleep(TITLE_RENAME_INTERVAL_SECONDS)+ def _track_stream_error(self, ctx: MessageContext, error_kind: str) -> None:+ self._api.track_event(+ platform=ctx.platform,+ event_type="stream_error",+ server_id=ctx.server_id,+ channel_type=ctx.channel_type,+ error_kind=error_kind,+ )+# -- Linking --async def _ensure_linked(diff --git a/autogpt_platform/backend/backend/data/bot_analytics.py b/autogpt_platform/backend/backend/data/bot_analytics.pynew file mode 100644index 0000000000..45cc97f5e1--- /dev/null+++ b/autogpt_platform/backend/backend/data/bot_analytics.py@@ -0,0 +1,87 @@+"""Bot usage analytics writes (privacy-preserving).++Records discrete bot usage events and per-server presence for the admin+analytics page. NEVER stores message content — only counts, bounded enums,+timestamps and numeric metrics.++Directly accessed by the ``DatabaseManager`` pod (which holds the Prisma+connection). Other services (notably the out-of-process bot) reach these+through ``backend.data.db_accessors.bot_analytics_db`` so calls are+transparently routed via ``DatabaseManagerAsyncClient``.+"""++import logging+from datetime import datetime, timezone++from prisma.models import BotEvent, BotGuild++from backend.platform_linking.models import BotEventInput, BotGuildInput, Platform++logger = logging.getLogger(__name__)+++async def record_bot_event(event: BotEventInput) -> None:+ await BotEvent.prisma().create(+ data={+ "platform": event.platform.value,+ "eventType": event.event_type,+ "serverId": event.server_id,+ "channelType": event.channel_type,+ "commandName": event.command_name,+ "errorKind": event.error_kind,+ "charCount": event.char_count,+ "durationMs": event.duration_ms,+ }+ )+++async def record_guild_joined(guild: BotGuildInput) -> None:+ await BotGuild.prisma().upsert(+ where={+ "platform_serverId": {+ "platform": guild.platform.value,+ "serverId": guild.server_id,+ }+ },+ data={+ "create": {+ "platform": guild.platform.value,+ "serverId": guild.server_id,+ "name": guild.name,+ },+ "update": {+ "name": guild.name,+ "leftAt": None,+ "lastSeenAt": datetime.now(timezone.utc),+ },+ },+ )+++async def mark_guild_left(platform: Platform, server_id: str) -> None:+ await BotGuild.prisma().update_many(+ where={+ "platform": platform.value,+ "serverId": server_id,+ "leftAt": None,+ },+ data={"leftAt": datetime.now(timezone.utc)},+ )+++async def sync_guild_presence(platform: Platform, guilds: list[BotGuildInput]) -> None:+ """Full presence reconcile (on connect): upsert every server the bot is in+ now and mark any previously-joined server it is no longer in as left."""+ for guild in guilds:+ await record_guild_joined(guild)++ present = {guild.server_id for guild in guilds}+ joined = await BotGuild.prisma().find_many(+ where={"platform": platform.value, "leftAt": None}+ )+ stale_ids = [row.id for row in joined if row.serverId not in present]+ if stale_ids:+ await BotGuild.prisma().update_many(+ where={"id": {"in": stale_ids}},+ data={"leftAt": datetime.now(timezone.utc)},+ )diff --git a/autogpt_platform/backend/backend/data/bot_analytics_test.py b/autogpt_platform/backend/backend/data/bot_analytics_test.pynew file mode 100644index 0000000000..d6ff0b1e8b--- /dev/null+++ b/autogpt_platform/backend/backend/data/bot_analytics_test.py@@ -0,0 +1,100 @@+"""Tests for bot_analytics writer functions (prisma mocked)."""++from unittest.mock import AsyncMock, MagicMock, patch++import pytest++from backend.data import bot_analytics+from backend.platform_linking.models import BotEventInput, BotGuildInput, Platform+++async def test_record_bot_event_creates_row():+ prisma_mock = MagicMock()+ prisma_mock.create = AsyncMock()+ with patch.object(bot_analytics.BotEvent, "prisma", return_value=prisma_mock):+ await bot_analytics.record_bot_event(+ BotEventInput(+ platform=Platform.DISCORD,+ event_type="reply_sent",+ server_id="9",+ char_count=100,+ duration_ms=2500,+ )+ )++ data = prisma_mock.create.await_args.kwargs["data"]+ assert data["platform"] == "DISCORD"+ assert data["eventType"] == "reply_sent"+ assert data["serverId"] == "9"+ assert data["charCount"] == 100+ assert data["durationMs"] == 2500+++async def test_record_guild_joined_upserts():+ prisma_mock = MagicMock()+ prisma_mock.upsert = AsyncMock()+ with patch.object(bot_analytics.BotGuild, "prisma", return_value=prisma_mock):+ await bot_analytics.record_guild_joined(+ BotGuildInput(platform=Platform.DISCORD, server_id="5", name="Srv")+ )++ kwargs = prisma_mock.upsert.await_args.kwargs+ assert kwargs["where"]["platform_serverId"] == {+ "platform": "DISCORD",+ "serverId": "5",+ }+ assert kwargs["data"]["create"]["serverId"] == "5"+ assert kwargs["data"]["update"]["leftAt"] is None+++async def test_mark_guild_left_updates_active_rows():+ prisma_mock = MagicMock()+ prisma_mock.update_many = AsyncMock()+ with patch.object(bot_analytics.BotGuild, "prisma", return_value=prisma_mock):+ await bot_analytics.mark_guild_left(Platform.DISCORD, "5")++ where = prisma_mock.update_many.await_args.kwargs["where"]+ assert where == {"platform": "DISCORD", "serverId": "5", "leftAt": None}+++async def test_sync_guild_presence_marks_absent_as_left():+ prisma_mock = MagicMock()+ prisma_mock.upsert = AsyncMock()+ prisma_mock.update_many = AsyncMock()+ # Two rows currently joined; only "1" is still present.+ joined = [+ MagicMock(id="row1", serverId="1"),+ MagicMock(id="row2", serverId="2"),+ ]+ prisma_mock.find_many = AsyncMock(return_value=joined)++ with patch.object(bot_analytics.BotGuild, "prisma", return_value=prisma_mock):+ await bot_analytics.sync_guild_presence(+ Platform.DISCORD,+ [BotGuildInput(platform=Platform.DISCORD, server_id="1", name="A")],+ )++ prisma_mock.upsert.assert_awaited_once()+ prisma_mock.update_many.assert_awaited_once()+ where = prisma_mock.update_many.await_args.kwargs["where"]+ assert where == {"id": {"in": ["row2"]}}+++async def test_sync_guild_presence_noop_when_nothing_stale():+ prisma_mock = MagicMock()+ prisma_mock.upsert = AsyncMock()+ prisma_mock.update_many = AsyncMock()+ prisma_mock.find_many = AsyncMock(return_value=[MagicMock(id="row1", serverId="1")])++ with patch.object(bot_analytics.BotGuild, "prisma", return_value=prisma_mock):+ await bot_analytics.sync_guild_presence(+ Platform.DISCORD,+ [BotGuildInput(platform=Platform.DISCORD, server_id="1", name="A")],+ )++ prisma_mock.update_many.assert_not_awaited()diff --git a/autogpt_platform/backend/backend/data/db_accessors.py b/autogpt_platform/backend/backend/data/db_accessors.pyindex 2221866684..91a7d23a5e 100644--- a/autogpt_platform/backend/backend/data/db_accessors.py+++ b/autogpt_platform/backend/backend/data/db_accessors.py@@ -168,3 +168,16 @@ def platform_linking_db():platform_linking_db = get_database_manager_async_client()return platform_linking_db+++def bot_analytics_db():+ if db.is_connected():+ from backend.data import bot_analytics as _bot_analytics_db++ bot_analytics_db = _bot_analytics_db+ else:+ from backend.util.clients import get_database_manager_async_client++ bot_analytics_db = get_database_manager_async_client()++ return bot_analytics_dbdiff --git a/autogpt_platform/backend/backend/data/db_manager.py b/autogpt_platform/backend/backend/data/db_manager.pyindex a6e8bf58dd..bd950d666a 100644--- a/autogpt_platform/backend/backend/data/db_manager.py+++ b/autogpt_platform/backend/backend/data/db_manager.py@@ -35,6 +35,7 @@ from backend.api.features.store.db import (from backend.api.features.store.embeddings import backfill_missing_embeddingsfrom backend.copilot import db as chat_dbfrom backend.copilot.sharing.db import link_new_execution_to_chat_share+from backend.data import bot_analytics as bot_analytics_dbfrom backend.data import dbfrom backend.data.analytics import (get_accuracy_trends_and_alerts,@@ -395,6 +396,12 @@ class DatabaseManager(AppService):)fetch_workspace_artifact = _(platform_linking_db.fetch_workspace_artifact)+ # ============ Bot Analytics ============ #+ record_bot_event = _(bot_analytics_db.record_bot_event)+ record_guild_joined = _(bot_analytics_db.record_guild_joined)+ mark_guild_left = _(bot_analytics_db.mark_guild_left)+ sync_guild_presence = _(bot_analytics_db.sync_guild_presence)+# ============ CoPilot Chat Sessions ============ ## NOTE: no eager-load `get_chat_session` here — callers go through# `get_chat_messages_paginated` (with `limit=MAX_LOADED_CHAT_MESSAGES`) so@@ -642,6 +649,12 @@ class DatabaseManagerAsyncClient(AppServiceClient):cleanup_expired_platform_link_tokens = d.cleanup_expired_platform_link_tokensfetch_workspace_artifact = d.fetch_workspace_artifact+ # ============ Bot Analytics ============ #+ record_bot_event = d.record_bot_event+ record_guild_joined = d.record_guild_joined+ mark_guild_left = d.mark_guild_left+ sync_guild_presence = d.sync_guild_presence+# ============ CoPilot Chat Sessions ============ #get_chat_session_metadata = d.get_chat_session_metadataget_chat_messages_paginated = d.get_chat_messages_paginateddiff --git a/autogpt_platform/backend/backend/data/db_manager_test.py b/autogpt_platform/backend/backend/data/db_manager_test.pyindex fa290abb49..e622acc09a 100644--- a/autogpt_platform/backend/backend/data/db_manager_test.py+++ b/autogpt_platform/backend/backend/data/db_manager_test.py@@ -1,6 +1,17 @@-from .db_manager import DatabaseManagerAsyncClient+from .db_manager import DatabaseManager, DatabaseManagerAsyncClientdef test_async_client_exposes_chat_methods() -> None:assert hasattr(DatabaseManagerAsyncClient, "delete_chat_session")assert hasattr(DatabaseManagerAsyncClient, "set_turn_duration")+++def test_bot_analytics_methods_registered() -> None:+ for method in (+ "record_bot_event",+ "record_guild_joined",+ "mark_guild_left",+ "sync_guild_presence",+ ):+ assert hasattr(DatabaseManager, method)+ assert hasattr(DatabaseManagerAsyncClient, method)diff --git a/autogpt_platform/backend/backend/platform_linking/manager.py b/autogpt_platform/backend/backend/platform_linking/manager.pyindex 92936b3dae..650baf3e1a 100644--- a/autogpt_platform/backend/backend/platform_linking/manager.py+++ b/autogpt_platform/backend/backend/platform_linking/manager.py@@ -2,13 +2,15 @@import logging-from backend.data.db_accessors import platform_linking_db+from backend.data.db_accessors import bot_analytics_db, platform_linking_dbfrom backend.util.service import AppService, AppServiceClient, endpoint_to_async, exposefrom backend.util.settings import Settingsfrom .chat import list_user_chats, start_chat_turnfrom .models import (BotChatRequest,+ BotEventInput,+ BotGuildInput,ChatTurnHandle,CreateLinkTokenRequest,CreateUserLinkTokenRequest,@@ -90,6 +92,24 @@ class PlatformLinkingManager(AppService):session_id, file_id, max_bytes)+ @expose+ async def record_bot_event(self, event: BotEventInput) -> None:+ await bot_analytics_db().record_bot_event(event)++ @expose+ async def record_guild_joined(self, guild: BotGuildInput) -> None:+ await bot_analytics_db().record_guild_joined(guild)++ @expose+ async def mark_guild_left(self, platform: Platform, server_id: str) -> None:+ await bot_analytics_db().mark_guild_left(platform, server_id)++ @expose+ async def sync_guild_presence(+ self, platform: Platform, guilds: list[BotGuildInput]+ ) -> None:+ await bot_analytics_db().sync_guild_presence(platform, guilds)+class PlatformLinkingManagerClient(AppServiceClient):@classmethod@@ -115,3 +135,7 @@ class PlatformLinkingManagerClient(AppServiceClient):fetch_workspace_artifact = endpoint_to_async(PlatformLinkingManager.fetch_workspace_artifact)+ record_bot_event = endpoint_to_async(PlatformLinkingManager.record_bot_event)+ record_guild_joined = endpoint_to_async(PlatformLinkingManager.record_guild_joined)+ mark_guild_left = endpoint_to_async(PlatformLinkingManager.mark_guild_left)+ sync_guild_presence = endpoint_to_async(PlatformLinkingManager.sync_guild_presence)diff --git a/autogpt_platform/backend/backend/platform_linking/models.py b/autogpt_platform/backend/backend/platform_linking/models.pyindex 85f23a6144..030f62aa16 100644--- a/autogpt_platform/backend/backend/platform_linking/models.py+++ b/autogpt_platform/backend/backend/platform_linking/models.py@@ -224,3 +224,24 @@ class WorkspaceArtifact(BaseModel):mime_type: strsize_bytes: intcontent: bytes+++class BotEventInput(BaseModel):+ """A single bot usage event. Never carries message content."""++ platform: Platform+ event_type: str+ server_id: str | None = None+ channel_type: str | None = None+ command_name: str | None = None+ error_kind: str | None = None+ char_count: int | None = None+ duration_ms: int | None = None+++class BotGuildInput(BaseModel):+ """Presence of the bot in a single server."""++ platform: Platform+ server_id: str+ name: str | None = Nonediff --git a/autogpt_platform/backend/migrations/20260608120000_add_bot_analytics_tables/migration.sql b/autogpt_platform/backend/migrations/20260608120000_add_bot_analytics_tables/migration.sqlnew file mode 100644index 0000000000..259689d3d4--- /dev/null+++ b/autogpt_platform/backend/migrations/20260608120000_add_bot_analytics_tables/migration.sql@@ -0,0 +1,51 @@+-- CreateTable+-- BotEvent is an append-only stream of discrete bot usage events. It NEVER+-- stores message content — only counts, timestamps, bounded enums and numeric+-- metrics. Powers message-volume, command-usage, error-rate and per-server+-- activity charts on the admin analytics page.+CREATE TABLE "BotEvent" (+ "id" TEXT NOT NULL,+ "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,+ "platform" "PlatformType" NOT NULL,+ "eventType" TEXT NOT NULL,+ "serverId" TEXT,+ "channelType" TEXT,+ "commandName" TEXT,+ "errorKind" TEXT,+ "charCount" INTEGER,+ "durationMs" INTEGER,++ CONSTRAINT "BotEvent_pkey" PRIMARY KEY ("id")+);++-- CreateTable+-- BotGuild is the presence table: which servers the bot is physically in right+-- now (a superset of PlatformLink, since the bot can be in servers that never+-- ran /setup). leftAt IS NULL means currently joined; the joinedAt histogram+-- drives growth charts and sharding-threshold prediction.+CREATE TABLE "BotGuild" (+ "id" TEXT NOT NULL,+ "platform" "PlatformType" NOT NULL,+ "serverId" TEXT NOT NULL,+ "name" TEXT,+ "joinedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,+ "leftAt" TIMESTAMP(3),+ "lastSeenAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,++ CONSTRAINT "BotGuild_pkey" PRIMARY KEY ("id")+);++-- CreateIndex+CREATE INDEX "BotEvent_platform_eventType_createdAt_idx" ON "BotEvent"("platform", "eventType", "createdAt");++-- CreateIndex+CREATE INDEX "BotEvent_platform_serverId_createdAt_idx" ON "BotEvent"("platform", "serverId", "createdAt");++-- CreateIndex+CREATE INDEX "BotEvent_createdAt_idx" ON "BotEvent"("createdAt");++-- CreateIndex+CREATE UNIQUE INDEX "BotGuild_platform_serverId_key" ON "BotGuild"("platform", "serverId");++-- CreateIndex+CREATE INDEX "BotGuild_platform_leftAt_idx" ON "BotGuild"("platform", "leftAt");diff --git a/autogpt_platform/backend/schema.prisma b/autogpt_platform/backend/schema.prismaindex 8ce424a00f..84bebdb4a4 100644--- a/autogpt_platform/backend/schema.prisma+++ b/autogpt_platform/backend/schema.prisma@@ -1589,3 +1589,47 @@ model PlatformLinkToken {@@index([platform, platformUserId])@@index([expiresAt])}++// ── Bot usage analytics ────────────────────────────────────────────────+// Privacy: these tables NEVER store message content. Only counts,+// timestamps, bounded enums (event type, channel type, error kind) and+// numeric metrics (reply length, latency). Tagged with PlatformType so the+// same analytics work for every chat-bot platform.++// Append-only stream of discrete bot usage events. Powers message-volume,+// command-usage, error-rate and per-server activity charts.+model BotEvent {+ id String @id @default(uuid())+ createdAt DateTime @default(now())+ platform PlatformType+ // Bounded event kind, e.g. "message_received", "reply_sent",+ // "command_used", "link_created", "link_removed", "stream_error".+ eventType String+ serverId String? // Platform server/guild ID; null for DMs+ channelType String? // "dm" | "channel" | "thread"+ commandName String? // For command_used events (e.g. "/new", "/resume")+ errorKind String? // Bounded failure category for stream_error events+ charCount Int? // Reply length in characters — a metric, NOT content+ durationMs Int? // Receive→reply latency in milliseconds++ @@index([platform, eventType, createdAt])+ @@index([platform, serverId, createdAt])+ @@index([createdAt])+}++// Presence table: which servers the bot is physically in right now (a+// superset of PlatformLink, since the bot can be in servers that haven't run+// /setup). `leftAt IS NULL` is the live membership; the joinedAt histogram+// drives growth charts and sharding-threshold prediction.+model BotGuild {+ id String @id @default(uuid())+ platform PlatformType+ serverId String // Platform server/guild ID+ name String? // Server display name (best-effort, may go stale)+ joinedAt DateTime @default(now())+ leftAt DateTime? // Set when the bot is removed; null = currently joined+ lastSeenAt DateTime @default(now()) // Last reconcile that confirmed presence++ @@unique([platform, serverId])+ @@index([platform, leftAt])+}