feat: posthog integration

.env.example

@@ -53,6 +53,11 @@ APP_FULL_URL=
 QDRANT_FULL_URL=
 ADDITIONAL_CORS_ORIGINS=
 
+# Posthog Configuration
+POSTHOG_API_KEY=phc_your_api_key_here
+POSTHOG_HOST=https://app.posthog.com
+ANALYTICS_ENABLED=true
+
 # Other Settings
 PROJECT_NAME=Airweave
 LOG_LEVEL=INFO

backend/airweave/analytics/README.md

@@ -0,0 +1,293 @@
+# Airweave Analytics Module
+
+This module provides PostHog analytics integration for Airweave, enabling comprehensive tracking of user behavior, business metrics, and system performance.
+
+## 🏗️ Architecture
+
+The analytics module is organized into several components:
+
+- **`service.py`**: Core PostHog integration service
+- **`decorators/`**: Decorators for automatic tracking of API endpoints and operations
+- **`events/`**: Business event tracking classes for high-level metrics
+- **`config.py`**: Analytics configuration (integrated into core config)
+
+## 🚀 Quick Start
+
+### 1. Environment Setup
+
+Add these variables to your `.env` file:
+
+```bash
+# PostHog Configuration
+POSTHOG_API_KEY=phc_your_api_key_here
+POSTHOG_HOST=https://app.posthog.com
+ANALYTICS_ENABLED=true
+```
+
+### 2. Basic Usage
+
+```python
+from airweave.analytics import analytics, business_events
+
+# Track a custom event
+analytics.track_event(
+    event_name="custom_event",
+    distinct_id="user_123",
+    properties={"key": "value"}
+)
+
+# Track business events
+business_events.track_organization_created(
+    organization_id=org_id,
+    user_id=user_id,
+    properties={"plan": "trial"}
+)
+```
+
+### 3. Using Decorators
+
+```python
+from airweave.analytics import track_api_endpoint, track_search_operation
+
+@track_api_endpoint("create_collection")
+async def create_collection(ctx: ApiContext, ...):
+    # Your endpoint logic
+    pass
+
+@track_search_operation()
+async def search_collection(ctx: ApiContext, query: str, ...):
+    # Your search logic
+    pass
+```
+
+## 📊 Complete Analytics Events Overview
+
+### API Events
+- **`api_call`**: Successful API calls with timing and context
+- **`api_call_error`**: Failed API calls with error details and status codes
+
+**Covered Endpoints:**
+- `create_organization` - Organization creation
+- `list_collections` - Collection listing  
+- `create_collection` - Collection creation
+- `create_source_connection` - Source connection setup
+- `run_sync` - Sync execution
+- `search` - Basic search queries
+- `search_advanced` - Advanced search queries
+
+### Search Events
+- **`search_query`**: Successful search operations with query analysis
+- **`search_query_error`**: Failed search operations with error details
+
+### Business Events
+- **`organization_created`**: New organization signup
+- **`collection_created`**: New collection creation
+- **`source_connection_created`**: New source integration
+
+### Sync Events
+- **`sync_completed`**: Successful sync job completion with entity counts
+- **`entities_synced_by_type`**: Granular entity tracking per sync and entity type
+
+## 🎯 Dashboard Strategy
+
+### Dashboard 1: Airweave Overview
+**Purpose:** High-level business metrics and system health
+**Key Metrics:**
+- Query volume over time (weekly/monthly)
+- Query response times
+- Popular data sources
+- Error rates by endpoint
+- Total entities in sync
+- Query volume per organization
+
+### Dashboard 2: User Journey
+**Purpose:** Track user progression and identify drop-off points
+**Key Metrics:**
+- User funnel: org created → collection created → source added → first search
+- Time to first search ("time to wow")
+- Feature adoption rates
+- User retention metrics
+
+### Dashboard 3: Syncing & Storage
+**Purpose:** Monitor sync performance and storage usage
+**Key Metrics:**
+- Sync success/error rates
+- Entities synced per sync configuration
+- Storage usage by organization
+- Sync performance trends
+- Entity type distribution
+
+### Dashboard 4: Performance & Errors
+**Purpose:** System reliability and performance monitoring
+**Key Metrics:**
+- API error rates by endpoint
+- Search error rates
+- Sync error rates
+- Performance trends
+- Error patterns and troubleshooting
+
+### Dashboard 5: Advanced Analytics
+**Purpose:** Deep insights and custom analysis
+**Key Metrics:**
+- Query patterns and complexity
+- User behavior analysis
+- Integration health scores
+- Custom business metrics
+
+## 📈 PostHog Widget Configurations
+
+### Overview Dashboard Widgets
+1. **Query Volume Over Time**
+   - Event: `search_query`
+   - Type: Line Chart
+   - Property: Count
+   - Time Range: Last 30 days
+
+2. **Query Response Times**
+   - Event: `search_query`
+   - Type: Line Chart
+   - Property: `duration_ms` (Average)
+   - Time Range: Last 7 days
+
+3. **Error Rate by Endpoint**
+   - Event: `api_call_error`
+   - Type: Bar Chart
+   - Property: Count
+   - Breakdown: `endpoint`
+   - Time Range: Last 7 days
+
+### User Journey Dashboard Widgets
+1. **User Funnel**
+   - Events: `organization_created` → `collection_created` → `source_connection_created` → `search_query`
+   - Type: Funnel
+   - Time Range: Last 30 days
+
+2. **Time to First Search**
+   - Event: `search_query`
+   - Type: Histogram (if supported) or Line Chart
+   - Property: `searched_at`
+   - Time Range: Last 30 days
+
+### Syncing Dashboard Widgets
+1. **Sync Success Rate**
+   - Event: `sync_completed`
+   - Type: Line Chart
+   - Property: Count
+   - Time Range: Last 30 days
+
+2. **Entities Synced per Sync**
+   - Event: `sync_completed`
+   - Type: Bar Chart
+   - Property: `total_entities` (Sum)
+   - Breakdown: `sync_id`
+   - Time Range: Last 7 days
+
+3. **Storage Usage by Organization**
+   - Event: `entities_synced_by_type`
+   - Type: Bar Chart
+   - Property: `entity_count` (Sum)
+   - Breakdown: `organization_name`
+   - Time Range: Last 7 days
+
+## 🔧 Configuration
+
+The analytics module respects these configuration options:
+
+- `POSTHOG_API_KEY`: Your PostHog API key (required)
+- `POSTHOG_HOST`: PostHog host URL (default: https://app.posthog.com)
+- `ANALYTICS_ENABLED`: Enable/disable analytics (default: true)
+- `ENVIRONMENT`: Deployment environment - added as property to all events
+
+**Important**: Analytics events are emitted when `ANALYTICS_ENABLED=true`. Each event includes an `environment` property allowing you to filter by environment in PostHog dashboards. Control which environments emit events via their respective environment files.
+
+### Environment Configuration Examples
+
+```bash
+# Production environment (.env.prod)
+ANALYTICS_ENABLED=true
+ENVIRONMENT=prd
+
+# Development environment (.env.dev)
+ANALYTICS_ENABLED=true
+ENVIRONMENT=dev
+
+# Local development (.env.local)
+ANALYTICS_ENABLED=false
+ENVIRONMENT=local
+
+# Testing (.env.test)
+ANALYTICS_ENABLED=false
+ENVIRONMENT=test
+```
+
+### PostHog Dashboard Filtering
+
+- **Production Only**: `environment = "prd"`
+- **All Environments**: No filter
+- **Exclude Local**: `environment != "local"`
+- **Development Only**: `environment = "dev"`
+
+## 💡 Best Practices
+
+### 1. Use Decorators for Automatic Tracking
+```python
+@track_api_endpoint("endpoint_name")
+async def my_endpoint(ctx: ApiContext, ...):
+    # Automatically tracks timing, errors, and context
+    pass
+```
+
+### 2. Track Business Events at Key Milestones
+```python
+# Track when user completes onboarding
+business_events.track_first_sync_completed(ctx, sync_id, entities_count)
+```
+
+### 3. Include Rich Context
+```python
+analytics.track_event(
+    event_name="custom_event",
+    distinct_id=user_id,
+    properties={
+        "organization_name": ctx.organization.name,
+        "plan": ctx.organization.plan,
+        "feature": "advanced_search"
+    },
+    groups={"organization": str(ctx.organization.id)}
+)
+```
+
+### 4. Handle Errors Gracefully
+The analytics service automatically handles PostHog errors and logs them without affecting your application.
+
+## 🔒 Privacy & Compliance
+
+- All user data is sent to PostHog (ensure compliance with your privacy policy)
+- User IDs are hashed/obfuscated as needed
+- Sensitive data should not be included in event properties
+- Consider data retention policies in PostHog
+
+## 🚨 Troubleshooting
+
+### Common Issues
+
+1. **Events not appearing in PostHog**
+   - Check `POSTHOG_API_KEY` is set correctly
+   - Verify `ANALYTICS_ENABLED=true`
+   - Check logs for PostHog errors
+
+2. **High event volume**
+   - PostHog free tier: 1M events/month
+   - Consider sampling for high-volume events
+   - Use `ANALYTICS_ENABLED=false` to disable
+
+3. **Performance impact**
+   - Analytics calls are async and non-blocking
+   - Errors are logged but don't affect application flow
+   - Consider batching for high-frequency events
+
+## 📚 Additional Resources
+
+- [PostHog Documentation](https://posthog.com/docs)
+- [PostHog Python SDK](https://posthog.com/docs/libraries/python)
+- [Airweave Analytics Examples](analytics_integration_example.py)

backend/airweave/analytics/__init__.py

@@ -0,0 +1,13 @@
+"""Analytics module for PostHog integration."""
+
+from .decorators.api import track_api_endpoint
+from .decorators.search import track_search_operation
+from .events.business_events import business_events
+from .service import analytics
+
+__all__ = [
+    "analytics",
+    "business_events",
+    "track_api_endpoint",
+    "track_search_operation",
+]

backend/airweave/analytics/decorators/__init__.py

@@ -0,0 +1,9 @@
+"""Decorators for analytics tracking."""
+
+from .api import track_api_endpoint
+from .search import track_search_operation
+
+__all__ = [
+    "track_api_endpoint",
+    "track_search_operation",
+]