From 9c311e34f21edb9a02fe1eaccdc6441ed9ac12ff Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" <29069505+gewenyu99@users.noreply.github.com> Date: Tue, 4 Nov 2025 17:22:06 -0500 Subject: [PATCH] Consistent debug section for SDKs where possible (#13503) * Consistent debug section for SDKs where possible * Apply suggestion from @greptile-apps[bot] Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> * Apply suggestion from @greptile-apps[bot] Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> * Apply suggestion from @greptile-apps[bot] Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> * Call it debug mode * Add screenshot --------- Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- .../integrate/_snippets/install-dotnet.mdx | 35 ++++++----- .../integrate/_snippets/install-flutter.mdx | 3 +- .../integrate/_snippets/install-python.mdx | 15 +---- contents/docs/libraries/android/index.mdx | 13 ++++ contents/docs/libraries/flutter/index.mdx | 23 ++++++- contents/docs/libraries/ios/usage.mdx | 24 ++++++++ contents/docs/libraries/js/index.mdx | 19 ------ contents/docs/libraries/js/usage.mdx | 61 +++++++++++++++++++ contents/docs/libraries/node/index.mdx | 17 +++--- contents/docs/libraries/php/index.mdx | 12 +++- contents/docs/libraries/python/index.mdx | 20 +++++- .../docs/libraries/react-native/index.mdx | 22 +++++++ contents/docs/libraries/ruby/index.mdx | 8 +-- 13 files changed, 207 insertions(+), 65 deletions(-) diff --git a/contents/docs/integrate/_snippets/install-dotnet.mdx b/contents/docs/integrate/_snippets/install-dotnet.mdx index 48b1ffaec..a5d055a1b 100644 --- a/contents/docs/integrate/_snippets/install-dotnet.mdx +++ b/contents/docs/integrate/_snippets/install-dotnet.mdx @@ -39,22 +39,6 @@ dotnet user-secrets set "PostHog:PersonalApiKey" "phx_..." You can find your project API key and instance address in the [project settings](https://app.posthog.com/project/settings) page in PostHog. -To see detailed logging, set the log level to `Debug` or `Trace` in `appsettings.json`: - -```json -{ - "DetailedErrors": true, - "Logging": { - "LogLevel": { - "Default": "Information", - "Microsoft.AspNetCore": "Warning", - "PostHog": "Trace" - } - }, - ... -} -``` - ## Working with .NET Feature Management `PostHog.AspNetCore` supports [.NET Feature Management](https://learn.microsoft.com/en-us/azure/azure-app-configuration/feature-management-dotnet-reference). This enables you to use the <feature /> tag helper and the `FeatureGateAttribute` in your ASP.NET Core applications to gate access to certain features using PostHog feature flags. @@ -171,3 +155,22 @@ public static readonly PostHogClient PostHog = new(new PostHogOptions { }); ``` +## Debug mode + +If you're not seeing the expected events being captured, the feature flags being evaluated, or the surveys being shown, you can enable debug mode to see what's happening. + +To see detailed logging, set the log level to `Debug` or `Trace` in `appsettings.json`: + +```json +{ + "DetailedErrors": true, + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft.AspNetCore": "Warning", + "PostHog": "Trace" + } + }, + ... +} +``` \ No newline at end of file diff --git a/contents/docs/integrate/_snippets/install-flutter.mdx b/contents/docs/integrate/_snippets/install-flutter.mdx index 8ca565c4a..e967ffa30 100644 --- a/contents/docs/integrate/_snippets/install-flutter.mdx +++ b/contents/docs/integrate/_snippets/install-flutter.mdx @@ -137,8 +137,7 @@ Future main() async { final config = PostHogConfig(''); config.debug = true; config.captureApplicationLifecycleEvents = true; - // or EU Host: 'https://eu.i.posthog.com' - config.host = 'https://us.i.posthog.com'; + config.host = ''; await Posthog().setup(config); runApp(MyApp()); } diff --git a/contents/docs/integrate/_snippets/install-python.mdx b/contents/docs/integrate/_snippets/install-python.mdx index 330432af5..4685e98b1 100644 --- a/contents/docs/integrate/_snippets/install-python.mdx +++ b/contents/docs/integrate/_snippets/install-python.mdx @@ -20,17 +20,4 @@ posthog = Posthog('', host='') > **Note:** As a rule of thumb, we do not recommend having API keys in plaintext. Setting it as an environment variable is best. -You can find your project API key and instance address in the [project settings](https://app.posthog.com/project/settings) page in PostHog. - -To debug, you can toggle debug mode: - -```python -posthog.debug = True -``` - -To make sure no calls happen during tests, you can disable PostHog, like so: - -```python -if settings.TEST: - posthog.disabled = True -``` +You can find your project API key and instance address in the [project settings](https://app.posthog.com/project/settings) page in PostHog. \ No newline at end of file diff --git a/contents/docs/libraries/android/index.mdx b/contents/docs/libraries/android/index.mdx index d72f9da52..69ad1ba46 100644 --- a/contents/docs/libraries/android/index.mdx +++ b/contents/docs/libraries/android/index.mdx @@ -285,6 +285,19 @@ The PostHog Android SDK will continue to capture events when the device is offli - The queue is flushed when the app is restarted and the device is online. - When you call [`flush()`](#flush) while the device is offline, it aborts early and the events are not flushed. +## Debug mode + +If you're not seeing the expected events being captured, the feature flags being evaluated, or the surveys being shown, you can enable debug mode to see what's happening. + +You can enable debug mode by setting the `debug` option to `true` in the `PostHogAndroidConfig` object. This will enable verbose logs about the inner workings of the SDK. + +```kotlin +val config = PostHogAndroidConfig(apiKey = POSTHOG_API_KEY, host = POSTHOG_HOST).apply { + debug = true + // ... other config options +} +``` + ## All configuration options When creating the PostHog client, there are many options you can set: diff --git a/contents/docs/libraries/flutter/index.mdx b/contents/docs/libraries/flutter/index.mdx index 1af65c458..4a264c1c0 100644 --- a/contents/docs/libraries/flutter/index.mdx +++ b/contents/docs/libraries/flutter/index.mdx @@ -126,7 +126,7 @@ await Posthog().group(groupType: "company", groupKey: "company_id_in_your_db"); - Associate the events for this session with a group AND update the properties of that group -```swift +```dart await Posthog().group( groupType: "company", groupKey: "company_id_in_your_db", @@ -201,4 +201,25 @@ To check if a user is opted out: ```dart await Posthog().isOptedOut(); +``` + +## Debug mode + +If you're not seeing the expected events being captured, the feature flags being evaluated, or the surveys being shown, you can enable debug mode to see what's happening. + +You can enable debug mode during initialization by setting the `debug` option to `true` in the `PostHogConfig` object. A common pattern is to set this to `true` in development environments only using environment variables. + +```dart +final config = PostHogConfig(''); +config.host = ''; +config.debug = true; // + +await Posthog().setup(config); +``` + +This will enable verbose logs about the inner workings of the SDK. + +You can also enable debug by calling the `Posthog().debug()` method in your code. + +```dart +await Posthog().debug(); ``` \ No newline at end of file diff --git a/contents/docs/libraries/ios/usage.mdx b/contents/docs/libraries/ios/usage.mdx index 92f0ea2ae..b16cc8e2c 100644 --- a/contents/docs/libraries/ios/usage.mdx +++ b/contents/docs/libraries/ios/usage.mdx @@ -222,3 +222,27 @@ To set up [session replay](/docs/session-replay/mobile) in your project, all you ## Surveys [Surveys](/docs/surveys) launched with [popover presentation](/docs/surveys/creating-surveys#presentation) are automatically shown to users matching the [display conditions](/docs/surveys/creating-surveys#display-conditions) you set up. + +## Debug mode + +If you're not seeing the expected events being captured, the feature flags being evaluated, or the surveys being shown, you can enable debug mode to see what's happening. + +You can enable debug mode by setting the `debug` option to `true` in the `PostHogConfig` object. A common pattern is to set this to `true` in development environments only for local development. + +```swift +let config = PostHogConfig(apiKey: "", host: "") +config.debug = true +PostHogSDK.shared.setup(config) +``` + +This will enable verbose logs about the inner workings of the SDK. + +You can also toggle debug by calling the `PostHogSDK.shared.debug()` method in your code. + +```swift +// Enable debug mode +PostHogSDK.shared.debug(true) + +// Disable debug mode +PostHogSDK.shared.debug(false) +``` \ No newline at end of file diff --git a/contents/docs/libraries/js/index.mdx b/contents/docs/libraries/js/index.mdx index 2d449a2a8..7c302cd72 100644 --- a/contents/docs/libraries/js/index.mdx +++ b/contents/docs/libraries/js/index.mdx @@ -86,25 +86,6 @@ posthog.project2.capture('other_event') > **Note:** You'll probably want to disable autocapture (and some other events) to avoid them from being sent to both instances. Check all of our [config options](/docs/libraries/js/config) to better understand that. -## Debugging - -To see all the data that is being sent to PostHog, you can run `posthog.debug()` in your dev console or set the `debug` option to `true` in the `init` call. You can also enable debug mode by appending this query to the URL `?__posthog_debug=true` (i.e., https://posthog.com/?__posthog_debug=true). - -### Exposing the `posthog` global object in web apps that don't have `window.posthog` - -> This has been tested in Chrome and Firefox. Safari doesn't have this feature, but other Chromium and Gecko/Firefox browsers do. - -Sometimes you may want to test PostHog in the browser by using `posthog.capture()` or some other method. Although some sites expose `window.posthog`, most modern web app (React, Vue, etc.) don't. - -To expose PostHog in the browser: - -1. Enable debug mode by setting `debug: true` in your config -2. In the browser console, search for `[PostHog.js] Starting in debug mode` -3. Expand the object -4. Right-click on `this` and pick "Store as global variable" - -You can then access `posthog` as `temp0` in Firefox and `temp1` in Chrome. You can then do stuff like `temp1.capture('test event')`. - ## Development For instructions on how to run `posthog-js` locally and setup your development environment, please checkout the README on the [posthog-js](https://github.com/PostHog/posthog-js#README) repository. diff --git a/contents/docs/libraries/js/usage.mdx b/contents/docs/libraries/js/usage.mdx index 0fb1e0c7d..8a5501692 100644 --- a/contents/docs/libraries/js/usage.mdx +++ b/contents/docs/libraries/js/usage.mdx @@ -667,3 +667,64 @@ posthog.init('', { ### Removing already ingested events Deleting already ingested events is complicated, but you can add user agents to the [internal and test accounts filter](https://us.posthog.com/settings/project-product-analytics#internal-user-filtering) in your project settings to filter them from your analytics. + +## Debug mode + +If you're not seeing the expected events being captured, the feature flags being evaluated, or the surveys being shown, you can enable debug mode to see what's happening. + +### Enabling debug mode + +You can enable debug mode by setting the `debug` option to `true` in the `init` call. A common pattern is to set this to `true` in development environments only using environment variables. + +```ts +posthog.init('', { + debug: true // Set this to true in development environments only using environment variables +}) +``` + +This will enable verbose logs about the inner workings of the SDK. + +You can also call `posthog.debug()` in your code or in the dev console like Chrome DevTools or Firefox Developer Tools at runtime. + +```ts +posthog.debug() +``` + +If you can't access or update your code, you can enable debug mode on your website by appending this query to the URL `?__posthog_debug=true`. + +You can try this on the PostHog website: + +```url +https://posthog.com/?__posthog_debug=true +``` + +### Exposing the `posthog` global object to the browser console + +> This has been tested in Chrome and Firefox. Safari doesn't have this feature, but other Chromium and Gecko/Firefox browsers do. + +Sometimes, you may want to test PostHog directly in the browser's dev console. This lets you run commands like `posthog.capture('test event')` directly in the console. + +The SDK will expose the `window.posthog` global object to the browser console on some sites, but most modern web app like React and Vue will not. + +To expose PostHog in the browser: + +1. Enable debug mode by setting `debug: true` in your config +2. In the browser console, search for the console log message `[PostHog.js] Starting in debug mode` +3. Expand the logged object +4. Right-click on `this` and pick **Store as global variable** + +You can then access `posthog` as `temp0` in Firefox and `temp1` in Chrome. You can then do stuff like `temp1.capture('test event')` in the console. + +### View logs in the developer console + +After enabling debug mode, you should see logs in the developer console like this: + + + +Chrome DevTools console showing PostHog logs + +When you reach out to support, please include debug logs from the developer console to help us diagnose the issue faster. \ No newline at end of file diff --git a/contents/docs/libraries/node/index.mdx b/contents/docs/libraries/node/index.mdx index 21a68cb8d..43ad93ac2 100644 --- a/contents/docs/libraries/node/index.mdx +++ b/contents/docs/libraries/node/index.mdx @@ -215,7 +215,16 @@ You should call `shutdown` on your program's exit to exit cleanly: await client.shutdown() ``` -## Debugging and exceptions +## Debug mode +If you're not seeing the expected events being captured, the feature flags being evaluated, or the surveys being shown, you can enable debug mode to see what's happening. + +You can enable debug mode by calling the `debug()` method in your code. This will enable verbose logs about the inner workings of the SDK. + +```node +client.debug() +``` + +## Handling errors thrown by the SDK If you are experiencing issues with the SDK it could be a number of things from an incorrectly configured API key, to some other network related issues. @@ -228,12 +237,6 @@ client.on("error", (err) => { }) ``` -Or you can enable debugging to get verbose logs about all the inner workings of the SDK. - -```node -client.debug() -``` - ## Short-lived processes like serverless environments The Node SDK is designed to queue and batch requests in the background to optimize API calls and network time. As serverless environments like AWS Lambda or [Vercel Functions](/docs/libraries/vercel) are short-lived, we provide a few options to ensure all events are captured. diff --git a/contents/docs/libraries/php/index.mdx b/contents/docs/libraries/php/index.mdx index d2a10b5f1..c4aa19a5d 100644 --- a/contents/docs/libraries/php/index.mdx +++ b/contents/docs/libraries/php/index.mdx @@ -143,7 +143,7 @@ When calling `PostHog::init`, there are various configuration options you can se ```php PostHog::init( - 'PROJECT_API_KEY', + '', array( 'host' => '', 'debug' => true, @@ -166,7 +166,17 @@ All possible options below: | `consumer`

**Type:** String
**Default:** `lib_curl` | One of `socket`, `file`, `lib_curl`, and `fork_curl`. Determines what transport option to use for analytics capture. [More details here](https://github.com/PostHog/posthog-php/blob/master/lib/Consumer/File.php) | | `debug`

**Type:** Boolean
**Default:** `false` | Output debug logs or not | +## Debug mode +```php +PostHog::init( + '', + array( + 'host' => '', + 'debug' => true, // + + ), +); +``` ## Thank you diff --git a/contents/docs/libraries/python/index.mdx b/contents/docs/libraries/python/index.mdx index 163a6fc01..33ef9aef6 100644 --- a/contents/docs/libraries/python/index.mdx +++ b/contents/docs/libraries/python/index.mdx @@ -187,6 +187,25 @@ You can also explicitly chose to enable or disable GeoIP for a single capture re posthog.capture('test_event', disable_geoip=True|False) ``` +## Debug mode + +If you're not seeing the expected events being captured, the feature flags being evaluated, or the surveys being shown, you can enable debug mode to see what's happening. + +You can enable debug mode by setting the `debug` option to `True` in the `PostHog` object. This will enable verbose logs about the inner workings of the SDK. + +```python +posthog.debug = True # + +``` + +## Disabling requests during tests + +You can disable requests during tests by setting the `disabled` option to `True` in the `PostHog` object. This means no events will be captured or no requests will be sent to PostHog. + +```python +if settings.TEST: + posthog.disabled = True +``` + ## Historical migrations You can use the Python or Node SDK to run [historical migrations](/docs/migrate) of data into PostHog. To do so, set the `historical_migration` option to `true` when initializing the client. @@ -206,7 +225,6 @@ By default, the library buffers events before sending them to the capture endpoi See our [Django docs](/docs/libraries/django) for how to set up PostHog in Django. Our library includes a [contexts middleware](/docs/libraries/django#django-contexts-middleware) that can automatically capture distinct IDs, session IDs, and other properties you can set up with tags. - ## Alternative name As our open source project [PostHog](https://github.com/PostHog/posthog) shares the same module name, we created a special `posthoganalytics` package, mostly for internal use to avoid module collision. It is the exact same. diff --git a/contents/docs/libraries/react-native/index.mdx b/contents/docs/libraries/react-native/index.mdx index c683609b1..0b14a84ad 100644 --- a/contents/docs/libraries/react-native/index.mdx +++ b/contents/docs/libraries/react-native/index.mdx @@ -332,6 +332,28 @@ To set up surveys, follow the [additional installation instructions for React Na > Note: URL and CSS selector targeting are not supported in React Native. Surveys that rely on these conditions will not appear. +## Debug mode + +If you're not seeing the expected events being captured, the feature flags being evaluated, or the surveys being shown, you can enable debug mode to see what's happening. + +You can enable debug mode by setting the `debug` option to `true` in the `PostHogProvider` options. This will enable verbose logs about the inner workings of the SDK. + +```react-native +", + }} +> +``` + +You can also call the `debug()` method in your code. + +```react-native +posthog.debug() +``` + ## Disabling for local development You may want to disable PostHog when working locally or in a test environment. You can do this by setting the `disable` option to `true` when initializing PostHog. Helpfully this allows you to continue using `usePostHog` and safely calling it without anything actually happening. diff --git a/contents/docs/libraries/ruby/index.mdx b/contents/docs/libraries/ruby/index.mdx index baf8a983f..cee956916 100644 --- a/contents/docs/libraries/ruby/index.mdx +++ b/contents/docs/libraries/ruby/index.mdx @@ -25,10 +25,6 @@ import RubyInstall from '../../integrate/_snippets/install-ruby.mdx' -### Debug logging - -The log level by default is set to WARN. You can change it to DEBUG if you want to debug the client by running `posthog.logger.level = Logger::DEBUG`, where `posthog` is your initialized `PostHog::Client` instance. - ## Capturing events import RubySendEvents from '../../integrate/send-events/_snippets/send-events-ruby.mdx' @@ -181,6 +177,10 @@ The `name` is a special property which is used in the PostHog UI for the name of If the optional `distinct_id` is not provided in the group identify call, it defaults to `${groupType}_${groupKey}` (e.g., `$company_company_id_in_your_db` in the example above). This default behavior will result in each group appearing as a separate person in PostHog. To avoid this, it's often more practical to use a consistent `distinct_id`, such as `group_identifier`. +## Debug mode + +The Ruby SDK debug logs by default. The log level by default is set to `WARN`. You can change it to `DEBUG` if you want to debug the client by running `posthog.logger.level = Logger::DEBUG`, where `posthog` is your initialized `PostHog::Client` instance. + ## Thank you This library is largely based on the `analytics-ruby` package.