Inspector Debugger

The Inspector Debugger is a real-time event stream viewer that lets you validate your tracking implementation as you develop, without waiting for events to flow through your analytics pipeline. See events as they happen, inspect their properties, and catch issues before they reach production.

When to use the Inspector Debugger

Inspector debugger is one of three views in Inspector. The other two are the the Issues view and the Events view.

The Inspector debugger is particularly useful when you need to:

• During active development - Validate tracking as you build new features, seeing events appear instantly as you interact with your application without waiting for data to flow through your analytics pipeline.
• Testing in development and staging - For QA teams and data designers to run through QA flows and verify all expected events are firing with correct properties before releasing to production.
• Understanding which events are triggered where - To see which events are triggered in which parts of the application, in which order and which properties are attached to them.

What is the Inspector Debugger?

The Inspector Debugger is a live event stream view within Avo Inspector that displays events as they’re sent from your application. It provides:

Real-time event stream

See all events flowing through Inspector in real-time, organized chronologically with:

• Event name - The name of each event as it was sent
• Validation status - Whether the event is valid according to the tracking plan on the branch that you are currently on or not
• Time - Exact timestamp when the event was sent by the application
• Environment - The environment the event was sent from (currently Development and Staging are supported)
• Source - Which platform or application sent the event (e.g., Desktop, iOS, Android, Web)
• Stream ID - A unique identifier for each user stream session, color-coded for easy visual tracking

Event details and validation

Click any event to see:

• Complete property list - All properties sent with the event, including their types and values (if property value validation is enabled and you have decrypted the values)
• Tracking plan validation - Details on the validation status, with immediate feedback on issue types like unexpected properties, type mismatches, or missing required properties
• Event metadata - Source, version, stream session information, and timestamps
• Link to tracking plan - Quick access to view the event definition in your tracking plan

Matching events and variants

In some cases, an incoming event could match multiple events or variants in your tracking plan. This happens when:

• Your tracking plan uses event variants - Multiple variants of the same event exist with different property requirements
• Your tracking plan uses event name mapping - Different events in the tracking plan are mapped to the same event name

When multiple matches are possible, Avo automatically picks the most likely event, name-mapped event, or variant from the tracking plan to validate against. However, you can manually select a different match from the Validating as dropdown to validate against another event or variant from your tracking plan.

In this example, an event named MSG_SENT has two possible matches in the tracking plan. The dropdown shows the direct matches, and you can select a different variant to see how the event validates against it.

This is useful for verifying that events are being sent with the correct properties for specific variants or mapped events.

How Avo picks the most likely match

When an event matches multiple variants in the tracking plan, Avo selects the best match using a tiered scoring system. Variants are compared in priority order, only moving to the next tier if there’s a tie:

1. Value validation failures - Count how many properties have values that don’t match what this variant expected. Fewer failures = better match.
2. Missing expected properties - Count properties the tracking plan expects but the event doesn’t have. Fewer missing = better match.
3. Unexpected properties - Count properties the event has that aren’t defined in the tracking plan for this variant. Fewer unexpected = better match.
4. Type mismatches - Count properties where the type is wrong (e.g., sent string but expected number). Fewer mismatches = better match.
5. Specific vs default (tiebreaker) - If all else is equal, prefer the specific variant over the default event.

How to use the Inspector Debugger

Accessing the debugger

1. Navigate to Inspector in the left sidebar of your Avo workspace and click on Debugger in the Inspector submenu
2. The debugger will show live events from all sources by default if you are an admin, editor or a viewer that has already activated an Implementer seat.

If you are not an admin, editor or a viewer that has already activated an Implementer seat, you will see a message telling you what you need to do to get access:

• If you’re a viewer and Implementer seats are pre-purchased - You’ll be prompted to activate an Implementer seat to start debugging
• If you’re a viewer and Implementer seats can be added - You’ll be prompted to activate an Implementer seat to start debugging (this will add to your monthly active Implementer seats count)
• If you’re a viewer and no Implementer seats are available - You’ll see a message prompting you to speak to an admin to get access to Implementer slots
• If your workspace is on an older pricing plan - You’ll see a message prompting you to reach out to an admin to renew or upgrade your plan

Filtering events

Use the filters at the top of the debugger to focus your view:

• Environment filter - Filter by development or staging environments
• Source filter - Show events from specific platforms (iOS, Android, Web, etc.)
• Stream session filter (coming soon) - Filter events to a specific user stream session
• Search - Search for specific event names

To find your events in the debugger while debugging:

1. Filter down on the environment and source that you are triggering events from
2. (Coming soon) Look at the stream ID column to identify which stream is sending events that match the ones you are triggering from your application, based on timing and event names and filter down to that stream session

