# 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

- [PostHog Documentation](https://posthog.com/docs)
- [Client API Reference](https://posthog.com/docs/api/js)
- [Node.js API Reference](https://posthog.com/docs/api/nodejs) 