Guide to Debugging RudderStack Event Streams

You are at a point where you have successfully sent an event through RudderStack and you can see it in your destination. Sometimes things may not go perfectly. Keep reading if you would like some tips on how to identify and debug some common issues. If everything worked great, feel free to skip the next section (or you can read on to gain some debugging knowledge).

Debugging RudderStack

There are a couple ways to debug RudderStack when things seem to be not going well.

  • Developer Console: This will be your best friend when beginning to figure out what is going on with your RudderStack implementation. The Developer Console keeps track of everything loaded onto the website and any network call that the website makes. Using  this will be a great starting point in your debugging journey.

Here are some things to investigate:

  1. Is RudderStack Loaded? Start by figuring out if RudderStack is loaded onto your website properly. There are two ways to do this:
    • Open the Developer Console. Navigate to the Console tab. Type in “rudderanalytics” into the command line and press enter. If an object is returned then that means that RudderStack was loaded. If an “is not defined” error message is returned then it means that RudderStack code was not loaded properly. Make sure the script from the docs is copy and pasted correctly, especially the cdn.rudderlabs.com script link!

  • Open the Developer Console. Navigate to the Network tab. You can filter with the word “rudder” and then refresh the page. Then, inspect the different network calls that were made and try to locate a rudder-analytics.min.js request. If you can find it, that means that RudderStack was likely loaded.

  • RudderStack also makes a request to fetch the source config, This request will look similar to “https://api.rudderlabs.com/sourceConfig/?p=web&v=X.X.X&writeKey=<WRITE_KEY>”If this request succeeds, that means that RudderStack was able to get the configuration file which is great! If this request fails, then you may want to check the write key and see if it matches the one on your RudderStack Control Plane.

  • Are my calls being sent? Use the Network tab to answer this question. When you think an event should be getting sent to RudderStack, have the Network tab open and inspect it. The request should be getting sent to whatever your <Dataplane URL> is and should be named according to the event name i.e. page, track, identify etc. If these events fail, check your Write Key and Dataplane URL combination as they may be incorrect.

Fun tip! You can use the Console tab of the Developer Console to actually send RudderStack events. As long as RudderStack is loaded properly, you can type certain events in the console and send them to RudderStack. See example below…

  1. Live Event Viewers: You can leverage the source live event viewer, the user transformation live event viewer, and finally the destination live event viewer, to see how the event travels through the RudderStack pipeline. These live event viewers are helpful to narrow down where exactly the root of the issue may be.
    • Source Live Event Viewer: Helps you to figure out if the event is getting received by RudderStack at all. The payload you will see in this viewer is the raw payload sent by your source:

  • User Transformation Live Event Viewer: This viewer gives you a before and after snapshot. You can see what the event looks like going into your user transformation and what it looks like afterwards.
  • Destination Live Event Viewer: The final live viewer shows you what the payload looks like as it is being sent to the destination. If the destination returns an error message, you will be able to see that here as well!

Adding Events to the Website

  • page() calls: First things first, you probably want to know how users are entering your site and navigating while on it. The most effective way to do this is to include a page call on every different page of your website. In fact, the SDK that you copied and pasted from the docs in Step 2, actually includes a rudderanalytics.page() call, so you are already set up with this!

  • identify() calls: Once you have some personal identifiable information (e.g. email, userId etc.) you will want to make an identify call to change your user from anonymous to identified. A great opportunity for capturing this valuable information is during sign up or login, through a newsletter subscription form, an order checkout flow, or a demo request form. You can add a submit event listener onto the form, and in the callback function you can call rudderanalytics.identify(email) to identify the previously unknown user with the information they provided. RudderStack will save this information and attach it to any subsequent call. Here is an example of a perfect time to make an identify call. This snippet is in the script.js file of the website.

  • track() calls: Now that you know who your users are and what pages they are visiting, It is important to understand exactly what they are doing while visiting your site. Common events that you can track are button clicks, form submissions, and/or any of these standard ecommerce events. Here is an example of adding a track call to the script.js file.

There is no limit to what you can track with RudderStack, but you may want to ask yourself a few key questions before implementing a new track call

  • Are the event names and properties clear? The stakeholders that are implementing these calls may not be the same as the ones analyzing the results. Make sure you are clear and concise with your naming conventions and schemas so that everyone can quickly understand what they are looking at. We will talk about event properties in more detail in the next section.
  • Is the event name dynamically generated? We suggest avoiding dynamically generated event names. An example of this would be “<button-text> Button Clicked”. Consider, instead, setting the event name as just “Button Clicked” and then setting a property that contains the <button-text>. This will help keep your warehouse tables and analysis more organized and concise.

  • Is this information being captured already? While more information is always better, redundant calls can cause confusion when it comes time to analyze the data.
  • Will I need this insight? This question may be the least important item to consider. However, some users like to capture everything, but then are left with the “boil the ocean” problem. A good approach may be to track the key events first and then expand over time.

User Traits vs Event Properties

While reading through our docs, you may see many mentions of traits and properties. What are the differences between the two, and when should you use them?

TLDR: Traits help describe the user that is taking the action, while properties help describe the action/event that the user is taking. Both of these are distinct and should be placed in different places to avoid confusion and redundancy.

User traits must be added to a particular user through the identify call. The benefit of that, is these user traits will be saved and attached to any subsequent calls that are sent to RudderStack. For example, if I make the following identify call

The user’s email address and phone number will be attached to any track or page call that happens after. You can find these traits in the context.traits object of the event payload.

Important: If you are going to fire an identify call and a track call, make sure to fire the identify call before the track call. That way, the track call will automatically have all of those user traits attached to it!

  • Properties: Properties are different from traits because they describe the event and not the user. Properties can be anything you would like! Here are some examples:
    • Button text
    • Price
    • Products
    • Order ID
    • Form ID, etc

Remember, if you have an identify call before the track call, then there should be no need to include user information in the properties object. The user traits will be added to the track call automatically.


Why is this important? When transforming your event to send it to its final destination, RudderStack will look in particular locations for specific pieces of information. For example, if you want to send a user’s email address to your destination, RudderStack will look for it in the traits object and not in the properties object. Therefore, it is best practice to put all user information in the traits object via identify calls and all event information in the properties object with the track call.


Conclusion: We hope this quick guide will help you kick start your RudderStack journey and set you up for success as you grow. We covered how to debug issues when things do not look right, what the different types of events are and how to use them, and finally when you should use traits vs properties.