AnalyticsCopy Anchor Link

Use analytics when you want to understand how people and agents use your docs. It emits product-level usage events: page views, search activity, Ask AI requests, feedback, page actions, machine-readable markdown reads, agent feedback routes, and MCP requests.

Analytics is intentionally separate from Observability. Analytics answers "what did users or agents do?" Observability answers "what happened inside this agent run?"

Quick StartCopy Anchor Link

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

analytics: true logs usage events to the console with the [@farming-labs/docs:analytics] prefix.

Send Events To Another ToolCopy Anchor Link

For connected Docs Cloud projects, this callback is optional and additive. Use it when you want a copy of events outside Docs Cloud; you do not need it for Cloud storage.

export default defineDocs({
  analytics: {
    async onEvent(event) {
      await fetch("https://analytics.example.com/events", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(event),
      });
    },
  },
});

The callback receives a normalized DocsAnalyticsEvent:

interface DocsAnalyticsEvent {
  type: string;
  timestamp: string;
  source: "client" | "server" | "mcp";
  url?: string;
  path?: string;
  referrer?: string;
  locale?: string;
  input?: {
    query?: string;
    question?: string;
    feedbackValue?: string;
    feedbackComment?: string;
    feedbackContext?: Record<string, unknown>;
    feedbackPayload?: Record<string, unknown>;
    agentFeedbackContext?: Record<string, unknown>;
    agentFeedbackPayload?: Record<string, unknown>;
    content?: string;
  };
  metadata?: Record<string, unknown>;
  properties?: Record<string, unknown>;
}

properties carries safe operational details such as status, durations, result counts, model ids, provider names, message counts, content lengths, and route or delivery metadata. Raw user-authored text stays in input and is excluded unless includeInputs: true is set.

Event TypesCopy Anchor Link

Analytics events describe product usage: what a person or agent did, which surface they used, and whether the action completed.

Client EventsCopy Anchor Link

Server And Agent-Surface EventsCopy Anchor Link

agent_read includes properties.delivery so you can see how the page was read: md_route, accept_header, signature_agent, user_agent, heuristic, api_format, or mcp_tool.

Ask AI API events include the provider, model, message count, question length, status or error reason, and durationMs when available. When ai.provider is "docs-cloud", those events identify the provider as docs-cloud even if the request is served through the local docs API proxy.

Input PrivacyCopy Anchor Link

By default, analytics events include safe metadata such as paths, counts, durations, status, result counts, model IDs, content lengths, and whether a comment exists.

Enable raw input capture only when you have user consent and a retention policy:

export default defineDocs({
  analytics: {
    includeInputs: true,
    onEvent(event) {
      console.info(event);
    },
  },
});

OptionsCopy Anchor Link

Configure both streams when you want usage analytics and runtime traces:

export default defineDocs({
  analytics: {
    onEvent: sendUsageEvent,
  },
  observability: {
    console: "debug",
    onEvent: sendTraceEvent,
  },
});