Blog

[frs-280] Setting VM Options via FRAPI

Setting VM Options via FRAPI

The Sun Java VM (JVM) offers many options to allow the user to control how the VM behaves. The HeapDumpOnOutOfMemoryError option for example is very useful if your server is suffering from heap memory problems and crashing.

By turning on HeapDumpOnOutOfMemoryError the JVM will create a dump file when java.lang.OutOfMemoryError is thrown that can be used in Memory Analysis tools such as MAT to track down memory problems.

A list of VM manageable runtime options includes:

Option Description
-XX:-HeapDumpOnOutOfMemoryError Dump heap to file when java.lang.OutOfMemoryError is thrown
-XX:-PrintClassHistogram Print a histogram of class instances on Ctrl-Break
-XX:-PrintConcurrentLocks Print java.util.concurrent locks in Ctrl-Break thread dump
-XX:-PrintGC Print messages at garbage collection
-XX:-PrintGCDetails Print more details at garbage collection
-XX:-PrintGCTimeStamps Print timestamps at garbage collection

Typically these options are added to the command line that starts the VM in the form of -XX:<optionname>.

There are however major problems with this:

  • Typically you have to edit the file that sets the command line options (e.g. jvm.conf) to change the settings.
  • If the -XX command line option wasn't added to the command line options at start-up then you can't set the option without restarting the server

Using FRAPI

It would be great if you control these VM options using code instead of the command line. FRAPI is a powerful and easy to use API that allows you to take control of FusionReactor programatically. Using FRAPI you can change the running configuration of FusionReactor or add extra debugging information to requests using just a few lines of code. We can also use FRAPI to set any "Managable" VM Option on the Sun JVM. (take a look at the following VM Options for details of all of the VM Options and look for "Manageable").

CFML
<cfset frapi = createObject("java", "com.intergral.fusionreactor.api.FRAPI").getInstance()>
<cfset frapi.setVMOption("HeapDumpOnOutOfMemoryError","true")>
<cfset frapi.setVMOption("PrintConcurrentLocks","true")>
<cfset frapi.setVMOption("PrintGCDetails","true")>   
JSP
<%@ page import="com.intergral.fusionreactor.api.*" %>
<%
    FRAPI frapi = FRAPI.getInstance();
    frapi.setVMOption("HeapDumpOnOutOfMemoryError","true");
    frapi.setVMOption("PrintConcurrentLocks","true");
    frapi.setVMOption("PrintGCDetails","true");   
%>

Requirements

You must be using a version of FRAPI that includes the setVMOption method (introduced in FRAPI 4.0) and a Sun JVM 1.5 or higher.

Notes

  • Due to a Bug in Java the HeapDumpPath VM Option may throw a NullPointerException and typically cannot be used.
  • Only VM Options that are known as "Manageble" can be set/changed at runtime. Manageable means that the option is dynamically writeable through the JDK management interface.

Summary

FRAPI is a easy way to set powerful VM Options while the server is running, without having to restart the server or edit configuration files.

Issue Details

Type: DevNet
Issue Number: FRS-280
Components: FRAPI
Environment:
Resolution: Fixed
Last Updated: 03/Nov/11 5:35 PM
Affects Version: 4.0.0
Fixed Version: 4.0.0
Server:
Platform: Windows XP, Windows 2000, Windows 2003, Linux, MacOS, Solaris, Windows Vista, Windows x64, AIX, Windows 7, Windows 2008
Related Issues:

FRS-232: Capturing ColdFusion’s Debug Output in FusionReactor

[frs-236] OnDemand Seminar: FusionReactor Server Monitor Introduction (with Railo)

Introduction to FusionReactor (with Railo)

This recorded webinar demonstrates how to install FusionReactor on your Railo servers as well as discusses the many useful features FusionReactor offers.

Webinar Outline


  • Installing FusionReactor with Railo
  • Configuring the FusionReactor JDBC Wrapper (in Railo)
  • FusionReactor Feature Run-Down



    • First look: What can I see?
    • System Level Metrics
    • Request Level Metrics
    • JDBC Requests
    • Crash Protection
    • Miscellaneous FusionReactor Goodies
    • Enterprise Monitoring



  • Summary

Watch Webinar

FusionReactor Introduction (with Railo) – Part 1 of 4
FusionReactor Introduction (with Railo) – Part 2 of 4
FusionReactor Introduction (with Railo) – Part 3 of 4
FusionReactor Introduction (with Railo) – Part 4 of 4

Get Started Monitoring

Download a free trial of FusionReactor Enterprise

About FusionReactor

FusionReactor is a generic Java application server monitoring tool that can help you to find, fix and prevent server problems.

Issue Details

Type: DevNet
Issue Number: FRS-236
Components: Installer
Environment:
Resolution: Fixed
Last Updated: 17/May/10 11:36 AM
Affects Version: 3.0, 3.0.1, 3.5
Fixed Version: 3.5
Server:
Platform:
Related Issues:

[frs-238] Getting Started With FusionReactor

Guide to Getting Started With FusionReactor

New to FusionReactor? Use this guide to help you Get Started.

This document refers to FusionReactor 3.0.1 and JDBC Wrap/Un-Wrap tool version 0.8 and is applicable to FusionReactor 3.5.1.

Getting Started with FusionReactor

Useful Links

Download FusionReactor
Install Guide (pdf)
JDBC Wrapper Tool

About the Author

