feat(web): add MCP and API key usage tracking to analytics (#950)

* feat(web): add MCP and API key usage tracking to analytics

Move audit event creation from client-side to service functions for search, repos, file source, and file tree endpoints. Add source metadata to distinguish MCP requests from other API calls. Extend analytics SQL to include new actions and display MCP request and API request counts on the analytics dashboard.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

* chore: update CHANGELOG for MCP analytics tracking (#948)

* feat: add audit log retention policy, update analytics UI and docs

- Add SOURCEBOT_EE_AUDIT_RETENTION_DAYS env var (default 180) and AuditLogPruner background job that prunes old audit records daily in batches
- Surface retention period and oldest record date in analytics page header
- Update audit action types table in docs (remove 4 stale, add 11 missing)
- Add audit log storage section to sizing guide with enterprise callout and storage estimates
- Update mock data script with mixed-usage user profiles and new audit actions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: update CHANGELOG for audit log retention policy (#950)

* feat(web): add sourceOverride to getFileSource and getTree

Extend the sourceOverride pattern to getFileSource and getTree so
internal callers (chat AI agent) can tag audit events with the correct
source instead of relying on the HTTP header.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(web): restructure analytics by source and add global active users

- Tag all audit events with source metadata (sourcebot-web-client,
  sourcebot-ask-agent, sourcebot-ui-codenav, mcp) via sourceOverride
- Restructure analytics SQL to segment by Web App (sourcebot-*),
  MCP, and API (everything else)
- Add global active users chart at top of analytics page
- Add info hover tooltips explaining each chart
- Prefix chart names with their section (Web/MCP/API) for clarity
- Update inject-audit-data script to use correct source values

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(db): backfill audit source metadata and add v2 inject script

Add a migration that backfills the 'source' field in audit metadata for
historical events created before source tracking was introduced. All
old events were web-only, so code searches and chats get
'sourcebot-web-client' and navigations get 'sourcebot-ui-codenav'.

Also restore the original inject-audit-data script and add
inject-audit-data-v2 with source-aware mock data generation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(web): add source-segmented analytics with MCP/API tracking

Restructure analytics dashboard to segment metrics by source (web, MCP,
API). Add audit events for file source, file tree, and repo listing
actions. Pass source metadata through all audit event paths including
MCP server, chat blocking API, and code navigation. Backfill historical
audit events with sourcebot-web-client source.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* shift migrations

* new docs and news data

* update readme to point to new demo site

* fix(web): Log audit failures instead of silently swallowing errors

Replace empty .catch(() => {}) on getAuditService().createAudit() in
askCodebase with a handler that logs the error and audit context
(action, actorId, orgId, source) for debugging and alerting.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(web): Use UTC timezone for "Data since" date display

Adds timeZone: "UTC" to toLocaleDateString() call so the oldest record
date doesn't shift by a day depending on the client's local timezone.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: use type-only imports and update import source in inject-audit-data-v2

Convert Script, PrismaClient, and Prisma imports to type-only imports since
they are only used in type positions. Update PrismaClient/Prisma import source
from "../../dist" to "@sourcebot/db" to match the pattern in scriptRunner.ts.
Also fix broken API reference link in sizing guide docs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(web): Remove redundant .catch() on createAudit calls

createAudit already catches errors internally and logs them with
context, so the .catch(() => {}) at each call site was redundant.
Removed from all 6 call sites: askCodebase, getFileSourceApi,
getTreeApi, searchApi (x2), and listReposApi.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor(web): Rename sourceOverride param to source

The "override" suffix is redundant — callers are simply providing the
source value. Renamed across all 9 files (function signatures, types,
and call sites). No behavioral changes.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* changelog typo

* fix news data

* fix(web): Resolve variable shadowing in getFileSourceApi

Rename local `source` variable (git file content) to `fileContent` to
avoid shadowing the `source` parameter, which caused a TypeScript
"Block-scoped variable used before declaration" error.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

Author: msukkari

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Added support a MCP streamable http transport hosted at `/api/mcp`. [#976](https://github.com/sourcebot-dev/sourcebot/pull/976)
 - [EE] Added support for Oauth 2.1 to the remote MCP server hosted at `/api/mcp`. [#977](https://github.com/sourcebot-dev/sourcebot/pull/977)
+- Added MCP and API key usage tracking to analytics dashboard and added audit retention system [#950](https://github.com/sourcebot-dev/sourcebot/pull/950)
 
 ## [4.13.2] - 2026-03-02
 

README.md

@@ -11,7 +11,7 @@
          <a href="https://docs.sourcebot.dev/self-hosting/overview">
             <strong>Self Host</strong>
          </a> · 
-         <a href="https://demo.sourcebot.dev">
+         <a href="https://app.sourcebot.dev">
             <strong>Public Demo</strong>
          </a>
       </h3>
@@ -41,7 +41,7 @@ Sourcebot is a self-hosted tool that helps you understand your codebase.
 - **Ask Sourcebot:** Ask questions about your codebase and have Sourcebot provide detailed answers grounded with inline citations.
 - **Code search:** Search and navigate across all your repos and branches, no matter where they’re hosted.
 
-Try it out in our [public demo](https://demo.sourcebot.dev)!
+Try it out in our [public demo](https://app.sourcebot.dev)!
 
 https://github.com/user-attachments/assets/ed66a622-e38f-4947-a531-86df1e1e0218
 
@@ -108,7 +108,7 @@ docker compose up
 To configure Sourcebot (index your own repos, connect your LLMs, etc), check out our [docs](https://docs.sourcebot.dev/docs/configuration/config-file).
 
 > [!NOTE]
-> Sourcebot collects <a href="https://demo.sourcebot.dev/~/search?query=captureEvent%5C(%20repo%3Asourcebot">anonymous usage data</a> by default to help us improve the product. No sensitive data is collected, but if you'd like to disable this you can do so by setting the `SOURCEBOT_TELEMETRY_DISABLED` environment
+> Sourcebot collects <a href="https://app.sourcebot.dev/~/search?query=captureEvent%5C(%20repo%3Asourcebot">anonymous usage data</a> by default to help us improve the product. No sensitive data is collected, but if you'd like to disable this you can do so by setting the `SOURCEBOT_TELEMETRY_DISABLED` environment
 > variable to `true`. Please refer to our [telemetry docs](https://docs.sourcebot.dev/docs/overview#telemetry) for more information.
 
 # Build from source

docs/docs/configuration/audit-logs.mdx

@@ -15,6 +15,9 @@ This feature gives security and compliance teams the necessary information to en
 ## Enabling/Disabling Audit Logs
 Audit logs are enabled by default and can be controlled with the `SOURCEBOT_EE_AUDIT_LOGGING_ENABLED` [environment variable](/docs/configuration/environment-variables).
 
+## Retention Policy
+By default, audit logs older than 180 days are automatically pruned daily. You can configure the retention period using the `SOURCEBOT_EE_AUDIT_RETENTION_DAYS` [environment variable](/docs/configuration/environment-variables). Set it to `0` to disable automatic pruning and retain logs indefinitely.
+
 ## Fetching Audit Logs
 Audit logs are stored in the [postgres database](/docs/overview#architecture) connected to Sourcebot. To fetch all of the audit logs, you can use the following API:
 
@@ -110,30 +113,37 @@ curl --request GET '$SOURCEBOT_URL/api/ee/audit' \
 
 | Action  | Actor Type | Target Type |
 | :------- | :------ | :------|
-| `api_key.creation_failed`             | `user` | `org` |
 | `api_key.created`                     | `user` | `api_key` |
-| `api_key.deletion_failed`             | `user` | `org` |
+| `api_key.creation_failed`             | `user` | `org` |
 | `api_key.deleted`                     | `user` | `api_key` |
+| `api_key.deletion_failed`             | `user` | `org` |
+| `audit.fetch`                         | `user` | `org` |
+| `chat.deleted`                        | `user` | `chat` |
+| `chat.shared_with_users`              | `user` | `chat` |
+| `chat.unshared_with_user`             | `user` | `chat` |
+| `chat.visibility_updated`             | `user` | `chat` |
+| `org.ownership_transfer_failed`       | `user` | `org` |
+| `org.ownership_transferred`           | `user` | `org` |
+| `user.created_ask_chat`               | `user` | `org` |
 | `user.creation_failed`                | `user` | `user` |
-| `user.owner_created`                  | `user` | `org` |
-| `user.performed_code_search`              | `user` | `org` |
-| `user.performed_find_references` | `user` | `org` |
-| `user.performed_goto_definition` | `user` | `org` |
-| `user.created_ask_chat`          | `user` | `org` |
-| `user.jit_provisioning_failed`        | `user` | `org` |
-| `user.jit_provisioned`                | `user` | `org` |
-| `user.join_request_creation_failed`   | `user` | `org` |
-| `user.join_requested`                 | `user` | `org` |
-| `user.join_request_approve_failed`    | `user` | `account_join_request` |
-| `user.join_request_approved`          | `user` | `account_join_request` |
-| `user.invite_failed`                  | `user` | `org` |
-| `user.invites_created`                | `user` | `org` |
+| `user.delete`                         | `user` | `user` |
+| `user.fetched_file_source`            | `user` | `org` |
+| `user.fetched_file_tree`              | `user` | `org` |
 | `user.invite_accept_failed`           | `user` | `invite` |
 | `user.invite_accepted`                | `user` | `invite` |
+| `user.invite_failed`                  | `user` | `org` |
+| `user.invites_created`                | `user` | `org` |
+| `user.join_request_approve_failed`    | `user` | `account_join_request` |
+| `user.join_request_approved`          | `user` | `account_join_request` |
+| `user.list`                           | `user` | `org` |
+| `user.listed_repos`                   | `user` | `org` |
+| `user.owner_created`                  | `user` | `org` |
+| `user.performed_code_search`          | `user` | `org` |
+| `user.performed_find_references`      | `user` | `org` |
+| `user.performed_goto_definition`      | `user` | `org` |
+| `user.read`                           | `user` | `user` |
 | `user.signed_in`                      | `user` | `user` |
 | `user.signed_out`                     | `user` | `user` |
-| `org.ownership_transfer_failed`       | `user` | `org` |
-| `org.ownership_transferred`           | `user` | `org` |
 
 
 ## Response schema
@@ -180,7 +190,7 @@ curl --request GET '$SOURCEBOT_URL/api/ee/audit' \
       },
       "targetType": {
         "type": "string",
-        "enum": ["user", "org", "file", "api_key", "account_join_request", "invite"]
+        "enum": ["user", "org", "file", "api_key", "account_join_request", "invite", "chat"]
       },
       "sourcebotVersion": {
         "type": "string"
@@ -192,7 +202,8 @@ curl --request GET '$SOURCEBOT_URL/api/ee/audit' \
             "properties": {
               "message": { "type": "string" },
               "api_key": { "type": "string" },
-              "emails": { "type": "string" }
+              "emails": { "type": "string" },
+              "source": { "type": "string" }
             },
             "additionalProperties": false
           },

docs/docs/configuration/environment-variables.mdx

@@ -42,6 +42,7 @@ The following environment variables allow you to configure your Sourcebot deploy
 | `HTTPS_PROXY` | - | <p>HTTPS proxy URL for routing SSL requests through a proxy server (e.g., `http://proxy.company.com:8080`). Requires `NODE_USE_ENV_PROXY=1`.</p> |
 | `NO_PROXY` | - | <p>Comma-separated list of hostnames or domains that should bypass the proxy (e.g., `localhost,127.0.0.1,.internal.domain`). Requires `NODE_USE_ENV_PROXY=1`.</p> |
 | `SOURCEBOT_EE_AUDIT_LOGGING_ENABLED` | `true` | <p>Enables/disables audit logging</p> |
+| `SOURCEBOT_EE_AUDIT_RETENTION_DAYS` | `180` | <p>The number of days to retain audit logs. Audit log records older than this will be automatically pruned daily. Set to `0` to disable pruning and retain logs indefinitely.</p> |
 | `AUTH_EE_GCP_IAP_ENABLED` | `false` | <p>When enabled, allows Sourcebot to automatically register/login from a successful GCP IAP redirect</p> |
 | `AUTH_EE_GCP_IAP_AUDIENCE` | - | <p>The GCP IAP audience to use when verifying JWT tokens. Must be set to enable GCP IAP JIT provisioning</p> | 
 | `EXPERIMENT_EE_PERMISSION_SYNC_ENABLED` | `false` | <p>Enables [permission syncing](/docs/features/permission-syncing).</p> |

docs/docs/deployment/sizing-guide.mdx

@@ -45,6 +45,34 @@ If your instance is resource-constrained, you can reduce the concurrency of back
 
 Lowering these values reduces peak resource usage at the cost of slower initial indexing.
 
+## Audit log storage
+
+<Info>
+Audit logging is an enterprise feature and is only available with an [enterprise license](/docs/overview#license-key). If you are not on an enterprise plan, audit logs are not stored and this section does not apply.
+</Info>
+
+[Audit logs](/docs/configuration/audit-logs) are stored in the Postgres database connected to your Sourcebot deployment. Each audit record captures the action performed, the actor, the target, a timestamp, and optional metadata (e.g., request source). There are three database indexes on the audit table to support analytics and lookup queries.
+
+**Estimated storage per audit event: ~350 bytes** (including row data and indexes).
+
+<Info>
+The table below assumes 50 events per user per day. The actual number depends on usage patterns — each user action (code search, file view, navigation, Ask chat, etc.) creates one audit event. Users who interact via [MCP](/docs/features/mcp-server) or the API tend to generate significantly more events than web-only users, so your real usage may vary.
+</Info>
+
+| Team size | Avg events / user / day | Daily events | Monthly storage | 6-month storage |
+|---|---|---|---|---|
+| 10 users | 50 | 500 | ~5 MB | ~30 MB |
+| 50 users | 50 | 2,500 | ~25 MB | ~150 MB |
+| 100 users | 50 | 5,000 | ~50 MB | ~300 MB |
+| 500 users | 50 | 25,000 | ~250 MB | ~1.5 GB |
+| 1,000 users | 50 | 50,000 | ~500 MB | ~3 GB |
+
+### Retention policy
+
+By default, audit logs older than **180 days** are automatically pruned daily by a background job. You can adjust this with the `SOURCEBOT_EE_AUDIT_RETENTION_DAYS` [environment variable](/docs/configuration/environment-variables). Set it to `0` to disable pruning and retain logs indefinitely.
+
+For most deployments, the default 180-day retention keeps database size manageable. If you have a large team with heavy MCP/API usage and need longer retention, plan your Postgres disk allocation accordingly using the estimates above.
+
 ## Monitoring
 
 We recommend monitoring the following metrics after deployment to validate your sizing:

docs/docs/features/analytics.mdx

@@ -14,7 +14,7 @@ import { Callout } from 'nextra/components'
 Analytics provides comprehensive insights into your organization's usage of Sourcebot, helping you understand adoption patterns and
 quantify the value of time saved.
 
-This dashboard is backed by [audit log](/docs/configuration/audit-logs) events. Please ensure you have audit logging enabled in order to see these insights.
+This dashboard is backed by [audit log](/docs/configuration/audit-logs) events. Please ensure you have audit logging enabled in order to see these insights. Analytics data is subject to the audit log [retention policy](/docs/configuration/audit-logs#retention-policy). By default, data older than 180 days is automatically pruned.
 
 <video
   autoPlay
@@ -25,18 +25,40 @@ This dashboard is backed by [audit log](/docs/configuration/audit-logs) events.
   src="/images/analytics_demo.mp4"
 ></video>
 
-## Data Metrics
+The analytics dashboard segments usage by source so you can understand how your team interacts with Sourcebot across different interfaces. Each chart supports daily, weekly, and monthly time periods.
+
+## Global
 
 ### Active Users
-Tracks the number of unique users who performed any Sourcebot operation within each time period. This metric helps you understand team adoption
-and engagement with Sourcebot.
+Tracks the number of unique users who performed any tracked action across all sources (web app, MCP, and API). This includes code searches, navigations, Ask chats, file views, and tree browsing. Web repo listings are excluded to reduce noise from passive page loads.
+
+## Web App
+
+Metrics from the Sourcebot web interface.
+
+### Web Active Users
+Shows unique users who interacted with the web interface, broken down by activity type:
+- **All**: Users who performed any web action (code searches, navigations, Ask chats, or file views), excluding repo listings.
+- **Search**: The subset of users who performed code searches.
+- **Ask**: The subset of users who created Ask chat sessions.
+
+### Web Activity
+Total event counts for web interface activity:
+- **Code Searches**: Searches performed in the web search bar.
+- **Ask Chats**: Conversations created through the web interface.
+- **Navigations**: "Go to Definition" and "Find All References" actions in the code viewer.
+
+## API
 
-### Code Searches
-Counts the number of code search operations performed by your team.
+Metrics from MCP integrations and direct API access.
 
-### Code Navigation
-Tracks "Go to Definition" and "Find All References" navigation actions. Navigation actions help developers quickly move
-between code locations and understand code relationships.
+### API Active Users
+Shows unique users who interacted via non-web sources:
+- **Any**: Users who used either MCP or the API.
+- **MCP**: Users from IDE extensions and other MCP clients.
+- **API**: Users from direct HTTP API access (e.g., via API keys), excluding web app and MCP traffic.
 
-### Ask Chats
-Tracks the number of new Ask chat sessions created by your team.
+### API Requests
+Total request counts:
+- **MCP**: Code searches, file reads, tree listings, repo listings, and Ask chats from MCP clients.
+- **API**: Direct HTTP API requests, excluding web app and MCP traffic.

docs/images/analytics_demo.mp4

@@ -0,0 +1,71 @@
+import { PrismaClient } from "@sourcebot/db";
+import { createLogger, env } from "@sourcebot/shared";
+import { setIntervalAsync } from "../utils.js";
+
+const BATCH_SIZE = 10_000;
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+
+const logger = createLogger('audit-log-pruner');
+
+export class AuditLogPruner {
+    private interval?: NodeJS.Timeout;
+
+    constructor(private db: PrismaClient) {}
+
+    startScheduler() {
+        if (env.SOURCEBOT_EE_AUDIT_LOGGING_ENABLED !== 'true') {
+            logger.info('Audit logging is disabled, skipping audit log pruner.');
+            return;
+        }
+
+        if (env.SOURCEBOT_EE_AUDIT_RETENTION_DAYS <= 0) {
+            logger.info('SOURCEBOT_EE_AUDIT_RETENTION_DAYS is 0, audit log pruning is disabled.');
+            return;
+        }
+
+        logger.info(`Audit log pruner started. Retaining logs for ${env.SOURCEBOT_EE_AUDIT_RETENTION_DAYS} days.`);
+
+        // Run immediately on startup, then every 24 hours
+        this.pruneOldAuditLogs();
+        this.interval = setIntervalAsync(() => this.pruneOldAuditLogs(), ONE_DAY_MS);
+    }
+
+    async dispose() {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = undefined;
+        }
+    }
+
+    private async pruneOldAuditLogs() {
+        const cutoff = new Date(Date.now() - env.SOURCEBOT_EE_AUDIT_RETENTION_DAYS * ONE_DAY_MS);
+        let totalDeleted = 0;
+
+        logger.info(`Pruning audit logs older than ${cutoff.toISOString()}...`);
+
+        // Delete in batches to avoid long-running transactions
+        while (true) {
+            const batch = await this.db.audit.findMany({
+                where: { timestamp: { lt: cutoff } },
+                select: { id: true },
+                take: BATCH_SIZE,
+            });
+
+            if (batch.length === 0) break;
+
+            const result = await this.db.audit.deleteMany({
+                where: { id: { in: batch.map(r => r.id) } },
+            });
+
+            totalDeleted += result.count;
+
+            if (batch.length < BATCH_SIZE) break;
+        }
+
+        if (totalDeleted > 0) {
+            logger.info(`Pruned ${totalDeleted} audit log records.`);
+        } else {
+            logger.info('No audit log records to prune.');
+        }
+    }
+}

packages/backend/src/ee/auditLogPruner.ts

@@ -12,6 +12,7 @@ import { ConfigManager } from "./configManager.js";
 import { ConnectionManager } from './connectionManager.js';
 import { INDEX_CACHE_DIR, REPOS_CACHE_DIR, SHUTDOWN_SIGNALS } from './constants.js';
 import { AccountPermissionSyncer } from "./ee/accountPermissionSyncer.js";
+import { AuditLogPruner } from "./ee/auditLogPruner.js";
 import { GithubAppManager } from "./ee/githubAppManager.js";
 import { RepoPermissionSyncer } from './ee/repoPermissionSyncer.js';
 import { shutdownPosthog } from "./posthog.js";
@@ -64,9 +65,11 @@ const repoPermissionSyncer = new RepoPermissionSyncer(prisma, settings, redis);
 const accountPermissionSyncer = new AccountPermissionSyncer(prisma, settings, redis);
 const repoIndexManager = new RepoIndexManager(prisma, settings, redis, promClient);
 const configManager = new ConfigManager(prisma, connectionManager, env.CONFIG_PATH);
+const auditLogPruner = new AuditLogPruner(prisma);
 
 connectionManager.startScheduler();
 await repoIndexManager.startScheduler();
+auditLogPruner.startScheduler();
 
 if (env.EXPERIMENT_EE_PERMISSION_SYNC_ENABLED === 'true' && !hasEntitlement('permission-syncing')) {
     logger.error('Permission syncing is not supported in current plan. Please contact team@sourcebot.dev for assistance.');
@@ -105,6 +108,7 @@ const listenToShutdownSignals = () => {
             await connectionManager.dispose()
             await repoPermissionSyncer.dispose()
             await accountPermissionSyncer.dispose()
+            await auditLogPruner.dispose()
             await configManager.dispose()
 
             await prisma.$disconnect();

packages/backend/src/index.ts

@@ -0,0 +1,19 @@
+-- Backfill source metadata for historical audit events.
+--
+-- Before this change, all audit events were created from the web UI without
+-- a 'source' field in metadata. The new analytics dashboard segments events
+-- by source (sourcebot-*, mcp, or null/other for API). Without this backfill,
+-- historical web UI events would be misclassified as API traffic.
+
+-- Code searches and chat creation were web-only (no server-side audit existed)
+UPDATE "Audit"
+SET metadata = jsonb_set(COALESCE(metadata, '{}')::jsonb, '{source}', '"sourcebot-web-client"')
+WHERE action IN ('user.performed_code_search', 'user.created_ask_chat')
+  AND (metadata IS NULL OR metadata->>'source' IS NULL);
+
+-- Navigation events (find references, goto definition) were web-only
+-- (created from the symbolHoverPopup client component)
+UPDATE "Audit"
+SET metadata = jsonb_set(COALESCE(metadata, '{}')::jsonb, '{source}', '"sourcebot-web-client"')
+WHERE action IN ('user.performed_find_references', 'user.performed_goto_definition')
+  AND (metadata IS NULL OR metadata->>'source' IS NULL);