Analytics & Observability

Relevant source files

The following files were used as context for generating this wiki page:

• src/app/api/chat/route.ts
• src/app/layout.tsx
• src/lib/posthog-server.ts
• src/lib/posthog-capture-exception.ts
• instrumentation.ts
• src/components/providers/PostHogProvider.tsx
• next.config.ts

The Analytics & Observability system in ThinkEx is a multi-layered infrastructure designed to provide comprehensive insights into application performance, user behavior, and AI model interactions. By integrating specialized tools like PostHog for product analytics and OpenTelemetry for server-side tracing, the platform ensures high reliability and data-driven development.

The architecture covers client-side event tracking, server-side exception capturing, and specific observability for AI-generated content and chat interactions. This allows developers to monitor token usage, model performance, and system health across the entire stack.

System Architecture & Integration

The observability stack is initialized at the root level of the application, ensuring that all components and API routes are covered.

Global Configuration

The system utilizes the Next.js instrumentation.ts (if present) and custom providers within the root layout to boot observability services. PostHog configuration is integrated directly into the Next.js build process via the configuration file.

• PostHog Integration: Configured via withPostHogConfig in the Next.js configuration to manage personal API keys, project IDs, and source map uploads for production debugging.
• OpenTelemetry: Used for server-side tracing, particularly within API routes like the chat endpoint.

Sources: next.config.ts:39-55, src/app/layout.tsx:88-100

Trace & Event Flow

The following diagram illustrates how telemetry data flows from user interactions and server processes to the monitoring backends.

This diagram shows the dual-path instrumentation for both client-side behavior and server-side logic.
Sources: src/app/layout.tsx:90-95, src/app/api/chat/route.ts:503-505, src/lib/posthog-server.ts:1-10

AI & Chat Observability

Specific observability is applied to the AI chat interface to monitor model behavior and resource consumption.

AI Tracing

Chat interactions are wrapped with PostHog AI tracing to capture specific properties such as the workspace ID, active folder, and the specific model ID used (e.g., Gemini or Claude).

• Distinct ID Tracking: Events are linked to the userId or marked as anonymous.
• Token Usage Monitoring: The system logs final token usage, including input, output, and reasoning tokens, upon the completion of a stream.

Metric	Description	Source
inputTokens	Number of tokens sent to the model	src/app/api/chat/route.ts:405
outputTokens	Number of tokens generated by the model	src/app/api/chat/route.ts:406
reasoningTokens	Tokens used for internal model "thinking"	src/app/api/chat/route.ts:409
finishReason	Why the model stopped generating	src/app/api/chat/route.ts:411

Sources: src/app/api/chat/route.ts:289-301, src/app/api/chat/route.ts:403-415

Server-Side Route Monitoring

API routes are wrapped with withServerObservability to provide consistent logging and tracing across the backend. This higher-order function identifies the route name and monitors execution health.

Sources: src/app/api/chat/route.ts:503-505

Error Handling & Exception Capturing

The platform utilizes a dedicated utility for capturing exceptions on the server to ensure that crashes or logical failures are reported to PostHog.

PostHog Capture Utility

The captureException utility provides a standardized way to log errors. It extracts the PostHog server client and sends an $exception event with the error message and stack trace.

// src/lib/posthog-capture-exception.ts:10-21
export async function captureException(error: unknown, properties?: Record<string, any>) {
  const posthog = getPostHogServerClient();
  if (!posthog) return;

  const errorMessage = error instanceof Error ? error.message : String(error);
  const errorStack = error instanceof Error ? error.stack : undefined;

  posthog.capture({
    distinctId: properties?.distinctId || 'server-side-error',
    event: '$exception',
    properties: {
      ...properties,
      message: errorMessage,
      stack: errorStack,
    },
  });
}

Sources: src/lib/posthog-capture-exception.ts:10-26

Environment Configuration

Observability features are toggled and configured via environment variables and specific build-time flags.

Variable	Type	Purpose
POSTHOG_PERSONAL_API_KEY	Secret	Used for uploading source maps to PostHog
POSTHOG_PROJECT_ID	String	Identifies the project in PostHog Cloud
POSTHOG_RELEASE_NAME	String	Tags events with a specific release (default: "thinkex")
NEXT_PUBLIC_APP_URL	URL	Used in referer headers for AI Gateway tracing

Sources: next.config.ts:40-52, src/app/api/chat/route.ts:394

Summary

The Analytics & Observability system provides a comprehensive view of ThinkEx operations by combining user-centric analytics with deep technical tracing. By instrumenting the AI Gateway and capturing detailed token usage alongside standard server exceptions, the project maintains high visibility into both its operational costs and user experience. This unified approach facilitates proactive debugging and performance optimization across the entire knowledge workspace platform.