Ajas Mohammed is a Sr. Software Engineer / Sr. ColdFusion Programmer at Absentys LLC with both a Bachelor's and Master's in Computer Science. Ajas has worked in the Information Technology field for over 10 Years.

Ajas Mohammed's Blog

Issue Details

Type: DevNet
Issue Number: FRS-238
Components: Compression, Content Filters, CPU + Memory, Crash Protection, Enterprise Dashboard, FR Enterprise Dashboard Desktop Application, FusionReactor Settings, Installer, JDBC, License + Activation, Logging, Metrics, Request Managment, Thread Management
Environment:
Resolution: Fixed
Last Updated: 20/Nov/09 1:15 PM
Affects Version: 3.0.1, 3.5
Fixed Version: 3.0.1, 3.5
Server:
Platform: Windows XP, Windows 2000, Windows 2003, Linux, MacOS, Solaris, Windows Vista, Windows x64, AIX, Windows 7, Windows 2008
Related Issues:

[frs-237] Creating Daily FusionReactor Log Files

Creating Daily Log Files in FusionReactor

FusionReactor captures a lot of very useful data into log files. These log files can be used to analyze a server in great detail. FusionReactor's logging mechanmism allows you to decide how many log files you want to keep and how big each log file should be but it doesn't allow you to rotate the log files every day.

It would be great to rotate the log files every day so that we can keep a record for as long as we want instead of losing data when the log files rotate automatically.

Using FRAPI (FusionReactor's API) this is easy to achieve.

Requirements

FusionReactor 3.0.1+

The Article

FusionReactor captures data about Requests, JDBC Requests, Resources, CrashProtection actions and details about itself into log files. These log files are typically placed under a log folder that can for each instance of FusionReactor. On a Windows installation the log folder might by for example:

   C:FusionReactorinstancecoldfusion.cfmx9.INT000Blog

About FRAPI

FRAPI is a powerful and easy to use API that allows you to take control of FusionReactor programatically. Using FRAPI you can change the running configuration of FusionReactor.

Here's how to instantiate the FRAPI interface in CFML. Once we have FRAPI available we are able to read this FusionReactor's configuration:

        <cftry>
            <cfset frapi = createObject("java", "com.intergral.fusionreactor.api.FRAPI").getInstance()>
            <cfset config = frapi.getRunningConfiguration()>
            <cfdump var="#config#">
            <cfcatch>
                <!--- FRAPI isn't available so FusionReactor probably isn't installed --->
            </cfcatch>
        </cftry>

Note that we always wrap FRAPI calls in a TRY/CATCH block. The reason for this is that FusionReactor may not be installed on every computer that you run the code on. The TRY/CATCH blocks will make sure that FRAPI calls will have no influence on your code even if FusionReactor isn't installed.

To try FRAPI, create a "frapiconfig.cfm" file with the CFML code above and run the page on a system that has FusionReactor installed. After the page has completed you should see a dump of FusionReactors configuration for this instance.

Once we have the configuration, we can change it and tell FusionReactor to update very easily like this:

            <cfset config.setValue("logfile", "#install_location#/instance/#instance_name#/log/#datetime#/reactor.log")>
            <cfset frapi.setRunningConfiguration(config)>

FRAPI.CFM

        <cftry>
            <cfset frapi = createObject("java", "com.intergral.fusionreactor.api.FRAPI").getInstance()>
            <cfsavecontent variable="debugData"><cfinclude template="classic.cfm"></cfsavecontent>
            <cfset frapi.trace( debugData )>
            <cfcatch>
                <!--- FRAPI isn't available so FusionReactor probably isn't installed --->
            </cfcatch>
        </cftry>

Notes

  1. Log File Sizes
    Some of FusionReactor's log files can fill very quickly. This is especially true of the JDBC log files. You need to take this into consideration when you set the log file size(s). As a counter point you have to be aware that using very large log files sizes and rotating the log files every day can very quickly use up lots of disk space. Please take care when setting the log file sizes and consider archiving or removing log files based upon there age.
  1. Log File Count
    FusionReactor lets you set the number of log files you want to keep for each log type. It's tempting to set this to a large number so that FusionReactor doesn't lose any information but you should consider that the more log files FusionReactor has to manage and rotate, the slower the log file rotate will be. I would not advise you to set the log file count higher than 20 log files. It is more advisable to balance the number of log files and the log file size. For example, of you set the log file count to 10 and the log file size to 20480 (log file size is set in KBytes) then you would create a maximum of 200MBytes of log data (for the specific log).

Fast Track

  1. Copy the frapi.rotatelogdirectoy.cfm file linked to this article to a folder where you run ColdFusion (for example): <coldfusion folder>/wwwroot/fusionreactor
  2. Create a scheduled task to run this page once per day at 00:00:00 midnight

Summary

By rotating FusionReactor's log files daily you can keep log files for as long as you want and can prevent you from losing this valuable data when FusionReactor rotates it's log files automatically when the size of the file has been reached.

Issue Details

Type: DevNet
Issue Number: FRS-237
Components: Logging
Environment:
Resolution: Fixed
Last Updated: 06/Nov/09 6:51 PM
Affects Version: 2.0, 2.0.3, 2.0.4, 3.0, 3.0.1, 3.5
Fixed Version: 3.0.1, 3.5
Server:
Platform: Windows XP, Windows 2000, Windows 2003, Linux, MacOS, Solaris, Windows Vista, Windows x64, AIX, Windows 7, Windows 2008
Related Issues:

FRS-232: Capturing ColdFusion’s Debug Output in FusionReactor