Blog

[FR-2832] How to add a FusionReactor Plugin to your FusionReactor installation

Description

Description

This article provides a set of instructions for adding FusionReactor plugins to existing FusionReactor instances and to the FusionReactor installation so that instances created in the future contain the plugin. This article provides a use case scenario, that scenario is how to add the Notification Generator plugin.

Adding a plugin to a FusionReactor instance

As mentioned in the Description this article provides a use case scenario.

1) Obtain the plugin from the FusionReactor plugins download page, click here to be taken to the page. For this scenario we would download the FusionReactor Notification Generator plugin.
2) Stop the server that contains the instance of FusionReactor that you want to add the plugin to.
3) Copy the plugin that you downloaded in step 1 into the FusionReactor instance’s plugins directory. The plugins directory is located in <FusionReactor_Home>/instance/<Instance_Name>/plugins. For this scenario it is located at C:\FusionReactor\instance\cfusion.cfmx10.HP-Pdv6-Laptop\plugins.

4) If you are running FusionReactor on a UNIX based machine (Linux, Solaris, MAC or generic UNIX) then you need to follow this step, if you are running FusionReactor on a Windows machine you can skip to step 5. When you copy over the plugin to your plugins directory, the plugin may not be owned by the same user and group as the other plugins. For example all your plugins may be owned by nobody and the plugin you downloaded may be owned by root. If your server is run as nobody then it may run into some problems in the future, so it is important that you follow this step. If it is owned by the same user and group as your other plugins then you can skip this step.

To allow the plugin to work in your environment, change the user and group of the plugin to be that of the other plugins. For our scenario this is how it would look.

Check to see if the plugin is owned by a different user and group to the other plugins.


The plugin, fr-notification-generator-plugin-1.0.0.jar, is owned by user root and group root

Change the permissions of the plugin by using the chown command.


The plugin, fr-notification-generator-plugin-1.0.0.jar, is now owned by user vmuser and group bin





5) Start your server back up and your plugin will be loaded up.
6) See Checking that your plugin has been correctly loaded into your FusionReactor environment to check if your plugin has been correctly loaded.

Configuring your environment so that the plugin is added to future FusionReactor instances

As mentioned in the Description this article provides a use case scenario.

1) Obtain the plugin from the FusionReactor plugins download page, click here to be taken to the page. For this scenario we would download the FusionReactor Notification Generator plugin.
2) Copy the plugin that you downloaded in step 1 into the plugins-deploy directory in FusionReactor. The plugins-deploy directory is located in <FusionReactor_Home>/etc/plugins-deploy. For this scenario it is located at C:\FusionReactor\etc\plugins-deploy.
3) If you are running FusionReactor on a UNIX based machine (Linux, Solaris, MAC or Generic UNIX) then you need to follow this step, if you are running FusionReactor on a Windows machine you can skip to step 4. When you copy over the plugin to your plugins-deploy directory it may not be owned by the same user and group as the other plugins. For example all the plugins may be owned by nobody and the plugin you downloaded may be owned by root. When you use FRAM to create a FusionReactor instance it copies the plugins from the plugins-deploy directory to the plugins directory of the newly created instance. If FRAM is running as nobody and the newly added plugin is owned by root then it will not be able to copy over the plugin when an instance is added. Simply change the user and group of the plugin to be that of the other plugins. Step 4 in the Adding a plugin to a FusionReactor instance section explains in detail how to do this.
4) Whenever a FusonReactor instance is created, it will come bundled with the newly added plugin.
5) See Checking that your plugin has been correctly loaded into your FusionReactor environment to check if the plugin has been correctly loaded into your newly created FusionReactor instance.

Checking that your plugin has been correctly loaded into your FusionReactor environment

1) Access the FusionReactor instance that contains the newly added plugin.
2) Navigate to Plugins > All Bundles
3) The All Bundles page lists all the FusionReactor bundles. A plugin is a bundle so it will be listed on here. Locate your bundle in the list and check that the status is listed as Active. If this is true then the plugin has successfully been loaded.
4) If your plugin is not listed as Active or it isn’t listed at all check the OSGi Log (Plugins > OSGi Log) for clues as to what went wrong. Also review all the steps you performed. It is a common mistake to add the plugin to the wrong FusionReactor instance.


