Jschart NPM | npm.io

About

LPCPU (Linux Performance Customer Profiler Utility): ./tools/jschart.pm/jschart.js

(C) Copyright IBM Corp. 2015

This file is subject to the terms and conditions of the Eclipse
Public License.  See the file LICENSE in this directory for more
details.

This is a Javascript library that renders SVG charts.

This library depends on 3 external packages: d3.js, d3-queue.js, and saveSvgAsPng.js

Those packages are available via npm:

https://github.com/mbostock/d3 -- API version 3
https://github.com/d3/d3-queue -- API version 3
https://github.com/exupero/saveSvgAsPng

This library supports the override of some paramters via the URL.

For example:

page.html?threshold=5&threshold_invalidate_on_load=true

Detailed Usage

Using jschart:

From a developer user perspective jschart is consumed by calling the create_jschart function:

create_jschart(, , , , , , );

Here is a summary of each parameter:

This parameter tells the library whether the chart is a simple line chart or a stacked area chart. There are two different methodologies of supplying this parameter. In the original invocation it was a simple boolean field: '1' or 'true' for a stacked area chart and '0' or 'false' for a regular line chart. When jschart was ported to pbench, support for two additional values were added: 'stackedAreaChart' and 'lineChart'. These new parameters were simply mapped to the existing values for compatilibity purposes.
This parameter tells the library what kind of chart is being built, which ultimately results in configuring how the X axis is setup. There are three possible values for :
a. 'xy' b. 'timeseries' c. 'histogram'
An 'xy' chart means that the supplied data is just a series of X/Y value pairs to be plotted without any additional processing. A 'timeseries' chart differs from the 'xy' chart because the X axis values are milliseconds since epoch timestamps. When the chart is being drawn the integer timestamps are used just like a regular X/Y value pair but at the presentation layer the timestamps are converted into user decipherable timestamps, generally of the form 'YYYY-MM-DD HH:MM:SS'. A 'histogram' chart is treated very similarly to an 'xy' chart from a plotting perspective, but the values are interpreted to be a bucket/count pair rather than simple X/Y coordinates. When the data table is populated this results in different statistics being conveyed to the user than a normal 'xy' chart.
The parameter tells the library where to insert the chart and its accompanying table into the HTML DOM. This is usually implemented in the following fashion:
...
This could also be implemented with a much less direct linkage, such as:
...
...
This is simply the title printed at the top of the chart.
This is the title printed below the X axis.
This is the title printed above the Y axis.
The parameter is a javascript object that is a catch-all for many parameters. All of the parameters supplied here are optional, but there must be something here. For example, there are many different ways of supplying data files, but at least one of them must be used in order to achieve a working chart.
Here is a list of the available options:
a. timeseries_timezone b. legend_entries c. plotfiles[] d. plotfile e. packed f. csvfiles[] g. json_plotfile h. json_args i. update_interval j. history_length k. raw_data_sources[] l. threshold m. sort_datasets n. x_min o. x_max p. y_min q. y_max r. x_log_scale s. y_log_scale t. scatterplot
Now it is time to break these options down in detail:
a. timeseries_timezone
```
 This option is used to configure what time zone is used for
 the 'timeseries' data model.  Currently only 'local' or
 'utc' is supported.
```
Example:
{ ..., timeseries_timezone: "local" }
b. legend_entries
```
 The legend_entries options is a variable sized array
 defining arbitrary entries that should be added to the chart
 legend.  This is meant to provide a convenient method
 through which comments can easily be added to a chart.

 Example:
```
{ ..., legend_entries: "entry #1", "entry #2" }
c. plotfiles[]
```
 A plot file is the original data file supported by jschart
 and originally comes from multiple generations of charting
 programs that predated jschart.  The plot file format is
 extremely simple, it consists of a header row which defines
 the data series name and then rows of value pairs which are
 typically X/Y pairs.  It looks like this:
```
#LABEL:data series name 5 0 10 2 15 8 20 3 25 1
In most cases the file consisted of X axis values which were the interval that a tool produced a sample, in the above example that interval is 5 seconds. The Y axis values are the arbitrary value produced by the tool for that interval's sample.
The jschart library supports multiple plot files to be specified, so the plotfiles parameter is an arbitrarily sized array. It would be used like this in the options parameter:
{ plotfiles: "plotfiles/file1.plot", "plotfiles/file2.plot", ... }
d. plotfile
```
 The plotfile options is a simplified version of the
 plotfiles option which only supports a single plot file
 being supplied to the jschart library.  It is most
 applicable when combined with the packed option which is
 discussed next.
```
e. packed
```
 The packed option is optionally used in conjunction with the
 plotfile option.  The original plotfile file format only
 supported a single data series, meaning multiple data series
 required multiple files.  When jschart was written this
 demonstrated scalability issues in environments with very
 large data series counts.  A modified version of the plot
 file format called a packed plot file was created which
 combined multiple plot files into a single file with
 delineations between each data series.  It was a requirement
 that jschart know in advance the number of data series
 packed into the single file which is the point of this
 variable.  Here is an example of how this option could be
 used and the accompanying plot file:
```
{ packed: 2, plotfile: 'plotfiles/2-packed.plot' }
Contents of plotfiles/2-packed.plot:
--- JSChart Packed Plot File V1 --- #LABEL:data series 1 5 10 10 9 15 11 20 13 25 7 --- JSChart Packed Plot File V1 --- #LABEL:data series 2 5 8 10 9 15 5 20 6 25 4
f. csvfiles[]
```
 The csvfiles parameter is an arbitrarily sized array that
 points to one or more CSV formatted data files.  CSV file
 support was added to jschart when it was adopted by pbench
 in order to handle the data files that pbench was already
 producing.  The CSV file format support is similar to the
 plot file format support, yet still different.  The csvfiles
 option is an abitrary array like the plotfiles options but
 since a CSV file can include multiple datasets there is no
 hackish entity like the packed plot file.  A chart can be
 populated with one or more CSV files and each CSV file can
 have one or more data series in it.
```
The jschart library understands two different CSV file formats which can be briefly described by the following examples:
i. ts,d0,d1,d2,...,dN ii. ts0,d0,ts1,d1,ts2,d2,...,tsN,dN
In the first format each data sample row has a single timestamp with an interval sample for each data series at that timestamp. In practice, this looks like the following:
timestamp_ms,data series 1,data series 2 1461027782000,0,5 1461027783000,4,1
The timestamps are in milliseconds since the epoch.
The second format has individual timestamps for each data series sample, even those on the same row of the file. This could look something like the following:
timestamp_data_series_1_ms,data series 1,timestamp_data_series_2_ms,data series 2 1461027782000,0,1461027782500,5 1461027783000,4,1461027783500,1
Using the csvfiles option to jschart would look something like this:
{ csvfiles: "data-files/samples.csv" }
g. json_plotfile
```
 The json_plotfile allows jschart to use JSON formatted data
 files.  Since it is JSON the file format is fairly dynamic,
 but there are some basic assumptions that must be met.  The
 JSON output should be based on the following:
```
{ 'x_axis_series': , 'data_series_names': [], 'data': [] }
The 'data_series_name' and 'data' properties are arrays which share the same indexes. The 'x_axis_series' property defines which entry in the 'data_series_names' array contains the X axis value of the X/Y pairs for each dataset. In practice this would look something like this:
{ 'x_axis_series': 'time', 'data_series_names': 'time', 'data series 1', 'data series 2' , 'data': [ 1461027782000, 0, 1, 1461027783000, 4, 5 ] }
Currently an assumption is made that the JSON output is used for a 'timeseries' data model and the X axis values are expected to be in milliseconds since the epoch.
It should be noted that the JSON features of jschart have had limited usage at this time and could probably be improved upon if required.
h. json_args i. update_interval j. history_length
```
 These three options are only used in conjunction with the
 json_plotfile option, and most often all together (although
 update_interval and history_length may not be required).
```
The json_args option defines post data that is sent to the HTTP server when requesting the data pointed to by json_plotfile. Typically this would be used to tell the HTTP server what data is being requested if json_plotfile refers to a URL whose response is dynamically generated. For example:
{ json_plotfile: 'http://some.server.somewhere', json_args: 'type=foo' }
In this example, supplying different values for 'type' could alter the response that the server sends depending on its implementation.
The update_interval options tells the jschart library that the data being requested is dynamic and should be re-requested periodically on the defined interval. This is typically used for pseudo realtime data monitoring. After the initial request is made, subsequent requests are made every update_interval number of seconds. These additional requests will include any json_args that were provided and will additionally add a 'time=' entry to the post data so that the server can try to optimize the transfer by only sending new samples since and avoid retransmission of existing data.
The history_length parameter tells the jschart library how many data samples should be retained when new data is being dynamically added. This prevents the arrays that contain the sample data from growing without bounds which would eventually cause a memory related issue.
All combined, these parameters could be used like this:
{ json_plotfile: 'http://some.server.somewhere', json_args: 'type=foo', update_interval: 5, history_length: 300 }
This example would request the available data every 5 seconds and maintain a history of 300 samples.
k. raw_data_sources[]
```
 The raw_data_sources option is an arbitrarily sized array
 that contains links that should be appended to the table
 associated with each chart.  This is typically used to
 provide a way to access the raw tool output that the charted
 data was generated with, hence the name.
```
Example:
{ csvfiles: "data-files/processed.csv" , raw_data_sources: "data-files/tool1.out", "data-files/tool2.out" }
l. threshold
```
 The threshold option defines a value which is compared
 against the maximum Y axis value for each dataset.  If the
 threshold value is larger than the dataset's value then that
 dataset is automatically hidden by default.  This provides a
 mechanism which is used to filter out noise from tools that
 produce large numbers of datasets.  At run time the user can
 achieve the same functionality through the UI and also
 apply the threshold against the dataset average instead of
 its maximum value.  The UI controls do not require that any
 options be provided in the code.
```
Example:
{ ..., threshold: 5 }
m. sort_datasets
```
 The sort_datasets option is a boolean value that determines
 the order in which datasets are presented to the user.  By
 default sort_datasets is enabled, unless live_update is used
 (this is due to the requirement of consistent ordering
 between the existing and new sample data).  If sort_datasets
 is disabled by setting it to false then datasets are
 presented in the order they are supplied to the library
 (note: this was the default behavior prior to the addition
 of sort_datasets).
```
Example:
{ ..., sort_datasets: false }
n. x_min o. x_max p. y_min q. y_max
```
 These four options control the default axes domain of the
 chart view port.  There are many different reasons for doing
 this but the most common is probably to set a strict range
 for a known set of values, such as a CPU usage graph which
 will be a percentage between 0 and 100.
```
Example:
{ ..., y_min: 0, y_max: 100 }
r. x_log_scale s. y_log_scale
```
 These two options are boolean values that control whether or
 not the corresponding axis scale should be presented with a
 logarithmic scale (instead of the default linear scale).
 The one exception to this is if the 'timeseries' data model
 is used, in that case the x_log_scale option is ignored.
```
Example:
{ ..., y_log_scale: true }
t. scatterplot
```
 The scatterplot option is a boolean value that changes the
 chart from a traditional line graph to scatterplot where
 only the individual data points of a series are visible
 without a line connecting them.  This option only makes
 sense for non-stacked charts.
```
Example:
{ ..., scatterplot: true }