The goal of this “DeepSee Troubleshooting Guide” is to help you track down and fix problems in your DeepSee project.
If the problem can’t be fixed by following the guidelines, you will at least have enough information to submit a WRC issue with DeepSee Support and provide all the evidence to us, so we can continue the investigation together and resolve it faster!
Please NOTE: If you are unfamiliar with the consequences of a given action or command, please don’t run it as it might have an effect on your production system. In this case contact DeepSee Support for further assistance.
The easiest way to follow this guide is by starting on the left and make your way to the Action column on the right.
| Problem Area | What happened? | Analysis | Solutions |
|---|---|---|---|
| Build Problems | Errors during builds | Check Error Message Run $System.OBJ.DisplayError() if Build didn't show errors Check ^DeepSee.BuildErrors/ run ##class(%DeepSee.Utils).%PrintBuildErrors(pCube) |
Fix Errors in Message |
| Less records built than rows in source table | Check cube for build restriction | remove or accept build restriction | |
| Check if maxfacts is used | remove maxfacts | ||
| Check ^DeepSee.BuildErrors/ run ##class(%DeepSee.Utils).%PrintBuildErrors(pCube) | fix build errors | ||
| Check indices in source class | Rebuild indices in source class | ||
| Missing Data | Records from source are not available in DeepSee | Check previous section for problems / restrictions in build | remove restrictions |
| Check "%OnProcessFact" in cube definition | correct method if necessary | ||
| Check for build errors | fix build errors | ||
| Debug methods in sourceExpression | fix methods | ||
| Check Fact table records | find cause of mismatch and resolve it | ||
| Compare Fact table to source table | |||
| Wrong Results | Duplicate Members in Level | Check dimension for valid hierarchy | Change level according to this article |
| Query shows unexpected results | Check previous section if data is missing Check if caching problem: - do $System.DeepSee.Shell() - cache off |
Fix errors on build do $System.DeepSee.Reset() kill ^DeepSee.Cache |
|
| Split query in smaller segments (i.e. each axis separately) Find problematic segment |
fix Problem in Segment | ||
| Check ^DeepSee.AgentLog | do ##class(%DeepSee.TaskMaster).%Reset() | ||
| Listings are empty | Check if normal Listing | Grant permissions on selecting from source table | |
| Check if Custom SQL Listing | Debug WHERE conditions Check ^DeepSee.SQLError Check ^DeepSee.QueryLog |
||
| Hangs / Unexpected Events | DeepSee not reacting as expected | Check System Health | |
| hangs | Check agent status | ||
| Check License Usage | Buy More Licenses | ||
| previously working operations fail | Check ^DeepSee.AgentLog | do ##class(%DeepSee.TaskMaster).%Reset() | |
| Run do ##class(%DeepSee.TaskMaster).%PrintLog() | |||
| Check ^DeepSee.LastLogError Check ^DeepSee.PivotError() |
Fix Errors found | ||
| Performance Issues | Build Performance low | Run do ##class(%DeepSee.TaskMaster).%PrintLog() | |
| Check number of available agents | do ##class(%DeepSee.TaskMaster).%Reset() | ||
| Check memory and CPU usage | run build in phase of low load | ||
| Check source expressions | avoid source expressions if possible | ||
| Check general Cube Statistics: | remove unnecessary dimension/levels | ||
| - do ##class(%DeepSee.Utils).%Analyze("Holefoods") | keep cubes simple and slim | ||
| High journaling activity | Using a data warehouse design or separate namespace for DeepSee you may disable journaling in this namespace | ||
| Query Performance low | run Report: do ##class(%DeepSee.Diagnostic.MDXUtils).%Run(<query>) | plausible long running queries need simplification or workaround | |
| Check memory and CPU usage | free resources | ||
| Check buffer settings | raise buffers if possible | ||
| Make general System Perfomance Analysis | on runtime perforrmance issues ask WRC for help | ||
| Common Reported Issues | Namespace Not Listed In DS Menu | Check if DeepSee is enabled in web-application settings /csp/<namespace> | enable "DeepSee" in web-application |
| Architect is grayed-out | Check license | get DeepSee enabled license | |
| Check roles of user | add resource %DeepSee_Architect / %DeepSee_ArchitectEdit Use | ||
| Check if your browser is not IE 8 | use supported browser |
Here are the mind-map diagrams for each problem area:
Great work, Sascha! Thank you!
Is it possible to make a mindmap version of this table too?
I need to check which other visualizations will work. I think the table gives the best overview. A mindmap or flowchart could look confusing.
As I see there are some cases with empty boxes in the solution column. I would add "Put a question on the Developer Community" there as a solution ;)
Or "Contact WRC" :)
Fixed a bit style for table, increased font-size, and removed unnecessary empty cells
Thanks Sascha and Dmitry!
It would be nice to add links (where applicable), to either documentation or other posts in the Developer Community, that have more details about the topic/troubleshooting step.
Sascha!
That looks just great! It's significantly clearer now. I'll print it out, it would be my favorite wall poster ;)
I would add also to the Build/Less facts section following:
sometimes you have no facts for the cube against source class with plenty of records. Please check the indexes in the source class and rebuild it, it can help. I met this thing.
I added your suggestion in the table and mind map.
Great guide. I would add something to the 'hangs' section on system health. We were evaluating DeepSee and having massive performance and hang issues. I was trying to do complicated stuff, and the machine was underpowered, but a MAJOR part of the problem was license thrashing. We had four licenses and my queries were essentially trying to spawn multiple processes and hitting the wall, and then trying again and again and again. Not only did we miss this, but it did not occur to support either, until they saw 'This Service Unavailable" messages, and tracked that down to license depletion. Changing our evaluation version to 10 licenses, with no other changes, to the machine, or the queries, instantly took the machine from DOA to usable.
Thank you Sam, this is a good suggestion.
Thanks for your suggestion. I added that to the table.
I would add something about 'This Service Unavailable" messages when trying to run Analyzer, Architect etc. - this is not a 'hang', but is symptomatic of no more available licenses. Sorry I didn't mention this explicitly before. Even the support guys on the phone with me did not know that the system was trying to tell us it had run out of licenses - they had to check the logs. Until a more meaningful error message is provided, perhaps this should be added to the chart too.
Cheers.
Journaling the DeepSee cache (the ^DeepSee.Cache* globals) can also cause low query performance
Journaling a DeepSee environment is a real performance killer.
Take a look of the Journal when using a Bitmap Index