The Notification Generator plugin was successfully added


How to use the Notification Generator Plugin.

See the FusionReactor Notification Generator Plugin documentation.

Issue Details

Type: DevNet
Issue Number: FR-2832
Components: Documentation
Environment:
Resolution: Unresolved
Added: 28/06/2012 15:34:18
Affects Version:
Fixed Version: 5.0.doc
Server:
Platform:
Related Issues: None

[frs-233] FusionReactor Nagios Plugin

FusionReactor Nagios Plugin

What is Nagios?

"Nagios is an enterprise-class monitoring solution for hosts, services, and networks released under an Open Source license."

Source: http://www.nagios.org, March 12th 2009

Many companies use Nagios throughout the enterprise to alert them of operational abnormalities. This plugin allows you leverage the unique monitoring capabilities of FusionReactor from within your existing Nagios environment.

Nagios Exchange

Plugin Details

This is a Perl plugin for the Nagios monitoring system to allow monitoring of your J2EE application through the FusionReactor software.

You can monitor & track high level metrics (instance CPU, heap memory, JDBC calls, average request time, etc) from within Nagios. If/When an issue is alerted from Nagios, you can use FusionReactor to investigate further.

Monitoring ColdFusion with Nagios

FusionReactor can monitor any type of J2EE server. ColdFusion runs on a J2EE server meaning that you can monitor your ColdFusion application with Nagios using FusionReactor and this plugin.

You can also monitor your Railo server with Nagios or OpenBD (Open BlueDragon) using this Nagios plugin.

Requirements

System to be monitored (J2EE server)

  • FusionReactor Enterprise Edition

Monitoring Host (Nagios server)

The following modules can easily be installed via CPAN. Further instructions are available in the documentation:

  • Nagios::Plugin
  • File::Basename
  • LWP::UserAgent
  • Digest::MD5
  • MIME::Base64
  • XML::XPath
  • XML::XPath::XMLParse

Latest Version

Latest Stable: Nagios Plugin 1.0

Download
Documentation

Changelog

1.0 – Initial release

Issue Details

Type: DevNet
Issue Number: FRS-233
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: 25/Aug/15 4:32 PM
Affects Version:
Fixed Version: 1.0, 2.0, 2.0.3, 2.0.4, 3.0, 3.0.1, 3.5, Pending
Server:
Platform: Windows XP, Windows 2000, Windows 2003, Linux, MacOS, Solaris, Windows Vista, Windows x64, AIX, Windows 7, Windows 2008
Related Issues:

[frs-334] Railo Extension for FusionReactor v5

About

This is a Railo Extension store plugin to simplify deployment of the FusionReactor server monitor.

What does the extension do?

  • Email a trial license to the installer
  • Deploy latest version of FusionReactor (or fall-back to the bundled version for servers with no direct internet access)
  • Automatically update container JVM arguments
  • Offer an uninstall option

Supported Platforms / System Requirements

For the FusionReactor software system requirements, please see https://www.fusion-reactor.com/system-requirements/.

The extension should function in all recent Railo releases but has been most thoroughly tested with Railo 4.1.2.005 final (Endal) using both the Tomcat and Jetty (aka Railo Express) deployments on Windows Server 2012 and CentOS 6.5 64-bit.

Help Videos

http://www.youtube.com/playlist?list=PLDIpVdHiiEMdxsppX-EpS9dFpZdGM3_hn

Issue Details

Type: DevNet
Issue Number: FRS-334
Components: Installer, Instance Manager
Environment:
Resolution: Fixed
Last Updated: 13/Mar/14 3:35 PM
Affects Version:
Fixed Version: 5.0.0
Server:
Platform:
Related Issues:

FusionReactor v5 Java Server Monitor – A feature tour

