references/EXAMPLE.md
PostHog FastAPI Example Project
Repository: https://github.com/PostHog/context-mill Path: basics/fastapi
README.md
PostHog FastAPI Example
A FastAPI application demonstrating PostHog integration for analytics, feature flags, and error tracking.
Features
- User registration and authentication with cookie-based sessions
- SQLite database persistence with SQLAlchemy
- User identification and property tracking
- Custom event tracking
- Feature flags with payload support
- Error tracking with manual exception capture
Quick Start
-
Create and activate a virtual environment:
python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate -
Install dependencies:
pip install -r requirements.txt -
Copy the environment file and configure:
cp .env.example .env # Edit .env with your PostHog project key -
Run the application:
python run.py -
Open http://localhost:5002 and either:
- Login with default credentials:
[email protected]/admin - Or click "Sign up here" to create a new account
- Login with default credentials:
PostHog Integration Points
User Registration
New users are identified and tracked on signup using the context-based API:
with new_context():
identify_context(user.email)
tag('email', user.email)
tag('is_staff', user.is_staff)
capture('user_signed_up', properties={'signup_method': 'form'})
User Identification
Users are identified on login with their properties:
with new_context():
identify_context(user.email)
tag('email', user.email)
tag('is_staff', user.is_staff)
capture('user_logged_in', properties={'login_method': 'password'})
Event Tracking
Custom events are captured throughout the app:
with new_context():
identify_context(current_user.email)
capture('burrito_considered', properties={'total_considerations': count})
Feature Flags
The dashboard demonstrates feature flag checking:
show_new_feature = posthog.feature_enabled(
'new-dashboard-feature',
current_user.email,
person_properties={'email': current_user.email, 'is_staff': current_user.is_staff}
)
feature_config = posthog.get_feature_flag_payload('new-dashboard-feature', current_user.email)
Error Tracking
The example demonstrates two approaches to error tracking:
Manual capture for specific critical operations** (app/routers/api.py).
try:
# Critical operation that might fail
result = process_payment()
except Exception as e:
# Manually capture this specific exception
with new_context():
identify_context(current_user.email)
event_id = posthog.capture_exception(e)
return JSONResponse({
"error": "Operation failed",
"error_id": event_id,
"message": f"Error captured in PostHog. Reference ID: {event_id}"
}, status_code=500)
The /api/test-error endpoint demonstrates manual exception capture. Use ?capture=true to capture in PostHog, or ?capture=false to skip tracking.
Project Structure
basics/fastapi/
├── app/
│ ├── __init__.py # Package marker
│ ├── config.py # Pydantic Settings configuration
│ ├── database.py # SQLAlchemy setup
│ ├── dependencies.py # FastAPI dependency injection
│ ├── main.py # Application factory and lifespan
│ ├── models.py # User model (SQLAlchemy)
│ ├── routers/
│ │ ├── __init__.py # Routers package
│ │ ├── main.py # Page routes (HTML)
│ │ └── api.py # API endpoints (JSON)
│ └── templates/ # Jinja2 templates
├── .env.example
├── .gitignore
├── requirements.txt
├── README.md
└── run.py # Entry point (uvicorn)
.env.example
POSTHOG_PROJECT_TOKEN=<ph_project_token>
POSTHOG_HOST=https://us.i.posthog.com
SECRET_KEY=your-secret-key-here
DEBUG=True
POSTHOG_DISABLED=False
app/init.py
"""FastAPI PostHog example application."""
app/config.py
"""FastAPI application configuration using Pydantic Settings."""
from functools import lru_cache
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
"""Application settings loaded from environment variables."""
model_config = SettingsConfigDict(
env_file=".env",
env_file_encoding="utf-8",
extra="ignore",
)
# Application
secret_key: str = "dev-secret-key-change-in-production"
debug: bool = True
# Database (SQLite like Flask example)
database_url: str = "sqlite:///./db.sqlite3"
# PostHog
posthog_project_token: str = "<ph_project_token>"
posthog_host: str = "https://us.i.posthog.com"
posthog_disabled: bool = False
@lru_cache
def get_settings() -> Settings:
"""Get cached settings instance."""
return Settings()
app/database.py
"""Database configuration with SQLAlchemy."""
from sqlalchemy import create_engine
from sqlalchemy.orm import DeclarativeBase, sessionmaker
from app.config import get_settings
settings = get_settings()
engine = create_engine(
settings.database_url,
connect_args={"check_same_thread": False}, # Required for SQLite
)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
class Base(DeclarativeBase):
"""Base class for SQLAlchemy models."""
pass
def get_db():
"""Dependency that provides a database session."""
db = SessionLocal()
try:
yield db
finally:
db.close()
def init_db():
"""Create all database tables."""
Base.metadata.create_all(bind=engine)
app/dependencies.py
"""Authentication dependencies for FastAPI."""
from typing import Annotated, Optional
from fastapi import Cookie, Depends, HTTPException, status
from itsdangerous import BadSignature, URLSafeSerializer
from sqlalchemy.orm import Session
from app.config import get_settings
from app.database import get_db
from app.models import User
settings = get_settings()
serializer = URLSafeSerializer(settings.secret_key)
def get_session_user_id(session_token: Annotated[Optional[str], Cookie()] = None) -> Optional[int]:
"""Extract user ID from session cookie."""
if not session_token:
return None
try:
data = serializer.loads(session_token)
return data.get("user_id")
except BadSignature:
return None
def get_current_user(
db: Annotated[Session, Depends(get_db)],
user_id: Annotated[Optional[int], Depends(get_session_user_id)],
) -> Optional[User]:
"""Get the current authenticated user, or None if not authenticated."""
if user_id is None:
return None
return User.get_by_id(db, user_id)
def require_auth(
current_user: Annotated[Optional[User], Depends(get_current_user)],
) -> User:
"""Require authentication - raises 401 if not authenticated."""
if current_user is None:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Authentication required",
)
return current_user
def create_session_token(user_id: int) -> str:
"""Create a signed session token for the user."""
return serializer.dumps({"user_id": user_id})
# Type aliases for cleaner dependency injection
CurrentUser = Annotated[Optional[User], Depends(get_current_user)]
RequiredUser = Annotated[User, Depends(require_auth)]
DbSession = Annotated[Session, Depends(get_db)]
app/main.py
"""FastAPI application with PostHog integration."""
from contextlib import asynccontextmanager
from pathlib import Path
import posthog
from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse, JSONResponse
from fastapi.staticfiles import StaticFiles
from fastapi.templating import Jinja2Templates
from app.config import get_settings
from app.database import SessionLocal, init_db
from app.middleware import PostHogMiddleware
from app.models import User
from app.routers import api, main
settings = get_settings()
# Setup templates
templates_dir = Path(__file__).parent / "templates"
templates = Jinja2Templates(directory=str(templates_dir))
@asynccontextmanager
async def lifespan(app: FastAPI):
"""Application lifespan events for startup/shutdown."""
# Startup: Initialize PostHog
if not settings.posthog_disabled:
posthog.api_key = settings.posthog_project_token
posthog.host = settings.posthog_host
posthog.debug = settings.debug
# Initialize database and seed default user
init_db()
db = SessionLocal()
try:
if not User.get_by_email(db, "[email protected]"):
User.create_user(
db,
email="[email protected]",
password="admin",
is_staff=True,
)
finally:
db.close()
yield
# Shutdown: Flush PostHog events
if not settings.posthog_disabled:
posthog.flush()
app = FastAPI(
title="PostHog FastAPI Example",
description="Example application demonstrating PostHog integration with FastAPI",
lifespan=lifespan,
)
app.add_middleware(PostHogMiddleware)
# Include routers
app.include_router(main.router)
app.include_router(api.router, prefix="/api")
# Error handlers
@app.exception_handler(404)
async def not_found_handler(request: Request, exc):
"""Handle 404 errors."""
if request.url.path.startswith("/api/"):
return JSONResponse({"error": "Not found"}, status_code=404)
return templates.TemplateResponse(
request, "errors/404.html", status_code=404
)
@app.exception_handler(500)
async def internal_error_handler(request: Request, exc):
"""Handle 500 errors."""
if request.url.path.startswith("/api/"):
return JSONResponse({"error": "Internal server error"}, status_code=500)
return templates.TemplateResponse(
request, "errors/500.html", status_code=500
)
app/middleware.py
"""PostHog middleware for automatic context and user identification.
Uses pure ASGI middleware instead of BaseHTTPMiddleware for better performance/best practices.
"""
from http.cookies import SimpleCookie
from typing import Callable, Optional
from posthog import identify_context, new_context, tag
from app.config import get_settings
from app.database import SessionLocal
from app.dependencies import serializer
from app.models import User
class PostHogMiddleware:
"""Pure ASGI middleware that wraps each request in a PostHog context.
If the user is authenticated, identifies them in the context so routes
can just call capture() without needing to set up context each time.
Uses pure ASGI interface for better performance than BaseHTTPMiddleware.
"""
def __init__(self, app):
self.app = app
self.settings = get_settings()
async def __call__(self, scope, receive, send):
if scope["type"] != "http" or self.settings.posthog_disabled:
await self.app(scope, receive, send)
return
user = self._get_user_from_scope(scope)
with new_context():
if user:
identify_context(user.email)
tag("email", user.email)
tag("is_staff", user.is_staff)
await self.app(scope, receive, send)
def _get_user_from_scope(self, scope) -> Optional[User]:
"""Extract authenticated user from session cookie in ASGI scope."""
headers = dict(scope.get("headers", []))
cookie_header = headers.get(b"cookie", b"").decode("utf-8")
if not cookie_header:
return None
cookies = SimpleCookie()
cookies.load(cookie_header)
session_cookie = cookies.get("session_token")
if not session_cookie:
return None
session_token = session_cookie.value
try:
data = serializer.loads(session_token)
user_id = data.get("user_id")
except Exception:
return None
if not user_id:
return None
db = SessionLocal()
try:
return User.get_by_id(db, user_id)
finally:
db.close()
app/models.py
"""User model with SQLite persistence (similar to Flask example)."""
from datetime import datetime, timezone
from typing import Optional
from sqlalchemy import Boolean, DateTime, Integer, String
from sqlalchemy.orm import Mapped, Session, mapped_column
from werkzeug.security import check_password_hash, generate_password_hash
from app.database import Base
class User(Base):
"""User model with SQLite persistence."""
__tablename__ = "users"
id: Mapped[int] = mapped_column(Integer, primary_key=True)
email: Mapped[str] = mapped_column(String(254), unique=True, nullable=False)
password_hash: Mapped[str] = mapped_column(String(256), nullable=False)
name: Mapped[Optional[str]] = mapped_column(String(100), nullable=True)
is_staff: Mapped[bool] = mapped_column(Boolean, default=False)
is_active: Mapped[bool] = mapped_column(Boolean, default=True)
login_count: Mapped[int] = mapped_column(Integer, default=0)
date_joined: Mapped[datetime] = mapped_column(
DateTime, default=lambda: datetime.now(timezone.utc)
)
def set_password(self, password: str) -> None:
"""Hash and set the user's password."""
self.password_hash = generate_password_hash(password, method="pbkdf2:sha256")
def check_password(self, password: str) -> bool:
"""Verify the password against the hash."""
return check_password_hash(self.password_hash, password)
@classmethod
def create_user(
cls, db: Session, email: str, password: str, is_staff: bool = False
) -> "User":
"""Create and save a new user."""
user = cls(email=email, is_staff=is_staff)
# nosemgrep: python.django.security.audit.unvalidated-password.unvalidated-password
user.set_password(password)
db.add(user)
db.commit()
db.refresh(user)
return user
@classmethod
def get_by_id(cls, db: Session, user_id: int) -> Optional["User"]:
"""Get user by ID."""
return db.query(cls).filter(cls.id == user_id).first()
@classmethod
def get_by_email(cls, db: Session, email: str) -> Optional["User"]:
"""Get user by email."""
return db.query(cls).filter(cls.email == email).first()
@classmethod
def authenticate(cls, db: Session, email: str, password: str) -> Optional["User"]:
"""Authenticate user with email and password."""
user = cls.get_by_email(db, email)
if user and user.check_password(password):
return user
return None
def record_login(self, db: Session) -> bool:
"""Record a login and return whether this is the user's first login."""
is_first_login = self.login_count == 0
self.login_count += 1
db.commit()
return is_first_login
def update_profile(self, db: Session, name: Optional[str] = None) -> list:
"""Update user profile and return list of changed fields."""
changed_fields = []
if name is not None and name != self.name:
self.name = name
changed_fields.append("name")
if changed_fields:
db.commit()
return changed_fields
def __repr__(self) -> str:
return f"<User {self.email}>"
app/routers/init.py
"""FastAPI routers package."""
app/routers/api.py
"""API endpoints demonstrating PostHog integration patterns."""
from typing import Annotated
import posthog
from fastapi import APIRouter, Cookie, Form, Query
from fastapi.responses import JSONResponse
from posthog import capture
from app.dependencies import RequiredUser
router = APIRouter()
MAX_BURRITO_COUNT = 10000
@router.post("/burrito/consider")
async def consider_burrito(
current_user: RequiredUser,
burrito_count: Annotated[int, Cookie()] = 0,
):
"""Track burrito consideration event."""
safe_count = max(0, min(burrito_count, MAX_BURRITO_COUNT))
new_count = safe_count + 1
capture("burrito_considered", properties={"total_considerations": new_count})
response = JSONResponse({"success": True, "count": new_count})
response.set_cookie(
key="burrito_count",
value=str(new_count),
httponly=True,
samesite="lax",
)
return response
@router.post("/test-error")
async def test_error(
current_user: RequiredUser,
capture_param: Annotated[str, Query(alias="capture")] = "true",
):
"""Test endpoint demonstrating manual exception capture in PostHog."""
should_capture = capture_param.lower() == "true"
try:
raise Exception("Test exception from critical operation")
except Exception as e:
if should_capture:
event_id = posthog.capture_exception(e)
return JSONResponse(
{
"error": "Operation failed",
"error_id": event_id,
"message": f"Error captured in PostHog. Reference ID: {event_id}",
},
status_code=500,
)
else:
return JSONResponse({"error": "Operation failed"}, status_code=500)
@router.post("/trigger-error")
async def trigger_error(
current_user: RequiredUser,
error_type: Annotated[str, Form()] = "generic",
):
"""Trigger different error types for testing error tracking."""
error_messages = {
"value": "Invalid value provided",
"key": "Missing required key",
"generic": "Generic test error",
}
safe_error_type = error_type if error_type in error_messages else "generic"
error_message = error_messages[safe_error_type]
try:
if safe_error_type == "value":
raise ValueError(error_message)
elif safe_error_type == "key":
raise KeyError("missing_key")
else:
raise Exception(error_message)
except Exception as e:
posthog.capture_exception(e)
capture(
"error_triggered",
properties={"error_type": safe_error_type, "error_message": error_message},
)
return JSONResponse(
{
"success": True,
"message": "Error captured in PostHog",
"error": error_message,
}
)
@router.post("/reports/activity")
async def generate_activity_report(
current_user: RequiredUser,
report_type: Annotated[str, Form()] = "summary",
):
"""Generate user activity report."""
valid_report_types = {"summary", "detailed", "export"}
safe_report_type = report_type if report_type in valid_report_types else "summary"
report_data = {
"user": current_user.email,
"name": current_user.name,
"date_joined": current_user.date_joined.isoformat(),
"login_count": current_user.login_count,
"is_staff": current_user.is_staff,
}
if safe_report_type == "detailed":
report_data["account_age_days"] = (
__import__("datetime").datetime.now(__import__("datetime").timezone.utc)
- current_user.date_joined
).days
row_count = len(report_data)
capture(
"report_generated",
properties={
"report_type": safe_report_type,
"row_count": row_count,
"username": current_user.email,
},
)
return JSONResponse(
{
"success": True,
"report_type": safe_report_type,
"row_count": row_count,
"data": report_data,
}
)
app/routers/main.py
"""Main routes demonstrating PostHog integration patterns."""
from pathlib import Path
from typing import Annotated
import posthog
from fastapi import APIRouter, Cookie, Depends, Form, Request
from fastapi.responses import HTMLResponse, RedirectResponse
from fastapi.templating import Jinja2Templates
from posthog import capture
from app.dependencies import (
CurrentUser,
DbSession,
RequiredUser,
create_session_token,
)
from app.models import User
router = APIRouter()
# Setup templates
templates_dir = Path(__file__).parent.parent / "templates"
templates = Jinja2Templates(directory=str(templates_dir))
@router.get("/", response_class=HTMLResponse)
async def home(request: Request, current_user: CurrentUser, db: DbSession):
"""Home/login page."""
if current_user:
return RedirectResponse(url="/dashboard", status_code=302)
return templates.TemplateResponse(
request, "home.html", {"current_user": current_user}
)
@router.post("/", response_class=HTMLResponse)
async def login(
request: Request,
db: DbSession,
email: Annotated[str, Form()],
password: Annotated[str, Form()],
):
"""Handle login form submission."""
user = User.authenticate(db, email, password)
if user:
is_new_user = user.record_login(db)
posthog.identify(user.email, {"email": user.email, "is_staff": user.is_staff})
posthog.capture(
user.email,
"user_logged_in",
properties={
"username": user.email,
"is_new_user": is_new_user,
},
)
# Create session and redirect
response = RedirectResponse(url="/dashboard", status_code=302)
response.set_cookie(
key="session_token",
value=create_session_token(user.id),
httponly=True,
samesite="lax",
)
return response
# Login failed
return templates.TemplateResponse(
request,
"home.html",
{"current_user": None, "error": "Invalid email or password"},
)
@router.get("/signup", response_class=HTMLResponse)
async def signup_page(request: Request, current_user: CurrentUser):
"""User registration page."""
if current_user:
return RedirectResponse(url="/dashboard", status_code=302)
return templates.TemplateResponse(
request, "signup.html", {"current_user": current_user}
)
@router.post("/signup", response_class=HTMLResponse)
async def signup(
request: Request,
db: DbSession,
email: Annotated[str, Form()],
password: Annotated[str, Form()],
password_confirm: Annotated[str, Form()],
):
"""Handle signup form submission."""
error = None
if not email or not password:
error = "Email and password are required"
elif password != password_confirm:
error = "Passwords do not match"
elif User.get_by_email(db, email):
error = "Email already registered"
if error:
return templates.TemplateResponse(
request, "signup.html", {"current_user": None, "error": error}
)
# Create new user
user = User.create_user(db, email=email, password=password, is_staff=False)
posthog.identify(user.email, {"email": user.email, "is_staff": user.is_staff})
posthog.capture(
user.email,
"user_signed_up",
properties={
"username": user.email,
"signup_method": "form",
},
)
# Create session and redirect
response = RedirectResponse(url="/dashboard", status_code=302)
response.set_cookie(
key="session_token",
value=create_session_token(user.id),
httponly=True,
samesite="lax",
)
return response
@router.get("/logout")
async def logout(current_user: RequiredUser):
"""Logout and capture event."""
capture("user_logged_out")
response = RedirectResponse(url="/", status_code=302)
response.delete_cookie(key="session_token")
return respo