Need hosting?

Who better to host your systems than the SeeFusion guys? Webapper's unparalleled ColdFusion/CFML expertise is now available in the form of fully-managed hosting services in the Amazon cloud.

Need support?

We're a one-stop-shop for any of your ColdFusion/Lucee support needs, from tuning and troubleshooting to infrastructure upgrades, and also including full lifecycle application development.

Contact Info

For SeeFusion support, please contact us via live chat with any questions you have (be sure to leave your email address for best service).

Overview

The basics of how SeeFusion works.


SeeFusion provides detailed monitoring and troubleshooting information about Adobe ColdFusion and Lucee servers. SeeFusion tracks a variety of metrics, including active, recent and slow requests and queries, request and query bottlenecks, memory utlization levels, and more.

Since this information is most useful when a server has appeared to stop responding, SeeFusion is designed to be accessed in an "out-of-band" fashion, by a browser or xml-aware process establishing a connection to a non-standard server port (e.g. port 8999).

In addition, SeeFusion Enterprise displays information about multiple servers in a convenient "dashboard" view, to allow for easily monitoring the status of large numbers of servers at once. The Enterprise edition also features a database logging system, allowing you to save metrics to a database for later analysis.

SeeFusion collects its data though two methods; first, a Java-standard "servlet filter" tracks the requests that are currently running. Second, a Java DataBase Connectivity (JDBC) driver "wrapper" tracks the queries that are executed by that request. SeeFusion attempts to be as non-intrusive as possible by adding as little processing overhead as possible. It is our belief that the value SeeFusion adds to the management of ColdFusion servers greatly exceeds the almost-undetectable overhead that SeeFusion adds.

Installation

Installation options below.


There are 3 main steps to getting up and running with SeeFusion:

  1. Install SeeFusion.
  2. Configure query monitoring (JDBC wrapper).
  3. Configure datbase logging (Enterprise only).
The sections below provide detailed instructions on steps 1 and 2. For step 3, see the "Database Logging" tab of the Configuration section below.

There are two very simple ways to install SeeFusion on a Lucee server:

  • Command-line installation.
  • Manual installation.

Command Line

  1. Download seefusion5.jar.
  2. Open a command-line window and run the following command: java -jar seefusion5.jar
  3. Follow the instructions in the installer window that appears.
  4. Restart the Lucee service.

Notes:

  • Depending on the setup of your server, you might be able to double-click seefusion5.jar in order to launch the installer window (instead of using the command line).
  • If you get an error using the command line, you may have to use full paths, like this: /path-to-java-directory/java -jar /path-to-download-directory/seefusion5.jar
  • If you have problems running the installer, you can just follow the simple manual installation instructions below.

Manual

  1. Download seefusion5.jar.
  2. Copy seefusion5.jar to {luceeRoot}/tomcat/lib
  3. Edit {luceeRoot}/tomcat/conf/server.xml, adding the following text right after the first <Engine name="Catalina" ...> entry, like this:
    <Engine name="Catalina" defaultHost="localhost" jvmRoute="cfusion">
    <!-- The next line starts SeeFusion -->
    <Valve className="com.seefusion.SeeFusionValve"/>
  4. Restart Lucee.

There are two very simple ways to install SeeFusion on an Adobe ColdFusion server:

  • Command-line installation.
  • Manual installation.

Command Line

  1. Download seefusion5.jar.
  2. Open a command-line window and run the following command: java -jar seefusion5.jar
  3. Follow the instructions in the installer window that appears.
  4. Restart the ColdFusion service.

Notes:

  • Depending on the setup of your server, you might be able to double-click seefusion5.jar in order to launch the installer window (instead of using the command line).
  • If you get an error using the command line, you may have to use full paths, like this: /path-to-java-directory/java -jar /path-to-download-directory/seefusion5.jar
  • If you have problems running the installer, you can just follow the simple manual installation instructions below.

Manual