Controlling the event stream

The debugger provides controls for managing the live stream:

• Pause - Pause the event stream to inspect events without new ones appearing. Useful when you need to review a specific event in detail.
• Resume - Resume the live stream to continue receiving events
• Reset - Clear all events from the current view to start fresh. Useful when you are finding your stream session or want to start fresh.

Property value validation

The Inspector Debugger supports property value validation, allowing you to see the actual values being sent with your events and verify they match your expected data. This is useful for catching property value issues where values that don’t match the property constraints defined in Avo, such as allowed values and regex patterns for string properties, min and max values for numerical properties, and required or unexpected keys in object properties.

Property values are encrypted end-to-end for privacy and security. You can always see if there is an issue related to the value but to see the actual values you need to decrypt them using your private key.

Setting up property value validation

Property value validation is enabled when the Property value validation setting is enabled in your workspace setting and you are using a supported SDK or integration version. You will always see validation issues (such as values not matching allowed values or regex patterns), but the actual property values will appear as encrypted. To see the actual values that are causing issues, you need to generate and configure encryption keys.

For existing Inspector installations

If you already have Inspector set up and want to enable property value validation:

1. Enable value validation in settings - Go to Inspector settings in your Avo workspace and enable property value validation
2. Update to a supported SDK or integration - Update to the latest version of a supported SDK or integration that includes property value validation
3. (Optional) Generate encryption keys - To see the actual property values (not just the validation issues), generate a public/private key pair using the Avo CLI and configure your SDK with the public key. See How encryption works for details.

For new Inspector installations

If you’re setting up Inspector for the first time:

1. Enable property value validation in settings - Go to Inspector settings in your Avo workspace and enable property value validation
2. Install the SDK or connect an integration - Follow the Inspector installation overview to set up Inspector. Property value validation is included by default in the latest versions of supported SDKs and integrations.
3. (Optional) Generate encryption keys - To see the actual property values (not just the validation issues), generate a public/private key pair using the Avo CLI and configure your SDK with the public key. See How encryption works for details.

How encryption works

Property values are only sent to Avo if you provide a public encryption key to encrypt the values:

• Avo never stores actual values - Only encrypted values are stored on Avo’s servers
• Public/private key encryption - You generate a key pair using the Avo CLI. Avo uses the public key to encrypt values, and only you can decrypt them with your private key
• Avo cannot decrypt your data - The public key can only be used for encryption, not decryption

To generate a public/private key pair, you can run the following command in your terminal:

node -e "const { createECDH } = require('crypto'); const ecdh = createECDH('prime256v1'); ecdh.generateKeys(); console.log('Private Key:', ecdh.getPrivateKey('hex')); console.log('Public Key:', ecdh.getPublicKey('hex', 'compressed'));"

Decrypting values in the debugger

When viewing events in the Inspector Debugger, property values will show as “Encrypted value” by default. You will always be able to see if there is an issue related to the value, but to view the actual values:

1. Click the Encrypted button in the debugger header
2. Enter your 64-character hex private key in the dialog
3. Optionally save the key using a password manager with a browser extension (if it’s not already saved) or your browser’s built-in password manager to avoid having to enter it every time
4. Click Decrypt to reveal the actual property values

Once decrypted, you can see the actual values sent with each event and identify issues like incorrect data or unexpected values.

Supported SDKs and integrations

Property value validation is currently supported on:

• Inspector Web SDK (v1.5.0+)
• Segment integration

Support for other platforms is coming soon. Reach out to support if you need property value validation for other platforms.

Troubleshooting

Not seeing events in the debugger

If events aren’t appearing in the debugger:

1. Verify Inspector is installed - Check that you’ve installed Inspector for your platform
2. Check your filters - Make sure environment, source and event name filters aren’t excluding your events
3. Check your API key - Verify you’re using the correct Avo API key in your Inspector configuration

Events appear but have many issues

If you’re seeing unexpected validation issues on events you might be on the wrong branch.

1. Check your branch - Verify you’re on the correct branch that you are expecting to see events from. Switch branches in the top of the left sidebar of your Avo workspace.
2. Check your tracking plan - Verify your tracking plan definitions match the event shapes that you are seeing in the debugger
3. Check the matched variant - If you’re using event variants or name mapping, verify that the debugger matched the correct variant. You can select a different variant from the “Validating as” dropdown to see how your event validates against other options.

What’s next?

• Learn about the Issues view to review and manage tracking plan violations
• Learn about finding and fixing issues in Inspector
• Learn about issue types in Inspector