AnalyticsCopy Anchor Link

Docs Cloud analytics stores usage events for a Docs Cloud project. The docs runtime emits the events; a Docs Cloud project ID tells Cloud which project should own those events; the dashboard reads the stored event stream.

Teams do not need to configure internal Cloud transport or add an onEvent callback for Cloud storage. onEvent is only for sending an additional copy of the same events to a system the team owns.

Project ID RequirementCopy Anchor Link

Cloud analytics requires a Docs Cloud project ID. Without one, Cloud cannot attach events to a workspace or dashboard.

There are two ways to get the ID:

Managed Docs Cloud deploys provide the project ID to the runtime for you. For a manually hosted or custom analytics source, copy the project ID from the Docs Cloud Analytics dashboard and set it in the runtime environment:

PUBLIC_DOCS_CLOUD_PROJECT_ID=docs_cloud_project_id
# Use DOCS_CLOUD_PROJECT_ID instead when only the server runtime needs the id.
# Next.js projects can use NEXT_PUBLIC_DOCS_CLOUD_PROJECT_ID.

Keep using the dashboard-provided ID. Do not invent one locally; the ID must match an imported repository project or a custom analytics project in Docs Cloud.

The project ID is enough to turn on the built-in Cloud delivery path. To opt out from a manual runtime environment, set the analytics flag to false:

NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_ENABLED=false

Only set NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_ENDPOINT when the docs app should send events to a custom or self-hosted Docs Cloud API. The hosted Docs Cloud endpoint is the default.

If your Cloud workspace issues a dedicated analytics key, set NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_KEY for browser delivery or DOCS_CLOUD_ANALYTICS_KEY for server-only delivery. The project ID is still required; the key only authenticates the event write.

Runtime ContractCopy Anchor Link

The runtime analytics stream is produced by @farming-labs/docs. Events cover product usage such as page views, search, Ask AI, feedback, page actions, markdown reads, agent reads, and MCP usage.

For a connected Cloud project:

1. Docs Cloud creates or provides the project ID
2. the runtime receives that project ID
3. the runtime enables the built-in Cloud delivery path
4. Docs Cloud validates the project ID and analytics state
5. Docs Cloud stores accepted events
6. the dashboard reads stored events for counts, filters, and recent activity

The public contract is the Docs Cloud project ID, the runtime analytics configuration, and the cloud.analytics setting. The internal transport is managed by Docs Cloud.

ConfigurationCopy Anchor Link

For frameworkless projects, cloud.analytics can be stored in docs.json because it only contains JSON-safe options:

{
  "cloud": {
    "analytics": {
      "enabled": true,
      "console": "info",
      "includeInputs": false
    }
  }
}

Function callbacks do not belong in docs.json. If a project needs executable analytics logic, keep that logic in docs.config.ts.

Custom onEventCopy Anchor Link

Use analytics.onEvent when the project needs a second destination for analytics events:

import { defineDocs } from "@farming-labs/docs";

export default defineDocs({
  analytics: {
    async onEvent(event) {
      await sendToCompanyAnalytics(event);
    },
  },
});

For connected Cloud projects, this callback is additive. Docs Cloud still stores its copy of the event through the managed Cloud path.

Privacy DefaultsCopy Anchor Link

By default, raw user-authored text is excluded from analytics events. That includes search queries, Ask AI questions, feedback comments, and copied content.

Set includeInputs: true only when the project has the right consent, retention, and review policy for user-authored text:

export default defineDocs({
  analytics: {
    includeInputs: true,
  },
});

Stored Event ShapeCopy Anchor Link

Docs Cloud stores event fields that are useful for dashboard queries:

The dashboard can use those fields for totals, recent event lists, source filters, event type filters, repository filters, and activity charts.

Agent-readable routes and MCP events are marked as agent traffic when the runtime can infer that from the event source, event type, explicit properties, or known AI crawler user agents. That lets the dashboard separate human docs usage from ChatGPT, Codex, Copilot, Claude, MCP clients, and crawler activity without requiring a custom onEvent callback.

Failure BehaviorCopy Anchor Link

Analytics delivery should not break the docs runtime. If Cloud analytics delivery fails, rendering, search, Ask AI, MCP, and a customer-owned onEvent callback should continue independently.

That behavior keeps analytics operationally useful without making analytics availability part of the critical path for serving docs.