For ColdFusion 10 and later:
  1. Download seefusion5.jar.
  2. Copy seefusion5.jar to {cfRoot}\cfusion\runtime\lib
  3. Edit {cfRoot}\cfusion\runtime\conf\server.xml, adding the following text right after the first <Engine name="Catalina" ...> entry, like this:
    <Engine name="Catalina" defaultHost="localhost" jvmRoute="cfusion">
    <!-- The next line starts SeeFusion -->
    <Valve className="com.seefusion.SeeFusionValve"/>
  4. Restart ColdFusion.
For ColdFusion 9 and earlier:
  1. Download seefusion5.jar, and place a copy in {ColdFusionRootDirectoryt}\cfusion\wwwroot\WEB-INF\lib. (Note: Your ColdFusion instance's root directory may be something other than the default "cfusion.")
  2. Edit {ColdFusionRootDirectoryt}\cfusion\wwwroot\WEB-INF\web.xml, entering the following XML snippet before the first block:
    <filter>
    <filter-name>SeeFusion</filter-name>
    <filter-class>com.seefusion.Filter</filter-class>
    </filter>
    <filter-mapping>
    <filter-name>SeeFusion</filter-name>
    <url-pattern>/*</url-pattern>
    </filter-mapping>
  3. Restart the ColdFusion service.

Once the installation steps are completed (and ColdFusion/Lucee has been restarted), SeeFusion will begin monitoring requests. Note that SeeFusion will still monitor requests even if the JDBC wrapper has not been configured for any datasources, but query information won't be reported in SeeFusion's output without the wrapper. You must apply the SeeFusion JDBC "wrapper" to any datasources whose queries you want SeeFusion to monitor. The easiest way to do this is to follow these steps:

  1. Create a new datasource in the ColdFusion Administrator using the "other" option from the "Add New Data Source" drop down on the main Data Sources page. This will expose the "JDBC URL" and "Driver Class" fields on the Data Source add page, which are needed for configuring the SeeFusion wrapper.
  2. Enter your database's JDBC URL in the JDBC URL field.
  3. Once your original datasource's JDBC URL is in the JDBC URL field, you'll need to wrap the SeeFusion driver around it. Some example syntax is as follows:
    Original SQL Server datasource:
    jdbc:macromedia:sqlserver://127.0.0.1:1433; databaseName=SampleDS; SelectMethod=direct; sendStringParametersAsUnicode=false; MaxPooledStatements=1000;
    SeeFusion datasource:
    jdbc:seefusion:jdbcwrapper:{jdbc:macromedia:sqlserver://127.0.0.1:1433; databaseName=SampleDS; SelectMethod=direct; sendStringParametersAsUnicode=false; MaxPooledStatements=1000};
    (Note: You may need to experiment with the syntax for your particular datasource.)
  4. Enter com.seefusion.Driver in the Driver Class field.
  5. If necessary, enter any other needed information, such as username/password, etc.
  6. Save the new, SeeFusion-wrapped datasource.
  7. Point your application to the SeeFusion datasource, either by changing the datasource name inside your application (to the name you gave to the new SeeFusion datasource), or by renaming your original datasource in ColdFusion/Lucee Administrator, and giving the new SeeFusion datasource the name used by your application.

Note: When the SeeFusion JDBC driver is first loaded, you will see the following message written to the standard output log:
seefusion.Driver: Loaded and in use.

Configuration

Review your configuration options.


We've designed SeeFusion to be as easy-to-use as possible, and we've also included more/better on-screen help text. Below is some additional information about each of the screens in the Configuration section of SeeFusion. If you have questions that aren't answered here, or inside SeeFusion, then just send us your question and we'll get it answered quickly.

Parameter

Default

Description


enabled
On
Turns request monitoring on or off. When off, all page information, logging events, and counters will be lost. Note that this does not disable the database driver wrapper; SeeFusion-wrapped datasources will continue to function normally.

name
{hostname}
Use this parameter to specify a display name of your choosing. This name is displayed at the top of the SeeFusion console in the first pod on the left (e.g., "Server: DisplayName"), and in the Name column of the SeeFusion Enterprise dashboard display. Also, this is the value that will be entered in the database column "FilterName", if you have database logging enabled. Use the value "{hostname}" (without quotes) to have SeeFusion attempt to discover and use the local machine hostname.

maxRequests
15
This parameter is used solely for the sizing of the real-time charts at the bottom of the Server screen. (Note: It does not relate at all to the simultaneous threads setting in the ColdFusion Administrator.

browserURL
(Enterprise only)
none [i.e., no link in dashboard]
In the Enterprise dashboard, each server's name (specified by the name parameter above) can be displayed as a hyperlink to the SeeFusion console for that server. This server name link in the dashboard display will open in a new browser window, which allows you to keep the dashboard open (and refreshing), while at the same time "drilling down" to an individual server to get more detailed information on that server. In order for the dashboard to display a server's name as a link, the browserURL parameter must be set in that server's configuration settings. For example, to set ServerA's name as a link on whichever dashboard display is monitoring that server, then go to the SeeFusion configuration screen for ServerA and set the browserURL parameter to the SeeFusion URL for ServerA.

Example:
http://ServerA:8999/
or
http://www01.mycompany.com:8999/

listeners
all:8999
To get information from SeeFusion, it must be configured to "listen" for connections on one or more IP addresses. This parameter specifies a space-delimited list of IP addresses (and port numbers) where you want SeeFusion to bind and listen to, using the standard {ip}:{port} syntax. The IP addresses listed must be associated with one of the server's network interfaces or an "Unable to start listener" error will be logged. Instead of an IP address you can also type the word "all" to listen on all IP addresses associated with all of the server's network interfaces. If a port is not specified for an IP address, then SeeFusion will attempt to listen on port 8999.

Examples:
all:8999
or
localhost 192.168.5.5:1111

license
none [free/evaluation mode]
Once a license key is purchased, you will install it using this parameter. If no license is specified, then SeeFusion will work with full Enterprise edition functionality for for two hours after each time the ColdFusion/Lucee service is restarted, and then will stop providing information upon timeout.

Note: The easiest way to enter your license key is simply to paste it into the configuration interface field in the block format in which it arrived via email. If you enter the key directly into the seefusion.xml properties file, the key must be entered on a single line, or, if entered directly into the file in block format, then each line must begin with an escape character ("\"). We recommend that you do NOT enter your license key directly into the seefusion.xml properties file.

jdbcDrivers
none
A space-delimited list of JDBC drivers to preload, if they're used by your application. Example:

"oracle.jdbc.driver.OracleDriver com.informix.jdbc.IfxDriver"

If you don't specify driver names here, you'll have to add ";driver=driver.class.name" to the end of every SeeFusion-wrapped JDBC URL.

Parameter

Default

Description


httpConfigPassword
none
Setting this parameter allows you to control access to SeeFusion's configuration screen. If you set a value for this parameter, then the "Configuration" menu item at the top of the SeeFusion screen will be disabled unless you login using the httpConfigPassword.

Note: The SeeFusion passwords are meant to be configured in "layers." If you set an httpPassword (below), but do not set an httpConfigPassword, then you will be locked out of the configuration screen entirely. If this happens, go into the seefusion.xml properties file, and manually set an httpConfigPassword. You can set it to blank ("httpConfigPassword=") to remove the password entirely, or to be the same as the httpPassword, or different, depending on how you want to control access to SeeFusion. DO NOT remove the entry entirely; just set it to blank if you'd like to remove that password. If you want to set passwords to control access to SeeFusion, start by setting an httpConfigPassword. Then you can set the httpPassword and httpKillPassword to be the same, or different, depending on whether you want a single security role, or multiple roles (e.g., separate roles for access, configuration, and kill functionality, which would require 3 distinct passwords).

httpKillPassword
none
If an httpKillPassword is set, and a user logs in with that password, then kill buttons will appear for running requests. Otherwise, they will not appear. If no httpKillPassword is set, then all users will see kill buttons, and can kill requests.

httpPassword
none
This parameter controls access to the SeeFusion display. If an httpPassword is set, users will see a login screen prior to the SeeFusion console loading.

If you're using an ipWhitelist, a user must be coming from a whitelisted IP to get the login screen; non-whitelisted IPs will have no access to SeeFusion (regardless of any password settings).

ipWhitelist
none
This is a space-delimited list of IP addresses or network blocks that are allowed to connect to SeeFusion. If an entry ends with a period, then the connecting IP will be matched up to that period. For example, the entry "192.168." will match any IP address that begins with "192.168.", and an entry "192.168.5.11" would match only that exact IP address.

Parameter

Default

Description


historySize
50
If desired, SeeFusion will track recently-completed request metrics, and will display these metrics on the Recent Requests tab of the main server screen. Use this parameter to specify how many requests you want to keep in this history. Once this list is full, the oldest (not the slowest) entry is removed from the list as new entries are added. Note that this request history does NOT persist following a ColdFusion/Lucee restart. (Saving request information to a database for later analysis is an Enterprise-only feature.)

slowHistorySize
50
This parameter specifies how many "slow" requests to store on the Slow Requests tab (if slowPageThreshold below is set). Once this list is full, the oldest (not the slowest) entry is removed from the list as new entries are added. Note that this request history does NOT persist following a ColdFusion/Lucee restart. (Saving request information to a database for later analysis is an Enterprise-only feature.)

slowPageThreshold
8000 [8 seconds]
If desired, SeeFusion will track information for requests that run longer than this threshold, and display that list on the Slow Requests tab of the main server screen. The setting is specifed in milliseconds.

This parameter is used to determine when the colored indicators are red/yellow/green in the Requests pod (top middle pod). You can use this parameter to control how frequently the colored slow requests visual alerts are displayed in the Requests pod. The indicators turn yellow when average request times reach 90% of the specified threshold, and red when they reach 98%.

slowQueryThreshold
1000 [1 second]
This parameter is used to determine when the colored indicators are red/yellow/green in the Queries pod (top right pod). You can use this parameter to control how frequently the colored slow query visual alerts are displayed in the Queries pod. The indicators turn yellow when average query times reach 90% of the specified threshold, and red when they reach 98%.

historyIgnoreSuffixList
none
Space-delimited list of filenames or file extensions never to show in the "Recent Requests" and "Slow Requests" lists. This affects both the HTML and XML SeeFusion data, but does not affect the "Active Requests" tab (which always shows all requests), and does not affect the database logging of long-running requests (if enabled).

displayRelativeTimes
off
Set to "On" to see relative times, "Off" to see absolute date/time stamps (using the time at the SeeFusion console). This only applies to the "Completed" column of Recent and Slow tabs; SeeFusion XML dumps are unaffected.

clickableURLs
off
When enabled, request URLs are clickable links in the Active, Recent and Slow tabs. Click the green arrow next to any request to open that URL in a new browser window.

clickableIPURLs
off
This parameter is used to configure an IP address lookup service, for quick lookups of the source IP address of a given request (in the From column of the Active/Recent/Slow tabs). For example, if you enter "http://whatismyipaddress.com/ip/" (no quotes), then SeeFusion will prepend this address to the IP address in the From column, and a globe icon will appear next to the IP address, and clicking the globe icon will open this particular lookup service in a new window. Just enter your favorite IP lookup tool in the correct format for that tool.

Parameter

Default

Description


dashboardServers
(Enterprise only)
none
The SeeFusion Dashboard will display a list of servers in a one-row-per-server format, which makes it easy to monitor the health of many servers. Servers that have running requests but no throughput will be listed as "SLOW" (highlighted in yellow), then "DOWN" (highlighted in red) if the situation persists. Servers with low memory, or almost no memory will have a "MEM" flag highighted in yellow, then red if the situation persists.

In order to configure a dashboard, choose one of your SeeFusion instances, go to that instance's configuration screen, and enter the server names, separated by spaces, of each of the servers (with SeeFusion Enterprise installed) that you want to display in the dashboard. You can also display the dashboard server itself (i.e., enter "localhost"). Note: All servers either displaying or being displayed in a dashboard require an Enterprise license.

The dashboard is accessed by clicking the Dashboard menu item in the SeeFusion console.

Example entry:
www01 www02 www03 www04
or
localhost serverA serverB:7999

The port number only needs to be specified for SeeFusion instances that are listening on a port other than 8999 (e.g., "www01:7999").

dashboardMinSlowRequests
(Enterprise only)
1
This is useful for servers that occasionally run very long requests (where this is considered normal operation), which might fool SeeFusion into thinking there is a throughput problem when none actually exists. In other words, this parameter tells SeeFusion to allow a certain number of slow requests (specified by the threshold) without counting those requests towards a "slow" or "down" status.
SeeFusion Enterprise adds the ability to log slow request and query metrics, along with information about specific incidents that occur (such as logging info based on the activation of an Active Monitoring Rule.

As the design goals for SeeFusion are low overhead and minimal impact, SeeFusion's database logging does not hold up request processing, but rather the information about the slow request or query is queued to a very low priority thread for logging, and only 10 such request are allowed to be queued at any given time. This means that it IS possible to "lose" slow request/query records, but in practice it's very unlikely. This also means that time synchronization across multiple Web servers is very important, as the Web server's current time is used to timestamp records. (The database server's current time can't be used, because there may be a queueing delay between the completion of the slow request/query and the insertion of that data into the database.)

Logging is turned on by entering the necessary information in the Database Logging section of the Configuration screen, and then enabling the logging system via the dbLoggerEnabled parameter. In order for logging to work, you must configure the database parameters in this section appropriately for the database SeeFusion will use for logging. Once you have set the database parameters properly, and you click the Save Settings link, SeeFusion will create the tables for you.

Parameter

Default

Description


dbDriver
(Enterprise only)
none
This is the driver class that SeeFusion will use to connect to the database specified below. Choose your database version from the dropdown. This driver must be in the same classpath as SeeFusion, or you'll see a "class not found" or "no suitable driver" error.

dbJdbcUrl
(Enterprise only)
none
This is the full JDBC URL for the connection that SeeFusion will use for database logging. Note: Do NOT wrap this URL with the SeeFusion wrapper syntax ("jdbc:seefusion:{...}").

Example entry:
jdbc:macromedia:sqlserver://127.0.0.1:1433;databaseName= SeeFusion;SelectMethod=direct;sendStringParametersAsUnicode=false
or
jdbc:mysql://192.168.1.123:3306/seefusion_db?

dbUserName
(Enterprise only)
none
Username, if any, for the database that SeeFusion will use for logging.

dbPassword
(Enterprise only)
none
Password, if any, for the database that SeeFusion will use for logging.

dbLogThreshold
(Enterprise only)
slowPageThreshold
SeeFusion will only log requests that run longer than this value. Enter the value in milliseconds. If no value is entered, then the threshold will default to the value of the slowPageThreshold parameter (which itself defaults to 8 seconds).

Example:
12000 (12 seconds)

dbLogQueryThreshold
(Enterprise only)
none
SeeFusion will log all queries that run longer than this value. (This assumes that you're using the SeeFusion JDBC wrapper for any datasources used by your application(s).)

dbLogQueryExceptions
(Enterprise only)
off
When enabled, SeeFusion will log all queries with exceptions. If this is "Off,"" then only completed queries that exceed dbLogQueryThreshold will be logged.

dbLogCountersThreshold
(Enterprise only)
none
Interval (in seconds) at which Counters are logged to the Counters table. If no value is set, Counters logging will be disabled.

dbLoggerEnabled
(Enterprise only)
Off
This is the on/off switch for database logging.

JDBC Driver Options

The SeeFusion JDBC driver wrapper accepts several arguments to provide you with more granular tracking of your database interaction. All options for the SeeFusion JDBC driver wrapper are specified using name=value pairs seperated by semicolons (";") at the end of the SeeFusion JDBC URL string entered in ColdFusion Administrator (URL parameters are appended to the SeeFusion JDBC URL following the closing curly brace (e.g., jdbc:seefusion:jdbcwrapper:{...};notifyCount=1500). These parameter names are NOT case-sensitive. The complete list of JDBC parameters and their use below:

driver
none
Specifes the name of the class of the driver that SeeFusion is wrapping. If specified, the SeeFusion driver will attempt to load the specified driver class (using "Class.forName()") the first time this parameter is specified.

Example:
;driver=com.myfavdb.Driver

Note: If you are having problems verifying a SeeFusion-wrapped datasource, you may need to add this parameter to your SeeFusion JDBC URL in order to allow SeeFusion to locate and load your driver.

notifyCount
0
The SeeFusion JDBC driver can alert you when a query retrieves an excessive number of rows from the database. If you want SeeFusion to log this information, set a notify threshold (a number of rows) at which SeeFusion should log the query to stdout. SeeFusion will also log the total number of rows retrieved by the query, once the query is complete.

Note: By default, ColdFusion/Lucee send stdout to a log file.

remindCount
0
After SeeFusion reaches the notifyCount, you can have it repeatedly log the number of rows fetched, at the interval specified by this parameter. For example, if a query retrieved 36777 rows, and you had notifyCount set to 5000 and remindCount set to 10000, then SeeFusion would log the query at 5000 rows, then log the number of rows again when the query reaches 15000, 25000, 35000, then 36777 rows.

rowLimit
0
When this parameter is added to the SeeFusion JDBC URL, all SeeFusion-wrapped datasources will be limited to returning only the number of rows specified. This is useful for preventing exceptionally large result sets from causing OutOfMemory and related errors.

Example:
;rowLimit=1500

dsn
blank
When this parameter is added to the SeeFusion JDBC URL, the ColdFusion datasource name used for the query will appear in the SeeFusion display for ACTIVE queries, along with other query information.

Example:
;dsn=CFAdminDSNName

Using SeeFusion

Some tips and tricks.


Server Profiles

Profiles are the most powerful new feature of SeeFusion 5. We've implemented this as "passive" profiling, which is much lower overhead than active profiling (which typically involves things like instrumenting your code). Just give your profile a name ("Label"), set an interval (which determines how often SeeFusion takes a snapshot of your system), and set a duration for the profile to run. For the duration you set, SeeFusion will take snapshots at the interval setting, and will aggregate information about code that was found to be running during the recording of the profile.

Recorded profiles will show up as a list on the main Server Profiling screen, under "Saved Profiles." Click the detail icon on the right side of any profile recording in order to see the metrics captured. The "Profile Summary" section lists the details of a particular recording. The "Recorded Traces" section lists the code seen running at the time of the snapshots, and lists your code in order of the frequency it was found to be running. Clicking on a recorded trace will show the stack trace(s) generated for that code at the time of the snaphot. This will tell you what code is most often running, and the stack trace will also show you (via the top of the stack trace) what was happening in your code at the time of the snapshot.

Note: Server Profiling is available for both Standard and Enterprise editions, but profiles are only saved to the SeeFusion database in the Enterprise edition. Standard edition profiles are not saved following restarts of the ColdFusion/Lucee service.


Active Monitoring Rules

The best way to keep track of your systems is with intelligent, automatic monitoring that's running 24/7. SeeFusion provides this capability via Active Monitoring Rules. There are 6 different rule types you can configure, for automatic monitoring of everything from the total number of active requests running at any given time, to memory utilization levels. You can also configure automated intervention, in the form of killing (stopping) requests, and/or be notified by email when a rule is triggered.

It may take some trial-and-error to configure rules optimally for your system, so fill in the information on the "Add a Monitoring Rule" screen as best you can, and then chat with us if you have questions/problems.


DoS Protection

Denial-of-service protection is another feature that's new to version 5. Over the years, DoS traffic has been a consistent problem for our customers, and now SeeFusion can help. The settings allow you to configure thresholds beyond which a given IP will be blocked, set a duration for blocking an IP only temporarily, and also to configure a whitelist to prevent certain IPs from ever getting blocked.

It's important to note that SeeFusion can only prevent DoS traffic from being processed by ColdFusion or Lucee. In most cases, this will be enough protection to prevent performance degradation, but DoS traffic will still be arriving at your network (load blancer, firewall, web server software, etc.).