Tools
Collecting Metrics : Reference
com.jmetra.JMetraMaker [options] [output directory]
| Argument | Description | Default |
| output directory | directory destination for generated file(s) . | current directory |
| Option | Description | Default |
| -help | print all the usage arguments and options, and their descriptions. | |
| -verbose | enable verbose output. | |
| -trace | enable debug level logging. Not recommended unless user is experiencing a possible problem with jMetra and wishes to collect more details for passing to hyperCision | |
| -javaversion <version> | (available in 1.2.4 only) Specify version of the Java source code metrics are being collected from. Options are 1.3, 1.4, or 1.5 | Default is 1.4 |
| -label <labelname> | explicitly assign a label labelname to the metrics file. | time formatted label will be used if -label is not specified |
| -tstampformat <format> | format of timestamp if not using -label option. Use SimpleDateFormat pattern. | yyyy.MM.dd.HHmmss |
| -tstamp <timestamp> | specify timestamp to associate the current build with. This will also be used if the timestamp is used for labelling. | current timestamp |
| -sourcepath <pathlist> | not implemented yet.... | |
| -rootsource <path> <keyword> | path specifies the top directory for searching for all source roots. keyword is the name of the directory/directories that are identified as source roots. | none. attributes must be specified. |
| -logconfig <log4j config filename> | specify custom log4j configuration. Refer to the default file before customizing. (version 1.2) | use log4j.properties contained within jmetra.jar |
| -config <filename> | filename specifies the an XML-based configuration file that may be used to customize jMetra. It currently is only used for code concurrency mappings in the -aggr option. | none. |
Parsing Errors
Any parsing errors will show up as an error in the jmetra log file (see Logging). Details will be provided regarding the specifics of the parsing error.
Usage Examples
The following are a collection of example usages to demonstrate the parameters in use. We assume all required jMetra are on the classpath.
Aggregating Metrics : Reference
com.jmetra.JMetraMaker -aggr [options] [metrics directory] [output directory]
| Argument | Description | Default |
| metrics directory | directory source where existing metrics files to be aggregated can be found. | |
| output directory | directory destination for generated file(s). |
| Option | Description | Default |
| -help | print all the usage arguments and options, and their descriptions. | |
| -verbose | enable verbose output. | |
| -logconfig <log4j config filename> | Refer to the default file before customizing. (version 1.2) | use log4j.properties contained within jmetra.jar |
| -config <filename> | filename specifies the an XML-based configuration file that may be used to customize jMetra. It currently is only used for code concurrency mappings in the -aggr option. | none. |
Incremental Building of Aggregate Metrics
Since generating jMetra documents with JMetraDoc requires the aggregrated metrics, the aggregation command (reviewed in the above section) will need to be executed every time you want to include new metrics (from new builds) in the jMetra Doc.
It is important to note that the aggregation command is given a directory to locate the individual metrics files generated over time. JMetraMaker -aggr will automatically run through all the metrics XML files in the directory and attempt to aggregate each one into the existing aggregate metrics files. If an entry for that label does not exist then they are added to the aggregate metrics file for that class.
As the aggregation is taking place, for each class, jMetra checks to see if the metrics with the same label are already in the file. If they are, jMetra will not add them again.Since jMetra will not add metrics with duplicate labels, you can always keep your metrics in the same directory and aggregate on this directory.
As a result of how jMetra aggregation occurs, if you keep all your individual metrics files from each build, you can blow away your aggregate metrics and they can be totally regenerated as long as all the individual metrics files are in the same directory. This is good to keep in mind!
Usage Examples
The following is a collection of example usages to demonstrate the parameters in use. We assume all required jMetra are on the classpath.
Code Metrics Continuity
As a project evolves, it is not uncommon for project packages to be reorganized, or specific files to be moved to different packages. It is desirable for jMetra to tie together classes metrics using old class nameswith the new, currrent class names. Likewise, it is desirable to tie together class metrics between a group of classes with an old package name with the classes at the new package name. We solve this problem by not resolving changes in class names and package location changes until the aggregation stage. The jMetra config file contains a list of original and current package changes, and the time that these changes/renamings took place. You must take the responsability to generate this yourself. Also, by delaying this continuity processing until aggregation, you can always regenerate the aggregations if you incorrectly defined the mappings between new and old class names and packages and their new class names and locations.
Example of Configuration file for Metrics Continuity
For our project proj, let's say we moved a java package and its contents from com.xyzinc.proj.ui.servlets to com.xyzinc.proj.app.servlets on 3/15/02. Also, we renamed and moved a class com.xyzinc.proj.AppException to com.xyzinc.ApplicationException on 4/10/02. The continuity file
<?xml version="1.0" encoding="UTF-8"?>
<config>
<moved-package from="com.xyzinc.proj.ui.servlets" to="com.xyzinc.proj.app.servlets" occurred="2002.03.15.000000"/>
<moved-package from="com.xyzinc.proj.AppException" to="com.xyzinc.ApplicationException" occurred="2002.04.10.000000"/>
</config>
would provide a continuity of the metrics. When aggregation occurs, metrics from the old packages and old class name would be added using the new packages and the new class name in the aggregated metrics files. Note that the aggregated XML file contains an original attribute when this occurs which contained the original full package name.
Usage Notes
Many projects using jMetra in a corporate environment often store the metrics aggregations on a shared, networked drive. Since the aggregation process is file-write intensive, aggregating new metrics files can take a substantially longer time. We have observed that performance for aggregating can take up to 10 times longer when writing to some networked drives. For this reason, we recommend that you put your metrics and aggregation files on a drive that is local to the platform where jMetra is executing. Users may still wish to write to a networked drive but should consider that aggregation performance is particularly sensative to drive access.
Configuration Note
When updating the config.xml file with new package or class name/location changes, it is required that the aggregate files be generated from stratch. In other words, make sure you save all your build metrics fills for your project, blow away the \aggr directory, and aggregate all your build metrics files again. Any time you update the config.xml file, you must totally regenerate the aggregration files.
