Tray Platform / Logs and Troubleshooting / Logs and Debugging

Logs and Debugging

Intro to Logs

When a workflow is run, it will produce a Workflow Log, which includes both an Input and an Output record of each individual Step within said workflow.

Using workflow logs enables you to follow a process of elimination and investigation by checking each step's individual input and output. This "step by step" process is crucial to troubleshooting your workflow issues, solving your bugs and searching for crucial information.

Logs make it easier to investigate issues and they especially help when building more complex workflows, as you are able to see what each individual workflow step is receiving (i.e. the input), so you can compare it to what the workflow step - or yourself - might otherwise expect to see. You can then further investigate using the output record (aka the end result of said step) with the same principles in mind.

IMPORTANT!: It is best practice to set up alerting workflows to automatically notify you about errors occurring within your workflows. It is very important that you do this in order to deal with anticipated error scenarios, and prevent any potential data loss. Please see our Error Handling guide on this for more details.

Using the Logs Interface

Getting used to a new interface can be daunting, which is why we have compiled this breakdown of the Logs Interface display, in order to help you get to grips with what each section is most commonly referred to.

To display the logs for a workflow, click on the 'Debug' button in the header section of the builder (it will highlight blue once selected):

logs-debug-btn

While all the sections may not make sense to you yet, as you work your way through this page, their purposes will become more clear and you will be able to use this as your point of reference should you need it again later on.

Make sure to use the Key provided as your guide, and feel free to open this image in a new tab for a larger image.

logs-section-names-alt

Key:

  1. Workflow Runs panel

  2. Workflow Steps panel

  3. Step Data panel

  4. Replay / stop button

  5. Logs / Data search box

  6. Logs Status button (Live/Paused)

Logs panels explained

Searching Panel Logs & Syntax

As previously mentioned, there is a search box available at the top of the list of workflow runs, logs, and data panel itself. You can use this search box to filter your logs history for specific log instances or data, using a unique Search Query.

There are many search filters available, and while it has been mentioned briefly above, this area is solely dedicated to giving you a much more thorough understanding, so that you can learn one of the most important aspects about how to debug and troubleshoot your workflows most effectively (every users dream come true!).

Note: For a full overview of what search filters are available within the Debug panels, see the Search Syntax tables for more details.

Lost Data

As mentioned previously, it is Best Practice to set up Error Alerting within your workflows, so as to automatically receive notifications when errors do occur. It is very important that you do this in order to deal with anticipated error scenarios, and prevent any potential data loss.

This kind of Error Handling will help you as a user get to grips with Troubleshooting Data and the general Debugging process as a while, making the entire approach smoother for you from the start.

On most plans, you can view your logs for up to 30 days since the last workflow was run.

IMPORTANT!: Please note that while you may be able to view your logs for up to 30 days; you can only click the 'Replay' button (i.e. re-execute a workflow run within your logs list), up to 7 days from when the workflow run was last triggered.

This means that there are potential pitfalls should the workflow fail, and you dont get to the run you need to execute, within the 7 day time frame.

Even if you do, and are able to re-run your specific log after only 5 days delay, the results may still be inaccurate, even though the workflow hasn't changed. If your workflow has not been run for a month, there may even be no runs to display.

Lost Data Scenario

Imagine a scenario where you have a workflow that is designed to create and collect a list, of the number of new subscribers who have signed up to receive your product email updates each week. It runs weekly, and usually there are no issues.

  • Every Monday the workflow creates/ collects a list of the new subscribers who joined your product updates emailing list, over the past 7 days, sends you the number, and you then feed it into your marketing chain to do with as you wish.

  • For whatever reason this time, the workflow errors. You have not set up any error notification handlers to deal with such a scenario occurring (naughty!), and so you are not aware of this when it occurs.

  • When you do discover the error, say, the following Tuesday having not received the usual list update; you are still able to view your logs as normal, including the failed run in question. But you will be unable to re-run said log. This is because the run log itself is over 7 days old.

  • This means that the data you would have otherwise received will now be unavailable to you. Even if you trigger your workflow now, and the workflow works perfectly, it will only be picking up the current data, within the current time frame (7 days past from Tuesday, instead of Monday) and will therefore give you inaccurate results.

PLEASE be wary of such instances occurring. Tray.io is not responsible for data that cannot and is not backed up. It is only under very rare circumstances that Tray.io might be able to help you retrieve some of your missing data when such instances do happen.

Debugging a workflow

The example below demonstrates how you can debug a workflow by checking the Debug panel's error logs.

The workflow used in this example uses a Github trigger that is fired when an event occurs on any Pull request from the selected Repository.

The main aim is to send a Slack notification when a PR review is requested from a specific person. We have set a Boolean check to verify if the trigger action is equal to review_requested and the person from whom the review is requested is equal to rasikatechwrite.

github-slack-boolean-condition

