AgentDock Core Documentation

Analytics Integration using PostHog

This document outlines how analytics, specifically using PostHog, is integrated into the AgentDock Starter Kit. The primary goal is to gather usage data when deployed (e.g., on AgentDock Hub) to understand application performance and user interaction patterns, while ensuring compatibility with core features like Vercel AI SDK tool calling.

Implementation Overview

The integration uses both client-side and server-side PostHog libraries:

  1. Client-Side (posthog-js): Handles automatic event capture (autocapture) for general UI interactions and manual pageview tracking. Setup via src/components/providers/posthog-provider.tsx.
  2. Server-Side (posthog-node): Handles specific, critical events triggered by backend processes, such as successful chat completions. Setup via src/lib/analytics.ts.

This dual approach allows capturing broad UI interactions without interfering with sensitive backend operations, while still capturing key server-side events.

Client-Side Integration

  • Provider Component: The src/components/providers/posthog-provider.tsx component initializes posthog-js and wraps the main application layout (src/components/layout/layout-content.tsx).
  • Configuration for Compatibility: The posthog-js client is initialized with specific options carefully chosen to prevent interference with the Vercel AI SDK's tool calling mechanisms:
    • capture_pageview: false: Default pageview tracking is disabled. Pageviews are tracked manually after a delay (useEffect in posthog-provider.tsx) to avoid race conditions during initial load.
    • autocapture: true: Standard UI interactions (clicks, form submissions, etc.) are captured automatically.
    • capture_pageleave: false: Disabled.
    • disable_session_recording: true: Session recording is disabled to minimize performance impact and potential conflicts.
  • Context & Hook: The provider exposes a usePostHog hook and a capture function for triggering custom client-side events if needed.

Server-Side Integration

  • Utility Module: The src/lib/analytics.ts file initializes a singleton instance of the posthog-node client.
  • Non-Blocking Capture: It provides a captureEvent function that captures events asynchronously (Promise.resolve().then(...)) to ensure analytics calls never block the main execution thread (e.g., API responses).
  • Functions: Exports captureEvent, identifyUser, and flushAnalytics for server-side use.

Tracked Events

Currently, the following key events are confirmed to be tracked:

  1. $pageview (Client-Side): Manually captured by src/components/providers/posthog-provider.tsx after a 1-second delay upon route changes to avoid conflicts during initial load.
  2. Autocaptured Events (Client-Side): Standard UI interactions captured automatically by posthog-js (e.g., button clicks, form submissions), as configured in src/components/providers/posthog-provider.tsx.
  3. Chat Completion Success (Server-Side): Captured in src/app/api/chat/[agentId]/route.ts after a successful response is generated by the agent. Includes the following confirmed properties:
    • agentId: The ID of the agent used.
    • sessionId: A masked version of the user's session ID.
    • durationMs: Time taken for the API request/response cycle.
    • provider: The LLM provider used (e.g., 'openai', 'groq').
    • model: The specific LLM model used.
    • environment: Node environment (e.g., 'development', 'production').
    • timestamp: Event timestamp.
    • (Note: Token usage properties are not currently captured in this event.)

Configuration

Analytics integration is controlled by environment variables:

  • NEXT_PUBLIC_POSTHOG_API_KEY: Your PostHog Project API Key. Required to enable tracking.
  • NEXT_PUBLIC_POSTHOG_HOST: The PostHog instance host (e.g., https://us.i.posthog.com or your self-hosted URL). Defaults to PostHog Cloud US.
  • NEXT_PUBLIC_ANALYTICS_ENABLED: Set to true to enable analytics. Defaults to true only if NODE_ENV is production.

Future Considerations & Customization

Users deploying this starter kit might want to:

  • Add More Custom Events: Track specific tool usage (client or server-side), settings changes, agent creation/selection, or errors.
  • Enable Session Recording: If compatibility is confirmed or tool usage is minimal, session recording could be enabled for deeper UX insights (carefully monitor performance).
  • User Identification: Implement identifyUser calls (e.g., upon login if authentication is added) to associate events with specific users rather than just anonymous sessions.
  • Feature Flags: Leverage PostHog's feature flags for A/B testing or rolling out features.

No other standard server-side events (like api_chat_request, api_chat_error, api_tool_execution_started) are currently tracked by default.

Debugging

When running in development mode (NODE_ENV=development):

  1. Client-side PostHog instance is available at window.posthog for debugging
  2. Server-side events are logged to the server console

Best Practices

  1. Personal Information: Avoid tracking personally identifiable information (PII) in events
  2. Error Information: Include error types and general messages, but not stack traces or sensitive error details
  3. User IDs: Use anonymous IDs where possible, especially for public-facing applications
  4. Property Naming: Use snake_case for event names and property keys

Additional Resources