A 20 minute feature tour of FusionReactor v5 visiting:

  • Enterprise Dashboard
  • Web Metrics
  • Real-Time Running Request List
  • Request History
  • Request Details
  • CPU Thread Time
  • TCP/IP Stream Metrics
  • HTTP Headers
  • JDBC Transactions
  • HTTPClient/WebService Transactions
  • Longest Requests (since server started)
  • Slowest Requests (recent pages longer than threshold)
  • HTTP 500 Server Error Details
  • User Experience Monitoring (UEM) (e.g. client network & browser rendering time)
  • Custom Transactions (e.g. tracking custom API calls)
  • Custom Metrics (tracking custom business metrics – e.g. revenue)
  • Custom Dashboard (e.g. revenue vs page execution time chart)
  • Metric History (e.g. CPU last hour/day/week; pan/zoom; etc)
  • Both Heap & Non-Heap Memory Spaces (e.g. PermGen)
  • Garbage Collection Timing
  • Thread State Charts (e.g. identifying locking contention)
  • EnGuard Crash Protection (e.g. alerts before failure or prevents server from failing)
  • Daily Report Email (e.g. managers don’t need to login for overview metrics)
  • Log rotation & archiving (including JVM logs)
  • Info/Warn/Error Notification system
  • Desktop, iOS, Android dashboard application
  • Stack trace running request (e.g. see what line of code is currently being executed / where a slow page is stuck)

[frs-228] Using FusionReactor’s JDBC Driver Wrapper With ColdFusion 9 ORM

Using FusionReactor's JDBC Driver Wrapper With ColdFusion 9 ORM

