Hyades Data Collection Engine
=============================
This is the Hyades Data Collection Engine that contains a server that has the 
capability to launch and manage local/remote applications from a local Hyades 
workbench.  It also contains a Java profiling engine that uses the JVMPI to 
profile local/remote Java applications from a local Hyades workbench.  Using 
the corresponding Hyades build, you can launch and profile local/remote Java 
applications and import local/remote Apache error and access logs.


Notation
========
<unzip directory> = The absolute directory path where the Hyades Data Collection 
Engine has been unzipped.  For example, C:\Hyades.

<service name> = A unique Windows service name.


Getting Started
===============
1) Generate the configuration file that provides the rules for which applications 
   that can be executed with the server.  This can be accomplished by running the 
   <unzip directory>\bin\SetConfig.bat script.  Run this script from a command shell 
   in the <unzip directory>\bin directory.  This step will require that a Java 
   Virtual Machine (JVM) be present in the system's PATH.  Follow the prompts and the 
   output will be the <unzip directory>\config\serviceconfig.xml file.  This is a sample 
   of the configuration file that will be used by the server when it is started.   You 
   may edit this file manually using the rules documented in the <unzip directory>\dtd\serviceconfig.dtd 
   file.  To load any changes, restart the server.

2) Add the <unzip directory>\bin directory to the system's PATH environment variable.  

   NOTE: Do NOT encase the environment variable's value in double quotes despite spaces in <unzip directory>.

3) Start the server using one of two possible techniques:


Running the Server as an Application
====================================
Set the RASERVER_HOME environment variable to point to <unzip directory>.  The server will use this environment 
variable to locate the configuration file.  

NOTE: Do NOT encase the environment variable's value in double quotes despite spaces in <unzip directory>.

Start the server by running the <unzip directory>\bin\RAServer.exe application.  

Stop the server by terminating the RAServer.exe process (e.g. closing the command shell).


Running the Server as a Windows Service
=======================================
Remove and/or uninstall all existing installations of the Hyades Data Collection Engine.

Run the <unzip directory>\bin\manageservice.exe application to create the Windows service.  
The syntax is:

	manageservice add "<service name>" "<unzip directory>"

For example:

	manageService add "Hyades Data Collector"  "C:\Hyades"

You can now start and stop the server using the Windows' Services panel or with the Windows' 
'net' command.

To unintall the server Windows service, run the <unzip directory>\bin\manageservice.exe 
application to delete the Windows' service.  

For example:

	manageservice remove "Hyades Data Collector"


Server Logging
==============
All server log entries will be placed in <unzip directory>\config\servicelog.log.


The Java Profiler
=================
The Java Profiler is a library that attaches to a JVM to capture and record the Java 
application's behavior. The output from the profiling agent is in the form of XML fragments.  

Documentation on the composition of these XML fragments is located at:
http://dev.eclipse.org/viewcvs/indextools.cgi/~checkout~/hyades-home/docs/components/data_collection/docs/XML4Profiling.htm


Invocation of the Java Profiler from the Hyades Workbench
=========================================================

The Java Profiler can be launched from the Hyades workbench.  Open the Profiling Perspective and you can
launch applications using the 'Profile' menu contribution or the toolbar button.  Applications can
be run either using code within the current Hyades workbench's workspace or binaries that are on the 
file system.


Invocation of the Java Profiler from the Command Line
=====================================================

The Java Profiler is invoked using the -Xrun JVM option as follows:
	
	-XrunpiAgent[:agent_parm[,agent_parm]*

where agent_parm may be:

server=[standalone | enabled | controlled]
	standalone
		The Java Profiler is manually attached to a JVM instance and generates a stand-alone
		trace to a specified file based on the options and filters given on the command line.
		When this option is selected, the Java Profiler produces the enclosing traceRoot
		element to form a complete and valid XML document.
	enabled
		The Java Profiler is loaded, allows the application to run normally, but produces no
		trace until a Hyades workbench attaches to the agent to give it instructions.  When this
		option is selected, the Java Profiler only produces XML fragments instead of a
		complete XML document.
	controlled
		The Java Profiler is loaded, blocks the application from running until a client gives
		it instructions to continue.  When this option is selected, the Java Profiler only
		produces XML fragments instead of a complete XML document.

filters=filename
	NOTE: This parameter is only used when server=standalone is specified.
	
	Specifies the name of the file that contains the initial class filter definitions to be used
	during the trace. The default is filters.txt in the current directory. The format of the file
	is as follows:
	
	    classpattern methodpattern mode , where:
	
	classpattern
		is a string with no imbedded blanks. The string may contain a single "*" either at the
		beginning of the string or at the end of the string. The "*" will match zero or more
		characters, thus making the pattern a generic prefix or suffix pattern. A single "*"
		can also be specified to represent all strings. 
	methodpattern
		is a string with no imbedded blanks. The string may contain a single "*" either at the
		beginning of the string or at the end of the string. The "*" will match zero or more
		characters, thus making the pattern a generic prefix or suffix pattern. A single "*"
		can also be specified to represent all strings. 
	mode
		is one of INCLUDE or EXCLUDE.

	Filter patterns are processed in the order that they are specified until the first pattern
	match succeeds. If the class name does not match any of the specified filter patterns, the
	default is to INCLUDE the class.

file=filename
	NOTE: This parameter is only used when server=standalone is specified.
	
	Specifies the name of a file where the trace will be written. The default is trace.xml in
	the current directory.
 
help
	Displays a list of available agent options to standard out.
