I would like to introduce a networking opportunity for all you infrastructure groupies, or those interested in the technical side of the Hyperion suite. Follow Rob Donahue on twitter – @EPMTechTips.
KScope12 is the premier conference for Hyperion techies and up-and-comers. Whether you are looking to brush up on your skills, learn new skills, or see how others overcome challenges, you will want to participate in this event. If your organization values your development and has a budget for these growth opportunities, mark your calendar for June 24th through the 28th. Registration is open, and as more information is available, it will be published at In2Hyperion.
Presenting a topic is a great way to reduce the cost of the trip. It’s a great way to get your name out in the community as well. If you have something that you think would be valuable for other experts to hear about, submit an abstract.
We hope to see you there. Visit www.kscope12.com for all travel details and abstract submissions.
This section will talk about how to dive into debugging critical issues with Oracle EPM.
Start a Problem Log
The most useful habit to develop during issue resolution is to start a detailed log about the issue. Some problems can take days or weeks to resolve and require trying hundreds of different prospective resolution attempts. It is easy for a “small” problem to become a long winded issue. Consequently, it is hard to foresee when the issue will resemble the analogous onion: keep peeling off layers and finding more and more to fix. If the problem log is created initially, all the important details can be captured. Additionally, it is much easier to bring others up to speed (management) and create support tickets when all of the information is documented. This log should include the error as the end user sees it, the error from any logs you are able to capture, screenshots, timestamps, and things that you have tried along with the results.
Reproduce the Issue
The first thing to find out is whether the issue is reproducible. It is very difficult to solve an issue that is not reproducible. Many errors are simply ‘glitches’ and may have been caused by a very improbable event, such as a database hiccup. For instance, a database problem propagates into the Oracle EPM system, forcing it into a bad state. Such a problem may never produce itself again. Consequently, an initial step toward resolution is to restart the Oracle EPM services to bring them back into a ‘known state’. If the problem is not immediately reproducible after the restart, go back to the problem log and record everything you can. This type of issue will need to be profiled over a period of time to try and discover patterns if it occurs again.
The Numerous Logs
Once it is discovered that the issue is not a simple glitch, it is time to start digging. As mentioned previously, the first place to track down the cause of an issue is in the logs. The logs come in various forms. Here is a general breakdown of the log types:
General
| Log Type | Description |
| Windows Event Viewer | This is helpful for general system related messages. Also some modules built on Windows Technology (DCOM) will log messages here. For example, Financial Management (HFM) and Financial Data Quality Management (FDQM). |
| Application Logs | The application logs are actually generated by the Hyperion code itself. These often contain the most useful information. |
| Application Server Logs | This type of log pertains to a Java based Web Application. Most of the Hyperion modules with a web based front end have Application Server Logs. The Application Server Logs run within the WebLogic, Tomcat, or WebSphere container. |
| Web Server logs | The web server controls the handoff of web requests between the Hyperion Modules. The best way to use this log is to look for error codes (404, 401… etc) in the web log and review the corresponding URL that was used to ensure it is correct. Sometimes it might be obvious that the URL in the web log has the wrong domain, points to the wrong server, or cannot resolve the context. |
Start by reviewing the log for the product where the error is occurring. The Application Logs and Application Server Logs will be most useful at first. The goal is to find a useful error message that can be used in the next process to find a resolution to the problem.
Common Log Locations:
Unfortunately, the actual log locations change drastically between recent versions of Oracle/Hyperion products. As stated before, searching for *.log might be useful.
Example Application Server Logs:
| Essbase Admin Services | Svr2 | /Oracle/Middleware/user_projects/domains/EPMSystem/servers/EssbaseAdminServices0/logs |
| Workspace | Svr1 | /Oracle/Middleware/user_projects/domains/EPMSystem/servers/FoundationServices0/logs |
| Financial Reporting | Svr1 | /Oracle/Middleware/user_projects/domains/EPMSystem/servers/FinancialReporting0/logs |
| Analytic Provider Services | Svr2 | /Oracle/Middleware/user_projects/domains/EPMSystem/servers/AnalyticProviderServices0/logs |
| Web Analysis | Svr1 | /Oracle/Middleware/user_projects/domains/EPMSystem/servers/WebAnalysis0/logs |
Example Application Logs
| Reporting and Analysis Core | Svr3 | /Oracle/Middleware/user_projects/epmsystem1/diagnostics/logs/ReportingAnalysis/
/Oracle/Middleware/user_projects/epmsystem1/diagnostics/logs/ReportingAnalysis/stdout_console_default.log |
| Essbase | Svr4 | /Oracle/Middleware/user_projects/epmsystem1/diagnostics/logs/essbase/ |
Sifting Through the Logs:
It helps to know which modules depend on each other in order quickly pick out the respective log files to analyze. The basic idea is to determine which products are interacting and to review each log in detail for messages. It is important to review the logs of the product not only during runtime (as it is happening), but also during startup. Sometimes the fastest way to cut out the fluff is to stop the services, move or delete all the existing logs and start the environment back up. This ensures any log messages are relevant to the issue. Alternatively, one has to sift through potentially large logs looking for timestamps to ensure relevance, which can be daunting.
| Product | Depends On |
| Shared Services | Relational Database, MSAD/LDAP |
| Lifecycle Management (LCM) | Shared Services, LCM Source/Target applications |
| Essbase | Shared Services |
| Hyperion Planning | Shared Services, Essbase, Business Rules, Relational Database per App |
| Business Rules | Shared Services, Hyperion Planning, Essbase, Relational Database (single database) |
| Hyperion Financial Management | Shared Services, Relational Database (single database), DCOM (Event Viewer) |
| Financial Data Quality Management (FDM) | Shared Services, Relational Database per App, Adapters for Essbase, Planning, HFM…etc, DCOM (Event Viewer) |
| Strategic Finance | Shared Services, Relational Database (optional) |
| Data Relationship Management | Shared Services, Database Client, Adapters, DCOM (Event Viewer) |
Found an Error Message!
After discovering the error message, the first thing to ask is does this message make any sense? Try to use it within the context of your problem to solve the issue. Often, it is necessary to use external resources to resolve the issue. Use resources like Google, the Oracle Support Knowledgebase, and the Oracle Forums to further research the issue. Most often there will be information regarding your issue.
Note: If possible do not searching using end user messages, i.e. what the user sees when encountering the error. Rather, find a detailed message in the logs. The end user messages are usually very generalized and can provide misleading information because of the vast number of issues which might match the general error message.
If there is still a struggle to discover a useful error message, most of the Hyperion modules use a logging mechanism that can be changed into debug mode. The actual method will differ based on product, for instance, most modules use log4j and there is often a .properties file you can change the logging level from “ERROR” or “WARN” to “DEBUG”. For instance, to enable debugging in Hyperion Planning: log into a Planning application, go to Administration -> Manage Properties, Select the System tab, Add the property DEBUG_ENABLED with a value of True. After changing the logging level, the service will need to be restarted to reflect the changes. Turning on application debugging should provide more context clues around what the product is doing at the time and help pinpoint the error.
Nothing Found…
If these resources do not help, an Oracle Support Ticket may be required. Additionally, the Oracle Forums can be a good place to post a question. When creating a support ticket and posting to a forum, please include as much information as possible. This is where the Problem Log will come in handy.
This is a good time to look for updates and patches to the product. Check for patches and updates on http://support.oracle.com. Read the release notes for anything matching your problem. Even if there is nothing coming up, some obscure errors can be solved by simply applying a patch. Not all bugs will be in the release notes for the patch. Oracle’s hpatch process is pretty straight forward, but older environments might take some time to apply the patch. Always read the entire release notes and installation instructions before applying a patch. Also, sometimes patches are not as proven as the initial installers. This is because some patches may have just been release and only tested with a handful of clients. So ensure there is a good backup process in case the patch causes unintended problems. The Oracle hpatch process has a back out feature, but it is not always useful if the patch is half way installed and failed.
Finally, the last part of troubleshooting is intuition. As more problems are encountered and resolved, one can become more confident in resolving upcoming issues. There is no way to have encountered every issue and know the resolution, so the best that you can do is arm yourself with a good knowledge of the architecture, have a set of best practices, and lots of patience for problem solving.
This article will discuss some best practices around troubleshooting and debugging your Oracle EPM environment.
Oracle EPM (Hyperion) is a complex system that is composed many modules that work together to perform different functions. Typically, in design, creating a modular approach is a best practice. However, the Oracle EPM modules were created with disparate architectures because they acquired over time through purchasing technology from many smaller companies. As a result, the modules interact only at a high level, through network APIs. The result is a complex system with many breaking points, and error messages that can be less than informative. Consequently, troubleshooting and debugging Hyperion is an art form.
The fastest way to debug a critical problem is to have a good understanding of what components represent a known, “good” state. Only by identifying the abnormal element in the system can one start to resolve a critical issue.
Below Are Best Practices to Follow to Document a Known, Good State
What Should Be Running?
The first question you should ask is, “is everything up?” Typically you would start by checking the URLs you use for each product – ensuring you can login. These URLs would typically include the load balancing name.
Example of End User/Administrative URLs
| Shared Services | http://hyperion.svr.com/interop |
| Hyperion Planning | http://hyperion.svr.com/HyperionPlanning |
| Essbase Admin Services | http://hyperion.svr.com/easconsole/console.html |
| Workspace | http://hyperion.svr.com/workspace |
| Web Analysis | http://hyperion.svr.com/WebAnalysis |
| FDM | http://hyperion.svr.com/HyperionFDM |
Set Up Port Monitoring Software
You can also get a ton of info in a quick glance by setting up port monitoring software. Remember to include the relational database in your monitoring. Sometimes the DBA will take the database down unexpectedly, or the database user IDs will expire. Additionally, it is easy to have 20-30 Hyperion related services or processes running per environment distributed among multiple hosts. It’s too time consuming and error prone to check manually.
An Example of a Custom Java Based Port Monitor
To gather a list of ports within the environment there are a few aids to use for reference. Oracle EPM Version 11 includes a diagnostics web form that will show the status of some of the products. This can be found under the Windows Start Menu, under Programs -> Foundation. This might be a good place to get started.
Also, refer to the Oracle EPM Documentation, Install Start Here Document for typical port reference.
http://download.oracle.com/docs/cd/E17236_01/epm.1112/epm_install_start_here.pdf
An Example of Some Common JVM Ports
| Application | Server Cluster/Node(s) | Port |
| Workspace | svr01 | 45000 |
| Web Analysis | svr01 | 16000 |
| Financial Reports | svr01 | 8200 |
| Shared Services | svr01 | 58080 |
| Analytic Provider Services | svr04 | 13080 |
| Hyperion Planning | svr02 | 8300 |
| Strategic Finance | svr04 | 7750 |
| Essbase Admin Services | svr04 | 10080 |
| EPMA | svr02 | 19091 |
Stopping and Starting the Environment
Operational procedures are important too. This means having a reliable start and stop procedure for the environment. Given the complexity of the Hyperion environment, there is no excuse for problems occurring while bringing an environment back up after routine maintenance. One common issue that comes up is a service did not start completely, which can be found by using the port monitoring method above. Also, sometimes the services do not fully stop – causing residual processes to mess up the restart procedure. This might include extra ESSVR processes indicating the Essbase application did not stop properly, or a JVM process which is hung. As a precaution, check the port monitoring software after stopping the environment to ensure all the components are indeed down. It is time consuming when this type of issue is encountered. In a Windows environment you might take the environment down through your normal process, then kill any remaining “Java” and “Hyperion” related processes using task manager. In a Unix environment, after stopping the environment, “kill -9 -1” can be used as a last resort. A reboot will always solve this type of issue, though not often actually needed; it might be faster as a last resort for the unskilled admin needing to fix unexplainable issues.
Functional Validation Script
Functional validation is a set of very simple actions that can be performed within a few minutes to validate the functionality of the environment. This is absolutely necessary to perform before handing the system back over to end users after a routine maintenance. This task can be either performed by the Hyperion Admin or handed over to the Help Desk. It should, at a minimum, include running a few types reports (HFM, FR, WA), log into Essbase, Planning, HFM, etc… As you discover other reoccurring issues you may want to include more specific checks to ensure common “gotchas” are ironed out before handing over to the end users.
Knowledge of the Architecture
The Hyperion administrator has to be technologically savvy. However, many times Hyperion will tell you exactly what the problem is. The first place to look when encountering an issue is the logs! Take time to find and document the log files for every product in your environment. Most administrators are a bit intimidated by the number of logs generated by the system, but this is the first place to look. Familiarize yourself with the various logs in the environment. This includes WebLogic logs, JVM logs, Hyperion logs, and operating system logs. If you are lost, a good place to start is search for *.log, sort by date, and look at the directory for the product name. You might even keep a record of each log after starting the service successfully so that you can compare to a good state if there is a problem.
Additionally, it is necessary to have context around how the environment works. This can be achieved by reading the product manuals, looking at architecture diagrams, and attending training sessions. Get involved in the environment. Try to understand both the technical details (ports, logs, different components…etc) and the functional basics (create a planning form, edit an outline, load data into Essbase, run a consolidation) of each Oracle Module.
A Good State: Create a Knowledge Base
Hyperion issues commonly come up more than once. Create a shared, searchable, knowledgebase to track issues and their resolutions. This will help you train your team as it expands and changes over time.
Final Comments
The focus of this article was to provide the Oracle EPM Administrator with best practices on how to document the current state of the Oracle EPM System. This is the most important part of being able to understand complex issues as they come up. More technical detail will be provided in the Oracle EPM Troubleshooting and Debugging Guide (Part 2 of 2).
As Hyperion applications have become more integrated, the need for multiple servers to support the environment is now required. Although the recent releases of version 11 are less dependent on the order in which the services start, Hyperion still recommends a specific order to start the services so they perform correctly. As these services are typically on multiple servers, it is time consuming to perform this operation and it is prone to error. Many organizations lack the ability to automate this task when services are interrupted, or operating systems are updated, and there is no automated way to start and stop the services.
In2Hyperion is now making available HypServicesManager. HypServicesManager is an application that will start or stop the services in a predefined order. An XML file holds the server/service order so the services to be included, and the order in which they start/stop, is completely customizable. It will impersonate a domain account that has permissions to the respective servers, so the starting or stopping of the services on multiple servers can be performed quickly and remotely. With command line parameters, it can even be automated.
Keep in mind, HypServicesManager is completely independent of Hyperion services. Although it was developed to fill the need to manage Hyperion services, it can be used for any windows service as it uses the windows APIs.
I have used this application in multiple organizations and it is often used in a production environment. With that said, this has not been tested on thousands of environments in every Windows OS. If it doesn’t work for you, we certainly welcome feedback and will make every effort to fix any bugs that are discovered.
Details on the use of the application are available here.
If you have users that rely on SmartView to pull data from your Essbase and/or Planning application, many of them may have large spreadsheets. One way to improve the perception of the performance of Essbase is the method in which SmartView (client side) communicates with the server.
APS, Planning, and HFM have the ability to take advantage of compression during the communication process. When large queries, retrieving and submitting data, are initiated, the performance can be significant.
The default compression settings for APS and Planning are not turned on. The good news is that turning this on is relatively simple.
Find the essbase.properties file on the APS server and change it to false. The path to this file is different in versions 9 and 11. In 11, the path is \Products\Essbase\aps\bin.
smartview.webservice.gzip.compression.disable=false
Open the Hyperion Planning application in question and change the SMARTVIEW_COMPRESSION_THRESHOLD in the System Properties (Administration/Manage Properties – System Properties tab) to a value no less than 1. This threshold is the minimum size of the query in which compression will be used. So, a value of 1000 would mean compression would be used for anything greater than 1,000 bytes.
For smaller queries, compression may not be necessary. It may even decrease performance because of the overhead to compress and uncompress the data. Every environment is different so there is no “right” answer as to what this value should be.
If you have used compression, please share your experiences.
Many developers that work with Hyperion products, as well as many any other software product, use virtual machines. Virtual machines are an easy way to create multiple environments for testing and developing multiple product versions
The 3 main applications to create and use virtual machines are
- Microsoft’s VirtualPC (version 2007 can be downloaded here)
- Sun’s VirtualBox
- VMWare
I have used all 3. Opinions can be found that promote all 3. Many IT professionals prefer VMWare. I have found it to be a little cumbersome to use, and find sharing virtual machines to be a frustrating experience. I am not a stereotypical IT professional, but rather a business person with an aptitide for technology. That said, I prefer VirtualBox. For me, VirtualBox is easier to install and manage the virtual machines. It is easy to move virtual hard drives to another computer, simple to duplicate a virtual hard drive and allows users to take snapshots, which allows, for lack of a better explanation, a huge undo if required.
Through my VirtualBox travels, I have found the following knowledge to be very valuable. Here are some HOW TOs that might be useful if you decide to use Sun’s VirtualBox.
How to reduce the size of a virtual machine
The use of virtual machines (just like any system) cause fragmentation and the size of the virtual hard drive to grow, sometimes substantially. Managing the size of the virtual machine is relatively easy, and is not time consuming. It involves 3 actions (defrag, delete free space, and compact the virtual hard drive). Here is one way to accomplish reducing the size of your virtual machine / virtual hard drive.
- Open the virtual machine that needs compressed
- Download sDelete, and extract the sDelete.exe to c:\
- NOT REQUIRED: Download and install Smart Defrag – this is a free disk defrag tool that I have found to be more effective than the one that comes with the Windows OS.
- Use the disk defrag tool that comes with Windows or the one above, and defragment the hard drive.
- Go to Start/Run, and enter “c:\sdelete.exe -c”
- Shut Down the OS on the virtual machine
- On the host computer, open a command window (Start/Run, and enter cmd)
- If VirtualBox was installed in the default location, change the directory to the VirtualBox directory by entering “cd C:\Program Files\Sun\xVM VirtualBox\”
- Enter “VBoxManage modifyvdi HardDrivePathAndName compact” where HardDrivePathAndName is the full path to the hard drive the virtual machine is using.
If the virtual machine/hard drive has free space, this process will find it and reduce the overall size of your virtual machine/hard drive.
How to duplicating, or clone, a hard drive
Often times there is a need to replicate a virtual machine on the same host environment. Copying the file doesn’t do the trick, as every virtual machine’s hard disk must have a unique key. VirtualBox comes with a tool to duplicate the hard drive and assign it a new key. To accompolish, follow the following steps.
- Reduce the hard drive size (see previous topic)
- On the host computer, open a command window (Start/Run, and enter cmd)
- If VirtualBox was installed in the default location, change the directory to the VirtualBox directory by entering “cd C:\Program Files\Sun\xVM VirtualBox\”
- Enter “VBoxManage clonevdi Source Destination” where Source is the full path to the hard drive the virtual machine to duplicate and Destination is the location of the new virtual machine hard drive.
- Open VirtualBox and create a new virtual machine that points to the newly created hard drive in the previous step.