Plot/Graph Action Blocks
- 1 Introduction
- 2 Creating Plot/Graph Action Blocks
- 3 A Simple Graph Script
- 4 Short List of Useful Script Commands
- 5 Accessing Data from Attachments
- 6 Plotting Multiple Graphs into a Single Picture
- 7 Changing the Size of the Generated Image
- 8 Caveats
- 9 Complete Example 1: Gathering Response Times of MQTT Protocol Messages
- 10 Example 1 Simplified: Using Probes to Gather the Data
- 11 See Also
With expecco18.1, a new block type named "Plot/Graph Actions" is introduced. These behave similar to other script action blocks, in that they are defined by a script (in this case: gnuplot scripting language) and are placed into the test sequence flow just like any other block.
However, when executed, these actions generate a graphic document (jpeg, png or postscript),
which is then either added to the activity log, or added as attachment. It will therefore be
available in the generated "
elf" execution log file, or shown in the generated "
Creating Plot/Graph Action Blocks
Plot/graph action blocks are created via the "Actions - More - Plot/Graph" menu item.
Select the "Plot/Graph" item, to create a new gnuplot action. An initial set of input pins and an initial (demo-) script is generated for you.
For details on the scripting language, please refer to the public gnuplot documentation "http://www.gnuplot.info/docs_5.0/gnuplot.pdf".
Any input pin named "
<pinName>" is available in the script as "
Thus, the script can be parametrized in arbitrary ways.
A number of pins are already created for you; these are:
both an input and an output. If the input is specified, gnuplot will generate the plot into that file. Otherwise, a new temporary file will be created and the output written into that. In any case will the actual outputFileName be available on the corresponding output pin for further processing.
specifies the kind of file to generate. For inclusion into the report, an image format should be chosen (i.e. one of "jpeg", "png" or "gif"). For archival or to generate high quality documents, you can also choose "postscript" or "svg". However, those can (currently) not be automatically converted for the pdf report.
On Unix systems, you can also specify "x11" as output format. In this case, a window is opened, displaying the generated graph. Be aware that expecco is (currently) not informed about the window being closed, so you may have to stop the test-run via the expecco-"Stop" button.
A title string to be drawn above the graphic (actually, the position of the title is specified by the "set key" gnuplot expression, inside the script)
If connected, and a collection of values is present, these values will be written into a temporary data file, and the filename is available in the gnuplot script as "
%(data)". Theis will be the raw data, to be processed by the script.
There is no pin for that, but the value is available to the script. It provides the number of data points (or rows) in the data file.
if true (the default), the generated graph will be attached to the final pdf report. This pin's value is not forwarded to the gnuplot script.
A Simple Graph Script
A typical gnuplot script looks like:
# The code below is sent to gnuplot and the generated output # will be stored in a file named %%(outputFile) # (unless explicitly specified, a temporary file is created) # set output "%(outputFile)" # set term %(outputFormat) # All input pin values can be used here as %%(nameOfPin). # so the next line controls the title via the "title" pin # set title "%(title)" # You can add more pins. # For example, add pins named "min" and "max" with type Number, # and replace "-10:10" below by "%%(min):%%(max) to parametrize the y-axis range. set key left box plot [1:%(dataSize)] [-10:10] "%(data)" title "My Data" with impulses
to plot a simple impulse graph of the data values, as presented at the input pin, assuming that the pins get the following values:
- "outputFile" - leave unconnected or remove the pin (to let the action choose a temp file)
- "outputFormat" - freeze as "
- "title" - any title - such as "Measurement #1"
- "data" - a vector of numbers
Of course, this is actually the simplest possible script to render such data.
Gnuplot provides a wide area of possible plots, both 2D and 3D, with or without colors, etc.
A few examples are provided in the "
Plot_Graph Library.ets", but much more is found on the gnuplot
website and gnuplot documentation "http://www.gnuplot.info/docs_5.0/gnuplot.pdf".
Short List of Useful Script Commands
For a full list, please take a look at the gnu plot documentation "http://www.gnuplot.info/docs_5.0/gnuplot.pdf". The following list is only presenting the most common plot commands:
plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with impulses
You can omit the "[yMin:yMax]" parameter, for a reasonable box to be automatically chosen by gnuplot.
Replace "nameOfDataFile" by "%(data)" if the data comes via an input pin and is not already in a file.
plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title"
Without the "impulses" parameter, a regular graph is drawn (straight lines between points)
plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with: lines
The same as above (straight lines between points)
plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with: dots
plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with candlesticks
the data file should contain multiple colums per line. Select the colums with a "using..." parameter.
set key left box
defines the position (left) and type (boxed) of the graph-title (the string comes from the
title "graph title"argument in the plot command)
set title "someTitle"
defines a headline title
set term %(outputFormat)
defines the type of image to be generated. For "%(outputFormat)", the input pin's format is generated. Otherwise, you can also hardcode any of "
jpg", etc. here
A few examples are found in the demo library: "Plot_Graph_Library.ets", which is found in the plugin's folder and in the online documentation "http://www.gnuplot.info/docs_5.0/gnuplot.pdf".
Accessing Data from Attachments
You can directly access expecco attachment files by their name inside the script. I.e. if you have an attachment with file named "
... data "foo.dat" ... inside the script. Notice that the attchment's filename is to be used - not its name in the tree.
Plotting Multiple Graphs into a Single Picture
To do this, generate multiple datasets (as ascii files, with one textline per row). Add
data<i> input pins and feed them the filenames. Add multiple
plot commands, each with its own "
%(data<i>)" argument, and possibly with its own graph-title.
Changing the Size of the Generated Image
By default, the generated image's size is 640 x 400 pixels.
For a fix size, change the script's "
set term" statement to:
set term %(outputFormat) size <width>,<height>
where <width> and <height> define the size in pixels.
Alternatively, add two pins named "width" and "height", and change the statement to:
set term %(outputFormat) size %(width),%(height)
and provide the desired size (as integers) at the input pins.
Do not place
pause statements into the script; there is no input stream given to gnuplot, so it will immediately read an EOF (end of file) and proceed.
Complete Example 1: Gathering Response Times of MQTT Protocol Messages
This example demonstrates, how a test suite can gather response times of a remote system, when sending MQTT messages to it.
Step 1: Define the Test Sequence
this is a very simple publish-response setup, in that a topic is published to an MQTT broker, and the time measured, until the notification arrives (in order to run this on your machine, the expecco MQTT plugin needs to be installed):
Outside (Schema) view of the measuring action:
which is implemented as:
The yellow area does the MQTT setup. First, an MQTT client connection is created, and the client handle forwarded to the Subscribe action, which registers expecco to react to the "expeccoTesting/test" topic.
The green area does the actual publish operation, publishing the "Hello from Expecco" string on this topic.
In parallel, the blue area waits for the next incoming event, (and generates a printed detail info on the received packet for the activity log).
The red area contains a stopWatch action block, which gets started with when the publish is done, and stops when the event arrives.
The measurement action is prametrized with the broker's host and port, and generates the measured timeDuration as output.
Step 2: Test Run
Assuming that you have an MQTT client running on the local host, the test sequence can be immediately tried via the Test/Demo page:
A good strategy is to package the MQTT broker into a docker file. Here is the MQTT client's output of the above run:
$ sh rundocker.sh 1522084243: mosquitto version 1.4.8 (build date Thu, 01 Mar 2018 09:34:49 -0500) starting 1522084243: Using default config. 1522084243: Opening ipv4 listen socket on port 1883. 1522084243: Opening ipv6 listen socket on port 1883. 1522084272: New connection from 172.17.0.1 on port 1883. 1522084272: New client connected from 172.17.0.1 as expeccoMQTT (c1, k0). 1522084272: Client expeccoMQTT disconnected.
and here the activitylog in expecco:
with the event info detail:
Step 3: Running that Sequence Multiple Times
Now that we have verified, that the communication with the MQTT broker works correctly, we create another action bock, which runs the above action multiple times and collects all the execution times:
[ explanation: first, a new empty colletion is created, then, the timing values of the multi-triggered measure-step are all added to this collection. When done (no step active), the collection is forwarded (now filled) to the output pin]
Here is the activity log after 10 runs:
Step 4: Adding the Graph
The last step is the easiest: select the "New Plot/Graph" action block from the menu, name it "Time Measurement Graph" and change its autogenerated gnuplot script to:
set output "%(outputFile)" set term %(outputFormat) set title "%(title)" set key left box plot [1:%(dataSize)] [0:100] "%(data)" title "%(lineTitle)" with impulses
then place a step of it into your network and connect the "collectedTimes" output of the above measurement step with the "data" input of the "Measurement-Graph" step:
Running it, and generating the report, produces the following pdf-report (the logging of subactivities was disabled for this report):
Example 1 Simplified: Using Probes to Gather the Data
The above data collection may look a bit complicated, due to the need for start/stop synchronization. A much nicer and easier to use solution is in using a probe to gather the data. For this, we need a probe which does no range checks, but instead only collects the incoming values:
Here, a probe was added (via the "timeDelta" pin's "Add Probe" menu item), and specified to "collect incoming data without check":
Now that we have a probe at the roundtrip time, the outer measurement looks much simpler:
- reset the probe (to clear any previously gathered data)
- prime the probe enable data collecting)
- run the roundtrip-test n-times
- unprime the probe (disable further data collecting)
- fetch the probe's values and pass them to the gnuplot action
"R Action Blocks" which provide similar graph/plot functions in addition to sophisticated mathematical and statistics libraries.