AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

instrument-error-tracking

Add PostHog error tracking to capture and monitor exceptions. Use after implementing features or reviewing PRs to ensure errors are tracked with stack traces and source maps. Also handles initial PostHog SDK setup if not yet installed.

Original source
posthog
License
MIT
Pinned revision
cac7c80a9e5b73484d18eda1bffb47297c938e0c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read posthog--instrument-error-tracking at revision cac7c80a9e5b73484d18eda1bffb47297c938e0c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 30

references/php.md

AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

PHP Error Tracking installation

Canonical URL: https://posthog.com/docs/error-tracking/installation/php

Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use https://eu.i.posthog.com instead of https://us.i.posthog.com (ingestion host), and use https://eu.posthog.com instead of https://app.posthog.com (app host for links).

On this page

  1. 1

    Install the PHP SDK

    Required

    Install the PostHog PHP SDK via Composer:

    composer require posthog/posthog-php
    
  2. 2

    Initialize the client

    Required

    Set your project token and instance address before making any calls:

    PostHog\PostHog::init(
        '<ph_project_token>',
        ['host' => 'https://us.i.posthog.com']
    );
    

    You can find your project token and instance address in the project settings page in PostHog.

  3. 3

    Capture exceptions

    Required

    Use captureException to manually capture exceptions and send them to PostHog as $exception events with full stack traces.

    Basic usage

    try {
        // Your code that might throw
        riskyOperation();
    } catch (\Throwable $e) {
        PostHog\PostHog::captureException($e, 'user_distinct_id');
    }
    

    With additional properties

    You can pass extra properties to include with the exception event:

    try {
        processOrder($orderId);
    } catch (\Throwable $e) {
        PostHog\PostHog::captureException($e, 'user_distinct_id', [
            'order_id' => $orderId,
            'environment' => 'production',
        ]);
    }
    

    You can also pass a plain string if you want to send an error message without a Throwable.

  4. 4

    Enable automatic capture

    Recommended

    Automatic capture is opt-in for PHP. When enabled, the SDK installs handlers for uncaught exceptions. With the default capture_errors: true, it also captures PHP errors and fatal shutdown errors.

    PostHog\PostHog::init(
        '<ph_project_token>',
        [
            'host' => 'https://us.i.posthog.com',
            'error_tracking' => [
                'enabled' => true,
            ],
        ]
    );
    

    Existing handlers are preserved

    The SDK chains existing exception and error handlers instead of replacing your app's behavior.

  5. 5

    Identify users and attach request context

    Recommended

    By default, automatically captured errors are anonymous. Use context_provider to attach a distinctId and request metadata to every automatically captured error event.

    PostHog\PostHog::init(
        '<ph_project_token>',
        [
            'host' => 'https://us.i.posthog.com',
            'error_tracking' => [
                'enabled' => true,
                'context_provider' => static function (array $payload): array {
                    return [
                        'distinctId' => $_SESSION['user_id'] ?? null,
                        'properties' => [
                            '$current_url' => $_SERVER['REQUEST_URI'] ?? null,
                            '$request_method' => $_SERVER['REQUEST_METHOD'] ?? null,
                            '$exception_source' => $payload['source'] ?? null,
                        ],
                    ];
                },
            ],
        ]
    );
    

    If distinctId is omitted, PostHog sends the event with an auto-generated ID and sets $process_person_profile to false.

  6. 6

    Configure error tracking options

    Optional

    PostHog\PostHog::init(
        '<ph_project_token>',
        [
            'host' => 'https://us.i.posthog.com',
            'error_tracking' => [
                'enabled' => true,
                'capture_errors' => true,
                'excluded_exceptions' => [
                    \InvalidArgumentException::class,
                ],
                'max_frames' => 20,
                'context_provider' => static function (array $payload): array {
                    return [
                        'distinctId' => $_SESSION['user_id'] ?? null,
                        'properties' => [],
                    ];
                },
            ],
        ]
    );
    

    | Option | Type | Default | Description | | --- | --- | --- | --- | | enabled | boolean | false | Enables automatic error tracking handlers. Manual captureException works regardless. | | capture_errors | boolean | true | When enabled, also captures PHP errors and fatal shutdown errors in addition to uncaught exceptions. | | excluded_exceptions | array of class strings | [] | Throwable classes to skip during automatic capture. | | max_frames | integer | 20 | Maximum number of stack frames included in $exception_list. | | context_provider | callable or null | null | Callback that returns distinctId and extra event properties for automatic captures. |

  7. Verify error tracking

    Recommended

    Trigger a test exception to confirm events are being sent to PostHog. You should see them appear in the Error Tracking tab.

    PostHog\PostHog::init(
        '<ph_project_token>',
        [
            'host' => 'https://us.i.posthog.com',
            'error_tracking' => [
                'enabled' => true,
            ],
        ]
    );
    
    try {
        throw new \Exception('Test exception from PHP');
    } catch (\Throwable $e) {
        PostHog\PostHog::captureException($e, 'test_user');
    }
    
  8. 7

    Link releases

    Optional

    Great, you're capturing exceptions! To see which release each exception comes from, give your app the release ID when you deploy.

    Link releases