When a certain user raised a review request, say KateHickey26, the set configuration did not work, and the reviewer rasikatechwrite did not receive a notification for a review request.

The slack notification was not received because of an incorrect boolean check, i.e., $.steps.trigger.sender.login Equal to rasikatechwrite. The correct attribute for the check can be identified using Github trigger's debug logs.

To do so,

  • Under the 'Debug' tab, search for Kate using the search bar on the Run Panel, which will bring the logs for the specific PR raised by Kate.

  • Select the log that shows the review requested by Kate and click the Github trigger step from the Steps Panel to open the step-specific logs.

  • On the Data Panel using the search bar, search for rasikatechwrite. Since the review was requested from rasikatechwrite, this helps you understand the exact field from the trigger logs that you can use for the boolean check.

github-debug-steps

So the correct boolean check would be $.steps.trigger.pull_request.requested_reviewers[0].login Equal to rasikatechwrite.

Useful Tips

Saving & Sharing your Queries

One of the most practical features within Tray.io is the ability to easily SHARE your search queries and even SAVE your search queries if need be.

Replaying and stopping runs

When you want to replay a run, simply hover over the run log in question, and a new button option will be presented to you. You can also use this method to stop your runs mid flow should you need to.

IMPORTANT!: When you replay a workflow run, it will re-run the data from the particular run youhave selected, but using the current settings for your individual connector steps, NOT the oldsettings.

This is how you can use replays to recover data that might not have been picked up by a failed workflow run - i.e. fix the workflow, then re-run! See above section for more details.

logs-search-interface-container-1-replay-btn

Note that when you replay a run, a new workflow run is activated and listed in the workflow run log listings.

The original workflow run will still be present, as you have simply triggered the run cycle again. Doing so does not delete or override the previous run. The new run will be displayed directly beneath it, at the bottom of logs listing.

This is especially important in regards to error fixing. For example, say a workflow run failed but the user then fixed the error within the builder. The user could then go back to the run logs listings and select the re-run option, from the previously failed/ red highlighted run.

The previously failed run will still show up in the logs listings, but now there will also be a new (hopefully) green/ successful run directly below it as well.

Step Panel Parameters

If you press 'shift & click' on a connector step within the container (or within the main builder as well), the parameters for that step will appear within the 'Properties Panel' to the right hand side of your builder. Aka, where you would normally fill in your step's field data.

Logs Status Button

There is a grey 'Logs Status Button' at the bottom of the first two panels. This enables you to switch between statuses ('LIVE' and 'PAUSED'), in order to prevent any new workflow runs or steps from appearing.

logs-search-interface-container-1-status-btn

Drag Handle

Sometimes it is hard to see your query due to the width of the interface section. This is easily mitigated by using the Drag Handle available:

logs-search-drag-handler

Typing into the Search Bar itself

You need not go through the search filters one by one if you are use to the terminology and how it is applied.

You will notice that once you have gone through the usual clickable options, the text within the search bar is displayed in a format that can be easily replicated by more advanced Tray.io users.

Once you are confident with how the search filters work, you can simply type in the search bar directly in order to achieve the same results.

Note that when using the search filter in the Steps Data panel, typing directly into the search bar is your only option.

Data Type

You can search by Data Type within the search bar.

For example a search of 1 will search for "1" and 1, or a search of "false" will search for "false" and false.

Data types recognised are as follows:

  • String

  • Number

  • Boolean

Use Output Button

Notice that the Output Panel also has a 'Use output' feature. This is for use with the connector-snake, when you need to generate more list results, than the given default amount.

CONNECTOR-SNAKE: The simplest and easiest way to generate your jsonpaths is to use our feature called the Connector-snake. Please see the main page for more details.

Expandable

If you wish to take a closer look at your input and output results, you can expand both of these fields to generate a larger pop-up. Depending on the size of your json data, you may have a scrollable option as well.

logs-search-interface-container-3-expand

Search Syntax

The following table provides a breakdown of the Basic searching syntax available while the latter goes into more detail regarding Input and Output query options that are available.

Debug Panels 1 & 2

Name Function (Displays) Example
Before Runs/ Steps which executed BEFORE a specific date & time (yyyy-mm-dd hh:mm) before > 2020-04-14T08:30:53.647Z
After Runs/ Steps which executed AFTER a specific date & time (yyyy-mm-dd hh:mm) after > 2020-04-14T08:30:53.647Z
Successful Runs/ Steps which were SUCCESSFUL successful > *
Failed Runs/ Steps which FAILED their execution failed > *
Running Runs/ Steps that are currently RUNNING running > *
Input Runs/ Steps which adhere to the INPUT prescribed input > step:slack-1 > field:username > Tray.io
Output Runs/ Steps which adhere to the OUTPUT prescribed output > step:slack-1 > field:username > Tray.io

Debug Panel 3

Name Function (Displays) Example
* Searches within BOTH the INPUT & OUTPUT panels for your specified value Tray.io