mirror of
https://github.com/BillyOutlast/posthog.com.git
synced 2026-02-04 03:11:21 +01:00
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>
This commit is contained in:
Vincent (Wen Yu) Ge
committed by
GitHub
GitHub
parent
3bbc091322
commit
9c311e34f2
@@ -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"
|
||||
}
|
||||
},
|
||||
...
|
||||
}
|
||||
```
|
||||
@@ -137,8 +137,7 @@ Future<void> main() async {
|
||||
final config = PostHogConfig('<ph_project_api_key>');
|
||||
config.debug = true;
|
||||
config.captureApplicationLifecycleEvents = true;
|
||||
// or EU Host: 'https://eu.i.posthog.com'
|
||||
config.host = 'https://us.i.posthog.com';
|
||||
config.host = '<ph_client_api_host>';
|
||||
await Posthog().setup(config);
|
||||
runApp(MyApp());
|
||||
}
|
||||
|
||||
@@ -20,17 +20,4 @@ posthog = Posthog('<ph_project_api_key>', host='<ph_client_api_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.
|
||||
@@ -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:
|
||||
|
||||
@@ -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('<ph_project_api_key>');
|
||||
config.host = '<ph_client_api_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();
|
||||
```
|
||||
@@ -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: "<ph_project_api_key>", host: "<ph_client_api_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)
|
||||
```
|
||||
@@ -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.
|
||||
|
||||
@@ -667,3 +667,64 @@ posthog.init('<ph_project_api_key>', {
|
||||
### 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('<ph_project_api_key>', {
|
||||
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:
|
||||
|
||||
<ProductScreenshot
|
||||
imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/w_1600,c_limit,q_auto,f_auto/Screenshot_2025_11_04_at_3_32_58_PM_4ed3c4300f.png"
|
||||
imageDark="https://res.cloudinary.com/dmukukwp6/image/upload/w_1600,c_limit,q_auto,f_auto/Screenshot_2025_11_04_at_3_32_58_PM_4ed3c4300f.png"
|
||||
alt="View logs in the developer console"
|
||||
/>
|
||||
|
||||
<Caption>Chrome DevTools console showing PostHog logs</Caption>
|
||||
|
||||
When you reach out to support, please include debug logs from the developer console to help us diagnose the issue faster.
|
||||
@@ -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.
|
||||
|
||||
@@ -143,7 +143,7 @@ When calling `PostHog::init`, there are various configuration options you can se
|
||||
|
||||
```php
|
||||
PostHog::init(
|
||||
'PROJECT_API_KEY',
|
||||
'<ph_project_api_key>',
|
||||
array(
|
||||
'host' => '<ph_client_api_host>',
|
||||
'debug' => true,
|
||||
@@ -166,7 +166,17 @@ All possible options below:
|
||||
| `consumer`<br/><br/>**Type:** String<br/>**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`<br/><br/>**Type:** Boolean<br/>**Default:** `false` | Output debug logs or not |
|
||||
|
||||
## Debug mode
|
||||
|
||||
```php
|
||||
PostHog::init(
|
||||
'<ph_project_api_key>',
|
||||
array(
|
||||
'host' => '<ph_client_api_host>',
|
||||
'debug' => true, // +
|
||||
),
|
||||
);
|
||||
```
|
||||
|
||||
## Thank you
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
<PostHogProvider
|
||||
apiKey="<ph_project_api_key>"
|
||||
options={{
|
||||
debug: true,
|
||||
host: "<ph_client_api_host>",
|
||||
}}
|
||||
>
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
@@ -25,10 +25,6 @@ import RubyInstall from '../../integrate/_snippets/install-ruby.mdx'
|
||||
|
||||
<RubyInstall />
|
||||
|
||||
### 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.
|
||||
|
||||
Reference in New Issue
Block a user