| | h2. Overview |
| | |
| | As of version 2.0.32, {pn} includes support for configurable report groups for projects. These report groups can include multiple trend reports, showing how build metrics change over time. Furthermore, from this version, support for capturing custom fields is also supported. By combining these two features, you can capture arbitrary metrics from your build and chart them over time. In this cookbook recipe we will illustrate how to generate, capture and chart custom metrics. |
| | |
| | h2. Generating Metrics |
| | |
| | The easiest way to generate metrics for use with {pn} is to output them in a Java properties file (the format described [here|http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html#store(java.io.OutputStream,%20java.lang.String)]). These files contain simple key-value pairs, one per line, with the key separated from the value by an equals sign \(=). For example: |
| | |
| | {code:title=fields.properties} |
| | metric1=23916 |
| | metric2=11388 |
| | {code} |
| | |
| | Metric names can be anything of your choosing, although they may need escaping if you wish to include whitespace or certain punctuation characters. The properties file can be output in any location you choose - for simplicity we will assume it is output to the build base directory with the name {{fields.properties}}. You can also split your metrics over multiple files, by capturing them all as described below. |
| | |
| | h2. Capturing the Metrics |
| | |
| | To capture the metrics as part of your build result, you need to capture the properties file as an [artifact|Artifacts] and apply the custom fields [post-processor|Post-Processors] to it. The method depends on if you are using a [built-in project|built-in projects] or a [pulse file project|Pulse File Projects]. |
| | |
| | h3. Built-in Projects |
| | |
| | For built-in projects, navigate to the "artifacts" tree item in the project configuration, and click "add". Select "file artifact", then give the artifact a name, enter the file path, and select the "custom fields" processor: |
| | |
| | !custom-fields-artifact.png! |
| | |
| | h3. Pulse File Projects |
| | |
| | For pulse file projects, add a custom fields processor to your pulse file, add an artifact to capture the properties file, and apply the processor to it. For example: |
| | |
| | {code:title=pulse.xml|lang=xml} |
| | <?xml version="1.0"?> |
| | <project default-recipe="ant build"> |
| | <custom-fields.pp name="fields.pp"/> |
| | |
| | <recipe name="ant build"> |
| | <command name="build"> |
| | <ant targets="test"/> |
| | <artifact name="custom fields" file="fields.properties"> |
| | <process processor="${fields.pp}"/> |
| | </artifact> |
| | </command> |
| | </recipe> |
| | </project> |
| | {code} |
| | |
| | h2. Verifying Captured Metrics |
| | |
| | To verify that your metrics are being captured as expected, you can run a build and then navigate to the "detailed view" tab. By selecting the stage name in the left column ("default" for simple projects), you should see the "build stage summary", "commands" and finally "custom fields" tables. The latter should show the values of your custom metrics: |
| | |
| | !detailed-view.png! |
| | |
| | h2. Configuring the Report |
| | |
| | Now you are ready to configure a report to display the trends of your metrics over time. The first step is to add a new report group. Navigate to the "report groups" tree item for the project configuration, click "add" and fill in the group details. For example: |
| | |
| | !report-group.png! |
| | |
| | The default time frame is used to select the builds to report over when viewing the report. You can adjust this while viewing reports, but it is convenient to set a reasonable default. |
| | |
| | Next, add a report to this report group. Navigate down to the "reports" child node in the tree, and click "add". Enter the report details: |
| | |
| | !report.png! |
| | |
| | The "domain units" decide how the horizontal \(x) axis for the report is labelled - by build or by day. By build is simplest, but in some cases you may want all builds on a single day to be combined into a single value. In this case you will need to choose how to combine the metrics for the builds, e.g. to average them (take the mean), or add them (take the sum). For simplicity we have stuck with builds in this example. The range label is applied to the vertical \(y) axis of the report, and should typically mention the units of your metric. |
| | |
| | Finally, you need to add some series to your report. Each series captures the values of a single metric for reporting. One thing to consider here is that metrics are captured individually for every [stage|build stages] in your build. For simple builds there is only one stage (called "default"), so there is no extra complication. For builds with multiple stages, however, you will need to decide whether to show the values for each stage separately or to combine them. If you decide to keep them separate each series you configure will actually appear as multiple series in the report, one for each stage. They will be disambiguated by appending the stage name (in parentheses) to the series name in the report legend. |
| | |
| | To add a series, navigate to the "report series" child node in the tree and click "add". Select "stage series" - as described above custom metrics are captured per-stage. Then fill in the details for your series: |
| | |
| | !report-series.png! |
| | |
| | | Give your series a name (perhaps the metric name), select "custom field" as the metric and add the metric name. If your metric is expressed in whole numbers, choose "integral" as the type, otherwise choose "floating point". As described above, decide if you want to combine the metric values from different stages or keep them separate. If you decide to combine them you will have to choose how. If you like, you can also specify a custom colour for the series, for example you might want to set a "success"-related metric to "green" or "0xff8080". |
| | | Give your series a name (perhaps the metric name), select "custom field" as the metric and add the metric name. If your metric is expressed in whole numbers, choose "integral" as the type, otherwise choose "floating point". As described above, decide if you want to combine the metric values from different stages or keep them separate. If you decide to combine them you will have to choose how. If you like, you can also specify a custom colour for the series, for example you might want to set a "success"-related metric to "green" or "0x80ff80". |
| | |
| | When you have done adding one series, you may choose to add more - one for each metric you want on the same report. Alternatively you can add more reports to show different metrics in separate charts. |
| | |
| | h2. Viewing the Report |
| | |
| | Now you are almost ready to view your report. First, though, you may need to run a few builds so there is some data to report over! Once some builds are available, navigate to the "reports" tab for your project. Select your new report group in the left column, and you should see the fruits of your labour: |
| | |
| | !chart.png! |
| | |
| | Happy reporting! |
