This article walks you through how to access and use the Pendo agent debugger to troubleshoot issues with your app, such as guide display issues or configuration errors. You can also use the debugger for testing, for example, if you want to force a guide to appear more than once.
Access the agent debugger
The debugger is accessed differently depending on your implementation:
- If you have Pendo implemented directly on your application through the install script, follow the instructions under Install script access in this article.
- If you have Pendo deployed through the Pendo Launcher browser extension, follow the instructions under Browser extension access in this article.
Install script access
- Go to Settings > Subscription Settings.
- Open the Applications tab.
- Find and open the relevant app from your Applications list.
- In Agent Settings, select Debug in the Staging or Production environment.
- In the Launch Pendo agent debugger window, enter the app URL where you want to open the debugger and select Launch debugger.
Browser extension access
- Right click on the Pendo Launcher chevron icon in the top-right corner of your browser.
- Select Show Agent Debugger from the dropdown menu.
Alerts tab
The Alerts tab provides an overview of the health of your application. You can see if there are any errors or issues with your guides or the installation of the applicaton. Not all issues are actionable, or you might decide not to act on an issue.
- Select View details to see more detailed information. This opens the tab in the debugger that's related to the error or issue. It could be Config, Events, Guides, or Resource Center.
- Select Get help to view documentation relevant to the error or issue.
Config tab
Use the information provided in the Config tab to validate the setup and configuration of your app. It shows information about the Pendo agent configuration, like subscription settings and current visitor information. This is useful for troubleshooting guides and checking the installation. This information helps you to validate that your setup is as you expect it to be.
The Config tab includes the following sections, which you can expand by selecting the plus (+) icon on the far left of the heading row.
Environment
Environment can be set to production or staging. If the guide is in production, it also shows up in staging environments.
Check that you have the right API key. The API Key is specific to your Pendo app. To check that you have the right API key, go to Settings > Subscription Settings, open the Applications tab, and then open the relevant application. The App Details tab is open by default, where you can find your API Key.
If the API key matches and you have a multi-app subscription, open Guides from the left-side menu in Pendo, and find your guide in the App column. Check that it's registered under the app you just verified the API key for.
Visitor and account metadata
There are sections for Visitor metadata and Account metadata. Check the visitor and account metadata that your application is passing into Pendo for the current visitor. Ensure that the metadata values fit within the segment applied to the guide you're testing.
You can also use the debugger to find your current Visitor ID and create a segment that only applies to your Visitor ID. This allows you to test guides in production without anyone else seeing them.
Frames
Check the information about iframes that your application is using. If you have multiple iframes, you can select each one to view information about it.
Configuration
Technical admins can see more information to learn more about the settings configured in the app. For more information about the full configuration, see agent.pendo.io.
Plugins
Use this information to check whether expected functionality is present in your Pendo agent, such as text capture, guide Markdown, and Session Replay.
Advanced
This is for Pendo Support to view and troubleshoot technical information. This section provides the ability to reset built-in functions in the app.
Events tab
Use the Events tab to validate that Pendo is registering Track Events and clicks correctly in real-time. This also provides vital information when first installing Pendo. By default, the tab is empty.
Select Enable event logging to view events in real-time as you test your site. Expand each event to see information about the event, such as Visitor and Account IDs and the Page URL.
The Page URL is the normalized URL that Pendo recognizes from the page you're on. If your guide is set to a specific Page, copy the URL from the debugger, go to Pages in Pendo, and select the Page your guide is set to.
There should be at least one rule for that Page. Select Test Rule to the right of each Page rule. In the Test URL, paste the URL from the debugger. If the URL doesn't match any of the Page rules, then the Page you're on with the debugger loaded doesn't fit the Page you have the guide set to.
For more information about URLs and Page tagging, see URLs for Page tagging.
Guides tab
Use the guides tab to troubleshoot any issues with guides or steps in your guides not displaying. The guides tab consists of the following sections: Throttling, Last seen, Active guides, and Excluded guides.
Throttling
The Throttling section shows whether you have throttling set up, its settings, and your guide order. You can also see the throttling settings and guide order by navigating to Guides > Ordering from the left-side menu in Pendo.
If throttling is on and your guide is set to automatic activation, then the guide won't display until after that throttling time period is fulfilled.
If you don't see the guide at the top of the guide order list and it's set to automatic activation, then the guide won't display until the automatic guides above it have been seen first, in order. For more information, see Guide ordering and throttling.
Last seen
The Guide Last Seen section provides information about guides that your Visitor ID is able to see, including the guide ID, guide step ID, when the guide was last seen, and the status of the guide.
Your Visitor ID is at the bottom of the Last seen section. If your ID is anonymous, it appears in the following format: _PENDO_T_XXXX, where XXXX is a random string.
Note: If your segment is set to Everyone and your Visitor ID is anonymous, ensure that you have turned on Show guide to anonymous visitors in your application settings. After turning this setting on, you must re-save the segment on each guide that you want to display to anonymous visitors.
Active guides
Active guides are all guides available to the current visitor based on Page and segment. If the guide that you expected to load is in the list, the visitor fits the segment of that guide and the URL you’re on matches the Page that the guide is set to.
Select the plus (+) sign next to the guide to view its details. The guide details include the following information:
- Name. The title of the guide.
- ID. The unique identifier for the guide.
- State. The status of your guide, such as whether it’s public, staged, or in draft. For more information about guide statuses, see Create a guide.
- Launch method. How the guide is activated, such through a badge or automatically. For more information about guide activation, see Guide activation options.
- Last updated. The date and time that the guide was last updated.
- Device. The device that the guide is set to launch on.
- Steps seen. The number of steps seen out of the total number of steps. For example, 1 of 2 indicates that one out of two steps in the guide were seen.
- Language. The language of the guide. For example, en-US indicates that the guide was set to American English.
- Shared service version. The version of Pendo guides.
Information about each step in the guide is displayed in its own section below the guide’s details, labeled Step 1, Step 2, and so on. The information available for each step in a guide includes its ID and type, when it was last seen and updated, if and why it was seen, the regex for Page targeting, “Contains” rules, and the target and trigger elements for that step.
Issue: An active guide isn't launching
If you’re not seeing a guide that’s in the Active Guides List, check the Launch method for the guide.
If the Launch Method is auto, indicating that the guide is activated automatically, and Steps seen is more than zero, the guide isn’t displaying for you because guides that are activated automatically are only seen once until they’re dismissed. You can override this for testing by selecting the Launch Guide button above the guide’s details. For more information about automatic guide launching, see Guide activation options.
If the Launch Method is either badge or dom, indicating that the guide is activated through a target element, check the details for the first step in your guide. If the Target element has a red cross (x) next to it with a statement like not found, Pendo couldn’t find the element that the guide is anchored to on the current page. If you can see the element on the page, try retagging it, which you can do in one of the following ways:
- Open the Visual Design Studio and retarget the element from there.
- If you’re comfortable with CSS and HTML, find the element in the DOM and verify that it fits the CSS selector.
- If you’re comfortable with the Inspect tool in Chrome, use the function
pendo.Sizzle(‘CSSselector’)in the console to find out whether the CSS selector fits any elements on the page. If it fits multiple elements, Pendo attaches the guide to the first element in the DOM.
If you’re still experiencing launch issues, check the following:
- Whether there are any issues with the individual steps in your guide.
- The order and throttling of your guides.
- The page settings in the Config tab. Check that the URL listed in Frame > Frame href matches what you expect to see.
Issue: A step in the guide isn't appearing
If the guide starts as expected, but one of the steps doesn’t appear, restart the guide and advance through it until you reach the step that comes before the step that doesn’t show up. Then, look at the guide’s details in the debugger and the details for the next step. Check that the element and the page settings match where you are for the next step in the guide. If they don’t match, the debugger displays a red cross (x) with a short message next to the relevant rows in the step’s details.
Excluded guides
Excluded guides are all the guides that aren’t eligible for the current visitor. Each excluded guide in the list includes the following information:
- A hyperlinked unique identifier to the guide.
- A reason for exclusion. For example, the current visitor might not fit the segment or the current URL might not match the location for a guide’s step.
Resource Center tab
Use the Resource Center tab to monitor and troubleshoot module activity, for example, guides not displaying in any of the modules.
The first section is the Home View, which refers to the first screen of the Resource Center. Each of the other sections corresponds to a module inside your Resource Center.
To troubleshoot guide display issues in the Resource Center, first identify the Onboarding or Guide List module in the Resource Center tab of the debugger.
- Verify whether the Has Content setting is set to No. This means that the module has no guides eligible for view. Check that the guide is listed under the Children header.
- If the guide is in the list, and it says it's in the payload, check that the segment applied to the module applies to the visitor metadata in the Config tab.
- If the guide isn't in the list, go to your Resource Center in Pendo, and check that the guide is in that module, and that it's been pushed to the appropriate environment, either Staging or Production.
Further troubleshooting
If you need help with additional troubleshooting, you can contact technical support. For more information, see Get help with Pendo from Technical Support.