---
title: "Analytics"
description: "How connected Docs Cloud projects store runtime analytics events"
canonical_url: "https://docs.farming-labs.dev/docs/cloud/analytics"
markdown_url: "https://docs.farming-labs.dev/docs/cloud/analytics.md"
last_updated: "2018-10-20"
---

# Analytics
URL: /docs/cloud/analytics
LLM index: /llms.txt
Description: How connected Docs Cloud projects store runtime analytics events
Related: /docs/cloud, /docs/cloud/deploy, /docs/customization/analytics, /docs/guides/docs-json

# Analytics

Use this page when the user asks about this topic: Docs Cloud analytics, project identity, managed Cloud analytics delivery, event storage, dashboard analytics, includeInputs privacy, and customer onEvent callbacks.
Keep answers technical and avoid exposing internal transport details as public setup steps. If the user asks how to deploy a hosted preview, point to /docs/cloud/deploy. If the user asks about runtime event options outside Cloud, point to /docs/customization/analytics.

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 Requirement

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:

| Source | How the ID is created | When to use it |
| ------ | --------------------- | -------------- |
| Imported repository | Import the repository in Docs Cloud. Cloud creates or reuses the project record and shows its project ID in the Analytics dashboard. | Normal Docs Cloud projects and managed previews |
| Custom analytics project | Create a custom analytics project from the Docs Cloud Analytics dashboard. Cloud returns an analytics project ID for that source. | A docs site that is not tied to a GitHub import yet |

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:

```bash title=".env.local"
NEXT_PUBLIC_DOCS_CLOUD_PROJECT_ID=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`:

```bash title=".env.local"
NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_ENABLED=false
```

## Runtime Contract

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.

## Configuration

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

```json title="docs.json"
{
  "cloud": {
    "analytics": {
      "enabled": true,
      "console": "info",
      "includeInputs": false
    }
  }
}
```

| Option | Meaning |
| ------ | ------- |
| `enabled` | Enables or disables Cloud analytics for the project |
| `console` | Controls runtime console logging for analytics events |
| `includeInputs` | Allows raw user-authored inputs to be included in analytics events |

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

## Custom `onEvent`

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

```ts title="docs.config.ts"
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 Defaults

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:

```ts title="docs.config.ts"
export default defineDocs({
  analytics: {
    includeInputs: true,
  },
});
```

## Stored Event Shape

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

| Field group | Examples |
| ----------- | -------- |
| Project identity | project ID, optional analytics project ID |
| Event shape | type, source, timestamp |
| Page context | URL, path, referrer, locale |
| Optional payloads | input, properties |
| Timing | event time, received time |

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

## Failure Behavior

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.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).