FusionReactor's JDBC Driver Wrapper is a great addition to ColdFusion 9's Object-Relational Modeling capabilities. You can use it to spy on what Hibernate (ColdFusion's ORM provider) is really doing to your database.

This article doesn't go into detail about what ORM is, or how it works – there are many posts and articles on the web which cover this in detail:

Why Use the JDBC Driver Wrapper in Your ORM Configuration?

Adobe's integration of the third-party Hibernate framework brings ORM functionality to your CFC-based applications. This brings with it some new, important concerns for ColdFusion developers:

  • How is Hibernate converting my entity operations to SQL?
  • Why are they running so slowly?
  • How is Hibernate locking the DB?

You can use the setting Application.cfc setting this.ormsettings.logSQL to have Hibernate dump its SQL to the log as it's created, but you'll soon find the log is overflowing with data.

  • FusionReactor's JDBC Driver Wrapper associates your queries with the precise request – and ultimately CFC/CFM line of code – in which they run.
  • You can use the JDBC tab in FusionReactor's Request View to see what ran, how long it took, and how many rows came back – great for tuning and catching runaway queries.

How Do I Set This Up?

Getting this working is simple, just follow the steps below.

Get FusionReactor

  • Download and install FusionReactor – you'll need version 3.5.0 or better. You can get a 10-day free trial here.

Use FusionReactor's JDBC Driver Wrapper

  • You'll need to create a wrapped datasource. This won't replace your original datasource, but it will allow our lightweight wrapper to spy on he interaction between ColdFusion, Hibernate and the database.
  • You can use the instructions in the FusionReactor JDBC Driver Wrapper User Guide, or download and use our free tool (just run the tool and have it wrap your datasource automatically).
  • Once you've got a wrapped datasource, change your ORM datasource in Application.cfc to point to the new datasource.
	this.datasource = "orm_WRAPPED";

.. for example.

That's it!

Spying on Hibernate

Once you've installed the FusionReactor JDBC Driver Wrapper, and adjusted your Application.cfc to point to the wrapped datasource, you can have a look at the collected data. We ran the 01_createmusician.cfm script from Mark Mandel's introductory app (from Introducing ORM in Adobe ColdFusion 9), with this.ormsettings.logSQL = true turned on in our Application.cfc.

What came out in the log was:

Hibernate: 
    insert 
    into
        Musician
        (name, age) 
    values
        (?, ?)
Hibernate: 
    select
        currval('Musician_musicianID_seq')

But that's not only what ran – the log isn't showing you everything. Inspecting the JDBC tab of the request in FusionReactor actually shows us exactly what's going on:

There's actually a whole bunch of overhead. We turned on "Record In Order" in FusionReactor's JDBC Settings, so this list is in time order – including a whole set of alters, drops, creates (JDBC transaction 1), then the load of sample data (transactions 2 and 3), the actual insert from the CFM page itself (transactions 4 and 5), and the select from the page for the dump (transaction 6).

Conclusion

We think FusionReactor's JDBC Driver Wrapper is an awesome tool to spy on exactly how Hibernate and ColdFusion 9 is interacting with your database. Object-Relational Modeling is going to revolutionize how you deal with your databases, and FusionReactor is going to make your life easier in analyzing and solving problems.

Issue Details

Type: DevNet
Issue Number: FRS-228
Components: JDBC
Environment:
Resolution: Fixed
Last Updated: 08/Sep/11 10:50 AM
Affects Version:
Fixed Version: 3.5, 4.0.0
Server:
Platform:
Related Issues:

[frs-300] FusionReactor Wrapper Tool for FusionReactor 4.5.x and above

JDBC Wrapper Tool for FusionReactor 4.5.x and above

Users using FusionReactor 4.0.10 or lower should use the original wrapper found here.

The JDBC tool is designed to provide an automated interface to configure the FusionReactor JDBC Wrapper. The tool uses the CF admin API introduced in CF7 to add/update your DSN entries. Once installed, the JDBC wrapper doesn't break if your FusionReactor license expires (trial or subscription).

Note: The tool is still under active development. Though we have used this succesfully we cannot guarantee it will function in all cases. Please check below for our tested compatibility chart.

Requirements

FusionReactor
CF7 or above OR A Compatible CFML Engine

Latest Version

The latest versions available for download are:

Latest Stable: 1.0.1
jdbc_tool_v1.0.1.zip

Usage

FusionReactor 4.5.x now supports a classpath option in the JDBC URL. For non-macromedia drivers (those that previously required the split-jar method) you can supply the path to your JDBC driver jar file and FusionReactor will function correctly. The split-jar method has been completely removed with FusionReactor 4.5.x and so users are required to perform this update.

  1. Download the updated FusionReactor Wrapper Tool
  2. Copy the fr_jdbc_wrapper.cfm file to /CFIDE/administrator/fr_jdbc_wrapper.cfm on your server, ensuring you have permission to run it.
  3. Navigate to this page via your browser.
    • If you have any wrapped data sources from older versions of this tool, you should unwrap them now. Click the "Unwrap" link at the top left and continue though the steps of the tool.
  4. Select the data sources you wish to wrap.
  5. If a text field is visible in the "Driver Jar" column then you are required to supply a canonical path to the JDBC driver jar file. EG:
    • CF10: C:ColdFusion10cfusionlibmysql-connector-java-commercial-5.1.17-bin.jar
    • CF9 Multi-server: C:JRun4libmysql-connector-java-commercial-5.0.5-bin.jar
    • CF9 Stand-alone: C:ColdFusion9libmysql-connector-java-commercial-5.1.11-bin.jar
  6. You can click the "Use for all of this type" checkbox to use the same driver file for all data sources of that type (e.g. all MySQL data sources). This is not recommended for Derby data sources.
  7. Once you have entered the correct paths to your driver jars, click next and navigate through the rest of the tool to wrap your data sources

Compatibility Notes

Railo

  • There is an additional requirement for Railo. Please (temporarily, whilst running the tool) set the Server Administrator->Security->Access->General->Access Read setting to "open".

Tested Compatibility

Adobe CF 7,0,2,142559

  • Microsoft SQL Server
  • ODBC Socket

Adobe CF 8,0,1,195765

  • Apache Derby Client
  • Microsoft SQL Server
  • MySQL (4/5)
  • Apache Derby Embedded (Requires CF Restart)
  • ODBC Socket
  • PostgreSQL
  • Other JDBC Driver
  • Sybase

Adobe CF 9,0,0,251028

  • Apache Derby Client
  • Microsoft SQL Server
  • MySQL (4/5)
  • Apache Derby Embedded (Requires CF Restart)
  • ODBC Socket
  • PostgreSQL
  • Other JDBC Driver
  • Sybase

Adobe CF 10

  • Apache Derby Client
  • Microsoft SQL Server
  • MySQL (4/5)
  • Apache Derby Embedded (Requires CF Restart)
  • Other JDBC Driver

Railo 4.0.4.001

  • MSSQL – Microsoft SQL Server (Vendor Microsoft)
  • MSSQL – Microsoft SQL Server (Vendor jTDS)
  • MySQL

Issue Details

Type: DevNet
Issue Number: FRS-300
Components: JDBC
Environment:
Resolution: Fixed
Last Updated: 01/Jul/13 12:56 PM
Affects Version: 4.5.0
Fixed Version: 4.5.0
Server:
Platform:
Related Issues:

Announcing Ortus ProfileBox – a ColdBox profiling / monitoring extension for FusionReactor 5

profilebox logo Ortus ProfileBox is a ColdBox module that will provide you with profiling, metrics, CacheBox reports, custom object metrics, exception notifications, LogBox integration and much more for any ColdBox 3.5 application.

ProfileBox is available for FusionReactor 5.x – for more details go here – www.goprofilebox.com/

Capabilities

  • Profile and take metrics of any ColdBox Event including ability to trace hierarchical executions, renderings and handler results
  • Profile ColdBox User Experience metrics from time spent in ColdBox code, to Client Code to Network time
  • Profile rendering of any layout or view
  • Ability to trace the request collections via any ColdBox event requested
  • Ability to profile any WireBox-managed object via our very own method and component annotations
  • LogBox appender for creating FusionReactor notifications
  • LogBox appender for creating FusionReactor request tracers
  • WireBox mappings for interacting with FusionReactor tracers and notifications a-la-carte
  • Ability to profile all caches monitored by CacheBox
  • Exception handling that can send your exceptions to the FusionReactor Notifications

[frs-239] Automatically login to FusionReactor with a Cookie

Background

FusionReactor provides several user roles each allowing a different set of actions. The Observer role allows users view only access to the metrics FusionReactor is gathering.

In some organisations, it could be beneficial to allow users to automatically login as the Observer user. This can be achieved by setting a cookie on the client browser – this process is shown here.

Process Overview

  1. Find the Cookie



    • Login to FusionReactor in the normal way
    • Find the cookie in your browser / debugging-proxy
    • Save this information for later



  2. Logout of FusionReactor



  3. Create a login portal page




    Note: This page must be able to write cookies to the same (or parent) domain name



  4. Test

Screencast / Video How-To

@video(FRscreencast.jpg,fr_autologin4.swf,640,498)

Sample Code

autologin.html
<html>
	<head>
		<title>FusionReactor Auto-Login</title>
	</head>
	<body>
		<script type="text/javascript">
			document.cookie =
				'FusionReactorAuthorization.cfusion.jrun4.DJS02WORK3' +
				'=' +
				'Administrator:E69315267C51BB306D16D719107C832A' + 
				'; expires=Sat, 1 Jan 2011 00:00:00 UTC; path=/';
			window.location = 
				'http://localhost:8088/fusionreactor/';
		</script>
	</body>
</html>

Issue Details

Type: DevNet
Issue Number: FRS-239
Components: FusionReactor Settings
Environment:
Resolution: Fixed
Last Updated: 20/Nov/09 2:52 PM
Affects Version: 3.5
Fixed Version: 3.5
Server:
Platform:
Related Issues:

[frs-271] Understanding FusionReactor’s Timeout Protection

Introduction

We're sometimes asked about the timings for FusionReactor's Timeout Protection, part of the Crash Protection system. The idea behind this crash protection is that it places a hard upper limit on the length of time requests can run. You might find, however, that requests take a few seconds longer to be killed than you originally thought. Here's why.

Kill Strategies

After the time limit is reached, three strategies are employed by the Request Assassin to kill the request:

  • Soft Kill
    If the request makes any output to the page whatsoever, it will be killed. This is done by intercepting the call which writes data back to the network. The Request Assassin waits for 2 seconds for the request to write output, before trying the next strategy.
  • Interrupt
    We interrupt the thread in which the request runs. If the request is performing an interruptible operation (a call which can throw InterruptedException; sleeping, for instance), the exception will be raised. The Request Assassin waits for 1 second for the thread to process the interrupt – if it does so at all – before trying the final strategy.
  • Thread Stop
    The request is forcefully stopped by Java's thread stop mechanism. Although this isn't completely reliable – threads performing native operations will not be stopped, for instance – it works most of the time, and in fact there is no other way to kill a thread.

The Request Assassin

In addition to these delays, the Request Assassin doesn't run all the time: it wakes up every second, and checks whether there are any threads it should examine. If there are any, it starts to process them, employing the strategies above. If a strategy succeeds, it moves on to the next candidate. If not, it tries the next strategy, until the list of strategies is exhausted.

Because FusionReactor attempts to place as little load on the target system as possible, the candidates for kill are queued up. This is an additional source of delay – previous kill operations may have to be processed before the Request Assassin gets to the request of interest.

Worked Example

Let's look at a worked example, with Timeout Protection set to 1 second.

In the diagram, you can see (starting from the top timeline):

  • The flow of a request (blue).
  • The best possible timing of a crash protection (red).
  • The worst possible timing of a crash protection (red).

Best Possible Scenario

  • The Request Assassin wakes up at time T1 – the exact instant the request becomes eligible for kill. It immediately sets the Soft-Kill flag, and starts the soft kill delay, 2 seconds.
  • At time T3, the soft-kill delay expires, and the request is still alive, having not performed output. The thread is interrupted, and the Request Assassin waits for a further second.
  • At time T4, the request is still alive, so the Request Assassin performs a thread kill.

The request then dies, marked by the first red "X" in its timeline. If the request was performing native operations (i.e. using part of the Java language that's written in C), it will be killed as soon as it returns. One common native operation is blocking socket communication: this is performed in Java by a C library.

Worst Possible Scenario

The second timeline is much the same as the first, except the Request Assassin ran at time T0.9r, i.e. an instant before the request became eligible for kill at T1. The next time the Request Assassin runs is at time T2 (actually an instant before that), meaning the whole timeline starts 1 second later, at time T2, and completing with the kill at time T5.

Conclusion

We showed in this small article where the (up to) 3-second overhead in Timeout Protection comes from: a combination of soft-kill and interrupt delays, which allow us to try to stop a request without resorting to a hard kill.

Issue Details

Type: DevNet
Issue Number: FRS-271
Components: Crash Protection
Environment:
Resolution: Fixed
Last Updated: 22/Sep/11 3:36 PM
Affects Version:
Fixed Version: 4.0.0
Server:
Platform:
Related Issues:

[frs-232] Capturing ColdFusion’s Debug Output in FusionReactor

Capturing ColdFusion's Debug Output in FusionReactor

It would be great if you could capture the debug data from every page run but hide it away from the user so that they don't even see it. It's easy to do this with FusionReactor.

ColdFusion's powerful debug data output feature that lets you see lots of useful debugging information about the page run. Unfortunately the data is lost as soon as you run the next page in the browser window/tab and is only visible to the user that ran the page.

Requirements

FusionReactor
FusionDebug

The Article

We're all familiar with ColdFusion's debug output at the end of a CFML page. Many CFML programmers use it as the primary way of debugging CFML code.

There are a few problems with the way that debug data is made available to us however such as the fact that the only user that can see the debug output is the user that ran the page. This is even more of a problem if you want to see the debug data but don't want to scare the user that ran the page. Of course it's possible in CF to restrict the IP addresses that generate debug output but sometimes you want to be able to see the debug output from other users without them seeing it. It's easy to do with FRAPI.

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 or add extra debugging information to requests using just a few lines of code.

Here's how to instantiate the FRAPI interface in CFML. Once we have FRAPI available we add extra information to a request data recorded in FusionReactor using FRAPI's trace() function:

      	<cftry>
            <cfset frapi = createObject("java", "com.intergral.fusionreactor.api.FRAPI").getInstance()>
            <cfset frapi.trace( "Hello FRAPI!")>
            <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 "frapitest.cfm" file with the CFML code above and run the page on a system that has FusionReactor installed. After the page has completed go into FusionReactor's Request History, select the Request Details for the request and click on the Markers tab to see the "Hello FRAPI!" message. Cool no? FRAPI tracks messages on the request as soon as trace() is called so it's possible to see the trace() statements in the Markers tab updating as a page is being run!

So how would we capture CF's debug output? We don't want to add FRAPI code to every page that we write that's for sure. We need to understand how ColdFusion's debug output is done to know how to capture it.

When enabled, CF Debug output is appended at the end of the page output by rCF running a "Debug Output Formatting" template. This is simply a piece of CFML code to that formats the debugging information into HTML. What's even better is the fact that the you can write your own and tell ColdFusion to use your template instead of the default one. So what if we wrote a CF Debug Template that simply calls FRAPI and adds that debug data to the FusionReactor Request using trace() calls? This means that the information would be available in FusionReactor but the user wouldn't even know that debug output was enabled because the FRAPI trace() calls don't output anything. It's that easy! Ok, there is always a but…

…but I don't know how to access all of this CF Debug Data and for sure it's complex, right?

The CF Debug data structures are fairly complex and very powerful but this is reason that few people ever write there own CF Debug Formatting template. The good news is we don't need to know anything about it due to a powerful CFML tag called <CFSAVECONTENT>. I know that the advanced CFML programmers out there just went… "OK, I get it…", but for the rest of us let's go into a little more detail on how we can do this.

<CFSAVECONTENT> is a tag that allows the programmer to capture output into a variable instead of sending it back to the user. Using <CFSAVECONTENT> we can capture the output from the classic CF debugging template into a variable and then simply call FRAPI's trace() function passing that variable as the information to record! Easy!

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>

All we have to do now is add our FRAPI Debug Template (frapi.cfm) to the CF debug templates by simply copying it folder where debug templates are placed, typically <coldfusion folder>/wwwroot/WEB-INF/debug.

Finally we have to Enable Request Debugging Output and select our new ("frapi.cfm") template as the Debugging Output Format in the ColdFusion Administrator -> Debug Output Settings page.

The next time you (or anyone) runs a CF page FusionReactor will capture the Debug data for the page. To see the data simple go to the FusionReactor->Request History, select the Request Detail for the request and then click on the Markers tab to see the CF Debugging Data for the page.

Notes

  1. Performance
    ColdFusion pages run slower when debugging is enabled and on some applications enabling CF Debug Output can seriously impact the performance of the server. You should test this on your applications before enabling debugging a production server.
  2. Memory
    FusionReactor will record the debug output on each request that it keeps in it's request history. This will use some memory; for example, if you have a Request History size of 100 requests and the average debug output data size is 20Kbytes then FusionReactor will use 2Mbytes of memory to
    record the debug data.
  3. Data
    The amount of debug data recorded is controlled via the settings on the Debug Output Settings page and the classic.cfm debug formatting output template. The data will not be added to FusionReactor until the page completes because this is when CF calls the Debug Output Formatting page. The
    debug data captured will honor any Debugging IP Address restrictions that you configure in the CF Administrator.

Fast Track

  1. Copy the frapi.cfm file linked to this article to your ColdFusion Debug Formatting Template folder (typically): <coldfusion folder>/wwwroot/WEB-INF/debug
  2. Select Debugging Output Format: "frapi.cfm" in the ColdFusion Administrator -> Debug Output.
  3. Enable Request Debugging Output in the ColdFusion Administrator->Debug Output Settings Settings
  4. Run a CF page.
  5. In FusionReactor->Request History select the Request Detail for the request and then click on the Markers tab to see the CF Debugging Data from the page.

Summary

FRAPI is a powerful way to capture extra debugging information on requests and makes FusionReactor a powerful platform for debugging on both development and production servers.

Issue Details

Type: DevNet
Issue Number: FRS-232
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: 03/Nov/11 3:36 PM
Affects Version: 2.0, 2.0.3, 2.0.4, 3.0, 3.0.1, 3.5
Fixed Version: 2.0.3, 2.0.4, 3.0, 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

FRS-280: Setting VM Options via FRAPI