vybekiit 0.7.33 → 0.7.35

package/dist/global-skills/instrument-product-analytics/references/php.md

@@ -2,22 +2,37 @@
 
 # PHP
 
+Canonical URL: https://posthog.com/docs/libraries/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
+
+- [Installation](#installation)
+- [Identifying users](#identifying-users)
+- [Capturing events](#capturing-events)
+- [Person profiles and properties](#person-profiles-and-properties)
+- [Alias](#alias)
+- [Feature flags](#feature-flags)
+- [Request context](#request-context)
+- [Error tracking](#error-tracking)
+- [Config options](#config-options)
+- [Flushing and shutting down](#flushing-and-shutting-down)
+- [Debug mode](#debug-mode)
+- [Thank you](#thank-you)
+
 This is an optional library you can install if you're working with PHP. It uses an internal queue to batch requests, flushes at the end of the request, and optionally does so in an async manner.
 
 ## Installation
 
 Install the package with Composer:
 
-Terminal
-
 ```bash
 composer require posthog/posthog-php
 ```
 
 In your app, set your project token before making any calls.
 
-PHP
-
 ```php
 PostHog\PostHog::init("<ph_project_token>",
   ['host' => 'https://us.i.posthog.com']
@@ -30,16 +45,14 @@ You can find your project token and instance address in the [project settings](h
 
 ## Identifying users
 
-> **Identifying users is required.** Backend events need a `distinct_id` that matches the ID your frontend uses when calling `posthog.identify()`. Without this, backend events are orphaned — they can't be linked to frontend event captures, [session replays](/docs/session-replay.md), [LLM traces](/docs/ai-engineering.md), or [error tracking](/docs/error-tracking.md).
+> **Identifying users is required.** Backend events need a `distinct_id` that matches the ID your frontend uses when calling `posthog.identify()`. Without this, backend events are orphaned — they can't be linked to frontend event captures, [session replays](https://posthog.com/docs/session-replay.md), [LLM traces](https://posthog.com/docs/ai-engineering.md), or [error tracking](https://posthog.com/docs/error-tracking.md).
 >
-> See our guide on [identifying users](/docs/getting-started/identify-users.md) for how to set this up.
+> See our guide on [identifying users](https://posthog.com/docs/getting-started/identify-users.md) for how to set this up.
 
 ## Capturing events
 
 You can send custom events using `capture`:
 
-PHP
-
 ```php
 PostHog::capture([
   'distinctId' => 'distinct_id_of_the_user',
@@ -51,9 +64,7 @@ PostHog::capture([
 
 ### Setting event properties
 
-Optionally, you can include additional information with the event by including a [properties](/docs/data/events.md#event-properties) object:
-
-PHP
+Optionally, you can include additional information with the event by including a [properties](https://posthog.com/docs/data/events.md#event-properties) object:
 
 ```php
 PostHog::capture([
@@ -70,8 +81,6 @@ PostHog::capture([
 
 If you're aiming for a backend-only implementation of PostHog and won't be capturing events from your frontend, you can send `pageviews` from your backend like so:
 
-PHP
-
 ```php
 PostHog::capture([
   'distinctId' => 'distinct_id_of_the_user',
@@ -84,9 +93,7 @@ PostHog::capture([
 
 ## Person profiles and properties
 
-The PHP SDK captures identified events by default. These create [person profiles](/docs/data/persons.md). To set [person properties](/docs/product-analytics/person-properties.md), call `identify` with the user's distinct ID and properties:
-
-PHP
+The PHP SDK captures identified events by default. These create [person profiles](https://posthog.com/docs/data/persons.md). To set [person properties](https://posthog.com/docs/product-analytics/person-properties.md), call `identify` with the user's distinct ID and properties:
 
 ```php
 PostHog::identify([
@@ -100,8 +107,6 @@ PostHog::identify([
 
 You can also include person properties when capturing an event:
 
-PHP
-
 ```php
 PostHog::capture([
     'distinctId' => 'distinct_id',
@@ -117,11 +122,9 @@ PostHog::capture([
 ]);
 ```
 
-For more details on the difference between `$set` and `$set_once`, see our [person properties docs](/docs/product-analytics/person-properties.md#what-is-the-difference-between-set-and-set_once).
-
-To capture [anonymous events](/docs/data/anonymous-vs-identified-events.md) without person profiles, set the event's `$process_person_profile` property to `false`:
+For more details on the difference between `$set` and `$set_once`, see our [person properties docs](https://posthog.com/docs/product-analytics/person-properties.md#what-is-the-difference-between-set-and-set_once).
 
-PHP
+To capture [anonymous events](https://posthog.com/docs/data/anonymous-vs-identified-events.md) without person profiles, set the event's `$process_person_profile` property to `false`:
 
 ```php
 PostHog::capture([
@@ -139,8 +142,6 @@ Sometimes, you want to assign multiple distinct IDs to a single user. This is he
 
 In this case, you can use `alias` to assign another distinct ID to the same user.
 
-PHP
-
 ```php
 PostHog::alias([
   'distinctId' => 'distinct_id',
@@ -148,11 +149,11 @@ PostHog::alias([
 ]);
 ```
 
-We strongly recommend reading our docs on [alias](/docs/product-analytics/identify.md#alias-assigning-multiple-distinct-ids-to-the-same-user) to best understand how to correctly use this method.
+We strongly recommend reading our docs on [alias](https://posthog.com/docs/product-analytics/identify.md#alias-assigning-multiple-distinct-ids-to-the-same-user) to best understand how to correctly use this method.
 
 ## Feature flags
 
-PostHog's [feature flags](/docs/feature-flags.md) enable you to safely deploy and roll back new features as well as target specific users and groups with them.
+PostHog's [feature flags](https://posthog.com/docs/feature-flags.md) enable you to safely deploy and roll back new features as well as target specific users and groups with them.
 
 There are two steps to implement feature flags in PHP:
 
@@ -162,8 +163,6 @@ Call `PostHog::evaluateFlags()` once for the user, then read values from the ret
 
 #### Boolean feature flags
 
-PHP
-
 ```php
 $flags = PostHog::evaluateFlags('distinct_id_of_your_user');
 
@@ -176,8 +175,6 @@ if ($flags->isEnabled('flag-key')) {
 
 #### Multivariate feature flags
 
-PHP
-
 ```php
 $flags = PostHog::evaluateFlags('distinct_id_of_your_user');
 
@@ -198,9 +195,9 @@ You can also call `$flags->getKeys()` to list the evaluated flag keys, or `$flag
 
 ### Step 2: Include feature flag information when capturing events
 
-If you want use your feature flag to breakdown or filter events in your [insights](/docs/product-analytics/insights.md), you'll need to include feature flag information in those events. This ensures that the feature flag value is attributed correctly to the event.
+If you want use your feature flag to breakdown or filter events in your [insights](https://posthog.com/docs/product-analytics/insights.md), you'll need to include feature flag information in those events. This ensures that the feature flag value is attributed correctly to the event.
 
-> **Note:** This step is only required for events captured using our server-side SDKs or [API](/docs/api.md).
+> **Note:** This step is only required for events captured using our server-side SDKs or [API](https://posthog.com/docs/api.md).
 
 There are two methods you can use to include feature flag information in your events:
 
@@ -208,8 +205,6 @@ There are two methods you can use to include feature flag information in your ev
 
 Pass the same `flags` object that you used for branching. This attaches the exact flag values from that evaluation and doesn't make another `/flags` request.
 
-PHP
-
 ```php
 $flags = PostHog::evaluateFlags('distinct_id_of_your_user');
 
@@ -228,8 +223,6 @@ By default, this attaches every flag in the snapshot using `$feature/<flag-key>`
 
 To reduce event property bloat, pass a filtered snapshot:
 
-PHP
-
 ```php
 // Attach only flags accessed with isEnabled() or getFlag() before this call
 PostHog::capture([
@@ -252,8 +245,6 @@ PostHog::capture([
 
 In the event properties, include `$feature/feature_flag_name: variant_key`:
 
-PHP
-
 ```php
 PostHog::capture([
     'distinctId' => 'distinct_id_of_your_user',
@@ -269,8 +260,6 @@ PostHog::capture([
 
 By default, `evaluateFlags()` evaluates every flag for the user. If you only need a few flags, pass `flagKeys` to request only those flags:
 
-PHP
-
 ```php
 $flags = PostHog::evaluateFlags(
     distinctId: 'distinct_id_of_your_user',
@@ -282,8 +271,6 @@ $flags = PostHog::evaluateFlags(
 
 `evaluateFlags()` also accepts optional parameters for local evaluation and GeoIP behavior:
 
-PHP
-
 ```php
 $flags = PostHog::evaluateFlags(
     distinctId: 'distinct_id_of_your_user',
@@ -298,7 +285,7 @@ $flags = PostHog::evaluateFlags(
 
 ### Sending `$feature_flag_called` events
 
-Capturing `$feature_flag_called` events enables PostHog to know when a flag was accessed by a user and provide [analytics and insights](/docs/product-analytics/insights.md) on the flag. With `evaluateFlags()`, the SDK sends this event when you call `$flags->isEnabled()` or `$flags->getFlag()` for a flag.
+Capturing `$feature_flag_called` events enables PostHog to know when a flag was accessed by a user and provide [analytics and insights](https://posthog.com/docs/product-analytics/insights.md) on the flag. With `evaluateFlags()`, the SDK sends this event when you call `$flags->isEnabled()` or `$flags->getFlag()` for a flag.
 
 The SDK deduplicates these events per `(flag key, distinct_id)` in a local cache. If you reinitialize the PostHog client, the cache resets and `$feature_flag_called` events may be sent again. PostHog handles duplicates, so duplicate `$feature_flag_called` events don't affect your analytics.
 
@@ -306,14 +293,12 @@ The SDK deduplicates these events per `(flag key, distinct_id)` in a local cache
 
 ### Advanced: Overriding server properties
 
-Sometimes, you may want to evaluate feature flags using [person properties](/docs/product-analytics/person-properties.md), [groups](/docs/product-analytics/group-analytics.md), or group properties that haven't been ingested yet, or were set incorrectly earlier.
+Sometimes, you may want to evaluate feature flags using [person properties](https://posthog.com/docs/product-analytics/person-properties.md), [groups](https://posthog.com/docs/product-analytics/group-analytics.md), or group properties that haven't been ingested yet, or were set incorrectly earlier.
 
 You can provide properties to evaluate the flag with by using the `person properties`, `groups`, and `group properties` arguments. PostHog will then use these values to evaluate the flag, instead of any properties currently stored on your PostHog server.
 
 For example:
 
-PHP
-
 ```php
 $flags = PostHog::evaluateFlags(
     distinctId: 'distinct_id_of_the_user',
@@ -364,8 +349,6 @@ Simply include any of these properties in the `person_properties` parameter alon
 
 You can configure the `feature_flag_request_timeout_ms` parameter when initializing your PostHog client to set a flag request timeout. This helps prevent your code from being blocked if PostHog's servers are too slow to respond. By default, this is set to 3 seconds.
 
-PHP
-
 ```php
 PostHog::init("<ph_project_token>",
     [
@@ -381,25 +364,21 @@ Evaluating feature flags requires making a request to PostHog for each flag. How
 
 It is best practice to use local evaluation flags when possible, since this enables you to resolve flags faster and with fewer API calls.
 
-To load feature flag definitions for local evaluation, initialize the SDK with your feature flags secure API key as `personalAPIKey`:
-
-PHP
+To load feature flag definitions for local evaluation, initialize the SDK with your secret API key as `personalAPIKey`:
 
 ```php
 PostHog::init(
     '<ph_project_token>',
     ['host' => 'https://us.i.posthog.com'],
-    personalAPIKey: 'your feature flags secure API key'
+    personalAPIKey: 'your secret API key'
 );
 ```
 
-For details on how to implement local evaluation, see our [local evaluation guide](/docs/feature-flags/local-evaluation.md). For distributed or stateless PHP applications, use `flag_definition_cache_provider` to share flag definitions across workers or requests. See [local evaluation in distributed environments](/docs/feature-flags/local-evaluation/distributed-environments?tab=PHP.md).
+For details on how to implement local evaluation, see our [local evaluation guide](https://posthog.com/docs/feature-flags/local-evaluation.md). For distributed or stateless PHP applications, use `flag_definition_cache_provider` to share flag definitions across workers or requests. See [local evaluation in distributed environments](https://posthog.com/docs/feature-flags/local-evaluation/distributed-environments?tab=PHP.md).
 
 ### Experiments (A/B tests)
 
-Since [experiments](/docs/experiments/start-here.md) use feature flags, the code for running an experiment is very similar to the feature flags code:
-
-PHP
+Since [experiments](https://posthog.com/docs/experiments/start-here.md) use feature flags, the code for running an experiment is very similar to the feature flags code:
 
 ```php
 $flags = PostHog::evaluateFlags('user_distinct_id');
@@ -410,18 +389,16 @@ if ($variant === 'variant-name') {
 }
 ```
 
-It's also possible to [run experiments without using feature flags](/docs/experiments/running-experiments-without-feature-flags.md).
+It's also possible to [run experiments without using feature flags](https://posthog.com/docs/experiments/running-experiments-without-feature-flags.md).
 
 ### Group analytics
 
-Group analytics allows you to associate an event with a group (e.g. teams, organizations, etc.). This feature requires version `2.1.0` or above of the PHP SDK. Read the [group analytics guide](/docs/product-analytics/group-analytics.md) for more information.
+Group analytics allows you to associate an event with a group (e.g. teams, organizations, etc.). This feature requires version `2.1.0` or above of the PHP SDK. Read the [group analytics guide](https://posthog.com/docs/product-analytics/group-analytics.md) for more information.
 
-> **Note:** This is a paid feature and is not available on the open-source or free cloud plan. Learn more on the [pricing page](/pricing.md).
+> **Note:** This is a paid feature and is not available on the open-source or free cloud plan. Learn more on the [pricing page](https://posthog.com/pricing.md).
 
 To create a group or update its properties, use `groupIdentify`:
 
-PHP
-
 ```php
 PostHog::groupIdentify([
     'groupType' => 'company',
@@ -442,8 +419,6 @@ If the optional `distinctId` parameter is not provided in the group identify cal
 
 Once a group is created, you can use the `capture` method and pass in the `groups` parameter to capture an event with group analytics.
 
-PHP
-
 ```php
 PostHog::capture([
     'distinctId' => 'user_distinct_id',
@@ -456,8 +431,6 @@ PostHog::capture([
 
 Use request context to apply a distinct ID, session ID, and common properties to all captures inside a callback. This is useful when connecting frontend activity to backend events, session replay, and error tracking.
 
-PHP
-
 ```php
 PostHog::withContext([
     'distinctId' => 'user_distinct_id',
@@ -472,12 +445,10 @@ PostHog::withContext([
 });
 ```
 
-You can extract PostHog context from frontend tracing headers with `contextFromHeaders()`. If you're using [PostHog JS](/docs/libraries/js.md) on the frontend, configure [`tracing_headers`](/docs/libraries/js/config.md#tracing-headers) for your PHP backend hostname so browser requests include the session and distinct ID headers.
+You can extract PostHog context from frontend tracing headers with `contextFromHeaders()`. If you're using [PostHog JS](https://posthog.com/docs/libraries/js.md) on the frontend, configure [`tracing_headers`](https://posthog.com/docs/libraries/js/config.md#tracing-headers) for your PHP backend hostname so browser requests include the session and distinct ID headers.
 
 Then read the incoming headers on the server:
 
-PHP
-
 ```php
 $context = PostHog::contextFromHeaders($_SERVER);
 
@@ -498,8 +469,6 @@ The PHP SDK supports both manual exception capture and opt-in automatic error tr
 
 To automatically capture uncaught exceptions, PHP errors, and fatal shutdown errors, enable `error_tracking` when initializing the client:
 
-PHP
-
 ```php
 PostHog::init(
     '<ph_project_token>',
@@ -514,14 +483,12 @@ PostHog::init(
 
 You can also call `PostHog::captureException()` directly for manual capture. When source files are readable at runtime, PostHog includes surrounding source lines for in-app stack frames automatically.
 
-For the full setup guide, including `context_provider`, excluded exceptions, and verification steps, see the [PHP error tracking installation docs](/docs/error-tracking/installation/php.md).
+For the full setup guide, including `context_provider`, excluded exceptions, and verification steps, see the [PHP error tracking installation docs](https://posthog.com/docs/error-tracking/installation/php.md).
 
 ## Config options
 
 When calling `PostHog::init`, there are various configuration options you can set apart from the host. Pass them into your client initialisation like so:
 
-PHP
-
 ```php
 PostHog::init(
     '<ph_project_token>',
@@ -543,7 +510,7 @@ All possible options below:
 | `timeout` **Type:** Integer **Default:** `10000` | Request timeout in milliseconds. |
 | `verify_batch_events_request` **Type:** Boolean **Default:** `true` | Whether to verify successful delivery of batch events (true, synchronous) or fire and forget (false, asynchronous) with the `lib_curl` consumer. |
 | `feature_flag_request_timeout_ms` **Type:** Integer **Default:** `3000` | Request timeout for feature flags in milliseconds. |
-| `flag_definition_cache_provider` **Type:** `PostHog\FlagDefinitionCacheProvider` **Default:** `null` | Provider for distributed local-evaluation flag definition caching. See [local evaluation in distributed environments](/docs/feature-flags/local-evaluation/distributed-environments?tab=PHP.md). |
+| `flag_definition_cache_provider` **Type:** `PostHog\FlagDefinitionCacheProvider` **Default:** `null` | Provider for distributed local-evaluation flag definition caching. See [local evaluation in distributed environments](https://posthog.com/docs/feature-flags/local-evaluation/distributed-environments?tab=PHP.md). |
 | `maximum_backoff_duration` **Type:** Integer **Default:** `10000` | Request retry backoff. Retries stop after this duration is hit. |
 | `consumer` **Type:** String **Default:** `lib_curl` | One of `socket`, `file`, `lib_curl`, `fork_curl`, and `noop`. Determines what transport option to use for analytics capture. |
 | `debug` **Type:** Boolean **Default:** `false` | Output debug logs or not. |
@@ -552,7 +519,7 @@ All possible options below:
 | `compress_request` **Type:** Boolean/String **Default:** `false` | Whether to gzip batch request payloads. |
 | `error_handler` **Type:** Callable **Default:** `null` | Callback invoked for SDK transport errors. |
 | `filename` **Type:** String **Default:** `sys_get_temp_dir() . '/posthog.log'` | File path used when `consumer` is set to `file`. |
-| `error_tracking` **Type:** Array **Default:** `[]` | Enables automatic error tracking. See the options below or the [PHP error tracking setup guide](/docs/error-tracking/installation/php.md). |
+| `error_tracking` **Type:** Array **Default:** `[]` | Enables automatic error tracking. See the options below or the [PHP error tracking setup guide](https://posthog.com/docs/error-tracking/installation/php.md). |
 
 ### Error tracking options
 
@@ -568,16 +535,12 @@ All possible options below:
 
 Call `PostHog::flush()` to send queued events without closing resources. When a script or long-running worker stops, call `PostHog::shutdown()` instead; it flushes queued events and releases resources held by providers such as `flag_definition_cache_provider`.
 
-PHP
-
 ```php
 PostHog::shutdown();
 ```
 
 ## Debug mode
 
-PHP
-
 ```php
 PostHog::init(
     '<ph_project_token>',
@@ -591,11 +554,3 @@ PostHog::init(
 ## Thank you
 
 This library is largely based on the `analytics-php` package.
-
-### Still have questions?
-
-Ask PostHog AI
-
-### Was this page useful?
-
-HelpfulCould be better

package/dist/global-skills/instrument-product-analytics/references/posthog-python.md

@@ -2,7 +2,7 @@
 
 # PostHog Python SDK
 
-**SDK Version:** 7.60.0
+**SDK Version:** 7.73.1
 
 Integrate PostHog into any python application.
 
@@ -716,11 +716,11 @@ posthog.load_feature_flags()
 
 **Release Tag:** public
 
-Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.
+Attempt immediate delivery of queued events and ended spans, keeping the client reusable.  For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans.  Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.
 
 ### Parameters
 
-- **`timeout_seconds?`** (`float`) - Maximum seconds to wait for the queue to flush.         Defaults to 10 seconds. Pass ``None`` to wait indefinitely.         Queued spans are sent at the same time, within the same
+- **`timeout_seconds?`** (`float`) - Seconds to wait for event queues to drain, shared         across event lanes. Defaults to 10 seconds. Pass ``None`` to wait         without a time limit; this does not guarantee successful delivery.         Queued spans flush concurrently. The span exporter waits up to         this many seconds for an in-flight flush, then uses a fresh drain         budget once it acquires the lock. If the lock wait times out, the         in-flight flush is left to finish. At least one span request is         attempted after acquiring the lock, even with no budget left;         retriable failures are retried after backoff while budget remains,         with one last attempt at the deadline. Each span request is         bounded by the client's ``timeout`` in         seconds, and the last request is not cut short. This is therefore         not a strict wall-clock limit for the whole call. With ``None``,         a retriable span failure is left for a later flush rather than         retried within this call.
 
 ### Returns
 
@@ -729,8 +729,9 @@ Force a flush from the internal queue to the server. Do not use directly, call `
 ### Examples
 
 ```python
-posthog.capture('event_name')
-posthog.flush()  # Ensures the event is sent immediately
+posthog.capture('event_name', distinct_id='user_id')
+# Before a serverless invocation returns; keep the shared client open.
+posthog.flush(timeout_seconds=10)
 ```
 
 ---
@@ -791,7 +792,7 @@ posthog.join()
 
 **Release Tag:** public
 
-Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.  Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.
+Attempt final delivery and permanently shut down the client.  Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed.  Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.
 
 ### Returns
 
@@ -1242,7 +1243,7 @@ Capture exception is idempotent - if it is called twice with the same exception
 
 ### Parameters
 
-- **`exception`** (`BaseException`) - The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`     **kwargs: Optional capture arguments including distinct_id, properties,         timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.
+- **`exception`** (`BaseException`) - The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`     **kwargs: Optional capture arguments including distinct_id, properties,         timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.         Overriding reserved exception properties through ``properties`` is         deprecated and will stop working in the next major version.
 - **`kwargs?`** (`Unpack[OptionalCaptureArgs]`)
 
 ### Returns
@@ -1558,11 +1559,11 @@ load_feature_flags()
 
 **Release Tag:** public
 
-Tell the client to flush all queued events.
+Attempt immediate delivery of queued events and ended spans, keeping the global client reusable.  Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans.  Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.
 
 ### Parameters
 
-- **`timeout_seconds?`** (`float`) - Maximum seconds to wait for the queue to flush.         Defaults to 10 seconds. Pass ``None`` to wait indefinitely.
+- **`timeout_seconds?`** (`float`) - Seconds to wait for event queues to drain, shared across         event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a         time limit; this does not guarantee successful delivery. Queued spans         flush concurrently, waiting up to this many seconds for an in-flight         flush before starting a fresh drain budget. A lock wait timeout leaves         the in-flight flush to finish. At least one span request is attempted         after acquiring the lock, even with no budget left; retriable failures         are retried after backoff while budget remains, with one last attempt         at the deadline. The last span request is not cut short and is bounded         by the client's ``timeout`` in seconds,         so this is not a strict wall-clock limit for the whole call. With         ``None``, a retriable span failure is left for a later flush rather than         retried within this call.
 
 ### Returns
 
@@ -1571,8 +1572,10 @@ Tell the client to flush all queued events.
 ### Examples
 
 ```python
-from posthog import flush
-flush()
+import posthog
+posthog.capture('event_name', distinct_id='user_id')
+# Before a serverless invocation returns; keep the global client open.
+posthog.flush(timeout_seconds=10)
 ```
 
 ---
@@ -1600,7 +1603,7 @@ join()
 
 **Release Tag:** public
 
-Flush all messages and cleanly shutdown the client.  This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.
+Attempt final delivery and permanently shut down the global client.  Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown.  This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.
 
 ### Returns