Error Tracking Python

Python error tracking installation - Docs

1. 1

   Install the package

   Required

   Install the PostHog Python library using pip:

   Terminal

   PostHog AI

   Copy

   pip install posthog

2. 2

   Initialize PostHog

   Required

   Initialize the PostHog client with your project token and host from your project settings:

   Python

   PostHog AI

   Copy

   from posthog import Posthog
   posthog = Posthog(
       project_api_key='<ph_project_token>',
       host='https://us.i.posthog.com'
   )

   Django integration

   If you're using Django, check out our Django integration for automatic request tracking.

3. 3

   Send events

   Recommended

   Once installed, PostHog will automatically start capturing events. You can also manually send events to test your integration:

   Capture custom events by calling the capture method with an event name and properties:

   Python

   PostHog AI

   Copy

   import posthog
   posthog.capture('user_123', 'user_signed_up', properties={'example_property': 'example_value'})

4. Verify PostHog is initialized

   Recommended

   Before proceeding, enable debug and call posthog.capture('test_event') to make sure you can capture events.

5. 4

   Setting up exception autocapture

   Recommended

   Exception autocapture can be enabled during initialization of the PostHog client to automatically capture any unhandled exceptions thrown by your Python application. It works by setting Python's built-in exception hooks, such as sys.excepthook and threading.excepthook.

   Python

   PostHog AI

   Copy

   from posthog import Posthog
   posthog = Posthog("<ph_project_token>", enable_exception_autocapture=True, ...)

   We recommend setting up and using contexts so that exceptions automatically include distinct IDs, session IDs, and other properties you can set up with tags.

   You can also enable code variables capture to automatically capture the state of local variables when exceptions occur, giving you a debugger-like view of your application.

6. 5

   Manually capturing exceptions

   Optional

   For exceptions handled by your application that you would still like sent to PostHog, you can manually call the capture method:

   Python

   PostHog AI

   Copy

   posthog.capture_exception(e, distinct_id="user_distinct_id", properties=additional_properties)

   You can find a full example of all of this in our Python (and Flask) error tracking tutorial.

7. 6

   Framework-specific exception capture

   Optional

   Python frameworks often have built-in error handlers. This means PostHog's default exception autocapture won't work and we need to manually capture errors instead. The exact process depends on the framework:

   Django

   The Python SDK provides a Django middleware that automatically wraps all requests with a context. Add the middleware to your Django settings:

   Python

   PostHog AI

   Copy

   MIDDLEWARE = [
       # ... other middleware
       'posthog.integrations.django.PosthogContextMiddleware',
       # ... other middleware
   ]

   By default, the middleware captures exceptions and sends them to PostHog. Disable with POSTHOG_MW_CAPTURE_EXCEPTIONS = False. Use POSTHOG_MW_EXTRA_TAGS, POSTHOG_MW_REQUEST_FILTER, and POSTHOG_MW_TAG_MAP to customize. See the Django integration docs for full configuration.

   Flask

   Python

   PostHog AI

   Copy

   from flask import Flask, jsonify
   from posthog import Posthog
   posthog = Posthog('<ph_project_token>', host='https://us.i.posthog.com')
   @app.errorhandler(Exception)
   def handle_exception(e):
       event_id = posthog.capture_exception(e)
       response = jsonify({'message': str(e), 'error_id': event_id})
       response.status_code = 500
       return response

   FastAPI

   Python

   PostHog AI

   Copy

   from fastapi.responses import JSONResponse
   from posthog import Posthog
   posthog = Posthog('<ph_project_token>', host='https://us.i.posthog.com')
   @app.exception_handler(Exception)
   async def http_exception_handler(request, exc):
       posthog.capture_exception(exc)
       return JSONResponse(status_code=500, content={'message': str(exc)})

8. Verify error tracking

   Recommended

   Confirm events are being sent to PostHog

   Before proceeding, let's make sure exception events are being captured and sent to PostHog. You should see events appear in the activity feed.

   Image: Activity feed with eventsImage: Activity feed with events

   Check for exceptions in PostHog

Community questions

Ask a question

Was this page useful?

HelpfulCould be better