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.
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):
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.
- Workflow Runs panel
- Workflow Steps panel
- Step Data panel
- Replay / stop button
- Logs / Data search box
- Logs Status button (Live/Paused)
Guide to the logs panels
1: RUNS panel
Each result is a single workflow run, along with the current state or how long the total run took. New workflow runs appear at the bottom of the list, and are listed by their trigger activation time.
- Green runs are SUCCESSFUL completed workflow runs
- Yellow runs are still PROCESSING
- Red runs have FAILED at some point during their step activation
- Grey runs have been STOPPED or are being replayed
At the top there is a search bar above the list of workflow runs (and above the list of steps). You can use these search boxes to search your logs history by using the search filters available.
2: STEPS panel
To view the workflow steps themselves, click on the individual run you wish to view.
You can do this on either failed, successful, processing or stopped runs. No matter the status of your run, you should be able to view how many steps your workflow has completed, and what status they are. The same colour coding from the previous panel applies.
3: DATA panel
Click on the individual step you wish to view, and you will automatically see the final section of the Logs Interface expanded.
This is the section that displays the steps Input and Output Panels aka the data received and the end results of the formula (presented in json format). You will also be able to see some other details like begin, end and total run time.
Here your only search option is to search through the available data from your input and output panels themselves. Any occurrences found will be highlighted within the individual input / output panels themselves. Typos really matter here, so PLEASE take extra care when writing out what you are looking for.
Searching 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.
1 - Querying the Run Panel
Once you place your cursor within the search bar itself, you should have an auto-generated, drop-down list of Search Filters available to you, to help you begin your Search Query:
From there, the steps are as follows:
- Select a 'Search Filter', eg:
- This will be automatically followed by the 'Separator' step:
- This will be automatically followed by the 'Separator' step:
- Specify your 'Search Parameters':
- Press the search button.
The final search query result will be displayed within the search box itself:
after > 2020-04-14T08:30:09.574Z
Certain searches will have continued drop-down options to help specify your request. In the above example, in order to get all the logs that have run after 09:30am, there are two more steps to complete:
Your results will be Tailored accordingly, displaying only those logs which have run past 09:30am:
2 - Querying the Steps Panel
You can deepen your search by using the search box above the second Workflow Steps panel. Again, type in the parameters that you wish to use (in this case, we are demonstrating how to search for a key input field, from within the step itself):
input > step:slack-2 > field:username > Tray.io.
Again you will have drop down options available for you to use, and once they are filled in, you should have your query displayed as usual within the search bar, alongside your newly filtered step results - having gone from 3 log steps to now 1.
3 - Querying the Data Panel
You can refine your search even more so, if need be. Sometimes this is very useful, especially in instances where you have large data amounts to get through. Type in what you are searching for and if found, Tray.io will highlight it for you. Remember that typos matter here! so please be accurate when writing!.
In order to better understand where the data we are searching for is coming from, we have also opened up the step's property panel (press 'shift & click' on a connector step within the container and the parameters for said step will appear). The 'Properties Panel' will automatically popup on the right hand side of your builder.
Note: For a full overview of what search filters available within the Debug panels, see theSearch Syntax tables for more details.
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.
On most plans, you can view your logs for up to 30 days since the last workflow was run.
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.
Sharing & Saving 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.
Should your workflow have several search filters applied throughout the Debug Panels, and you know you may need to repeat this search (on this workflow) again; you can now save your search query within your bookmark bar for later usage. Thereby saving you the effort of having to re-create said search query in the future.
Should you return to your bookmarked workflow and search in later days, the saved settings will apply and thus the search itself will automatically update the results depending on the logs that are now available there.
Note that even if you were to refresh your browser screen, your search query will still be saved.
Sharing your workflows is extremely simple. You need only copy the workflow URL and send the link to the user in question. Your search filters will stay intact, and will be able to be viewed on "their" screen as well as yours (though the query itself will be hashed out in the address bar for security purposes).
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.
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.
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.
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:
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. See Data Panel Search Bar for more details.
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:
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.
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.
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
|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
|*||Searches within BOTH the INPUT & OUTPUT panels for your specified value||Tray.io|