oltpplot − Create html and graphics for a single run
oltpplot [--xfile|--Xfile filename] [-x|-X|--xmarker|--xline ’time text’] [-c|--xcolor rgbname] [--ses-y{2}range ’[ .. ]’] [--ses-simplified] [--res-y{2}range ’[ .. ]’] [--ash-yrange ’[ .. ]’] [--gnuplot-extra file] [--no-awr-interval] [--no-titlerunnumber] [--no-client-cpu] [--xlabel ’text’] [--no-x2label] [--titletext ’text’] [--e2e-no-logscale] [--fractiles-dropped] [-k|--key key] [-l|--latest|[-r] runnumber]
Recreate the report that was created using oltprun with possible changes to contents, axes and/or potentially adding named markers or vertical lines.
-h|-H|--help
Print short help.
--res-yrange
’[ .. ]’
--res-y2range ’[ .. ]’
--ses-yrange ’[ .. ]’
--ses-y2range ’[ .. ]’
--ash-yrange ’[ .. ]’
By default the ranges of the left and right y-axes in the various plots are set to be "reasonable". The first two options will explicitly set different ranges in the first plot of resources (dbcpu and dbtime) on the left y-axis or throughput on the right y-axis. The second two options explicitly set different ranges in the second plot of sessions on the left y-axis (database open/active sessions) or right y-axis (instance distribution). The last option will set the left y-axis range (session count) for the ash plot. The argument to these options must be a valid gnuplot argument for a range such as [0:*], [0:20] or similar and it should typically be enclosed in quotes to prevent shell expansion.
-x|--xmarker ’time text’
Put a named marker on the x-axis of all relevant plots at some time. The time must be in either UTC time in YYYY.MM.DD"T"HH24:MI:SS format (as defined by Oracle) or it must be a positive number of seconds. The marker will be placed at the appropriate position on the x-axis and will have an associated name printed with it; the name text can be empty in which case only the marker is printed. Note that the whole option value must be provided as one shell argument and that it therefore will need to be quoted by the shell.
The option can be repeated if you want to print several markers, and you can mix the two ways to specify the time if needed.
-X|--xline ’time text’
Similar to the -x option except a vertical line spanning the whole range of the y-axis is printed.
--xfile|--Xfile filename
In stead of providing the time and the text as a shell argument, you can have a number of these combinations stored on individual lines in a text file. Each line must have a time per the above (seconds or UTC) followed by a blank and the wanted text. No other contents may be in the file.
The difference between --xfile and --Xfile is like the difference between --xmarker and --xline.
You can use either of the four options repeatedly.
-c|--xcolor rgbname
By default, these markers and lines are printed by gnuplot using the rgb name of ’blue’; you can use this option to choose any other valid rgb name.
--gnuplot-extra file
The contents of the named file will be added as extra contents to all gnuplot input files. It can contain any valid gnuplot commands and can be used to add any extra decoration to the generated graphics.
--no-awr-interval
By default, all generated graphics will indicate the time taken to do the initial and finishing awr snapshots. This option turns that graphics off.
--no-client-cpu
By default, the client cpu utilization is included on the graph with throughtput and resources. With this option, the client cpu it not included.
--no-titlerunnumber
By default, all generated graphics includes the runnumber in the title. This option turns that off.
--xlabel ’some text’
By default most graphics have an xlabel with the text "seconds since " followed by the date of the run. By using this option, you can supply any other text.
--no-x2label
By default, timestamps (without date part) will be printed above selected graphs. With this option, these timestamps will not be printed.
--ses-simplified
The graph showing sessions and - if relevant - ranges for the size of the pools is simplified and does not contain the distribution of sessions on instances.
--e2e-no-logscale
The graphs showing end-to-end timing for the various emulated business transactions is by default using a logarithmic time axes to cater for large variation or large differences between the end-to-end components. If you do not have such large variations or differences, you can use this option to use a regular linear scale.
--fractiles-dropped
Whenever your run is with a time_out value set, there might by dropped transactions. When generating the plot of execution time fractiles, such dropped transactions are not included. Whether this is the correct thing to do or not is surely debatable. By using this option, dropped transactions are assumed to "cost" 2s, typically causing the high range fractiles (e.g. 98%, 99%) to be very high.
--titletext ’some text’
By default, all generated graphics has that title that include the key and the komment from running oltprun. With this option, you can provide any other text.
-l|--latest
You can provide this option as an alternative to an actual runnumber, which causes the latest run from the current host to be used.
-k|--key key
Provide a key in the repository rather than the default taken from the RWLOLTP_NAME environment variable. This option is only relevant if you also use the -l or --latest option.
You normally don’t need to call this directly; it is automatically called after each execution of oltprun to create the standard graphs.
The primary purpose of the command is to allow various changes to the graphs including changes to the ranges, changes to contents, changes to texts using options beginnig with --ses, --res, --no, etc. You can also augment the various graphs with information about certain events during the run, you can do so by calling oltpplot with one or more of the -x or -X options.
To create a useful string for a date representation for either option, you can call
date -u +%Y.%m.%dT%H:%M:%S
If you find that your latest run was using a y-axis for the database cpu and time that was inappropriate, you can recreate the graphs, also providing a different text on them, using a command like
oltpplot --res-yrange=’[0:20]’ -l --titletext=’changed y range’
which will cause the y-axis on the throughput and resources graph to have the range 0-20 seconds. Note that the actual range typically needs to be quoted to prevent shell expansion.
If you had a run with number 12345 starting on 2021.12.31 just before midnight and you want to add a vertical line to the plots at exactly midnight, you can recreate the graphs using
oltpplot --xline ’2022.01.01T00:00:00 celebrate new year’ 12345
If you know that 110s and 140s into the last run you did, there were some external events and you want those external event to be shown on the graphs in red, you can recreate graphs using
oltpplot -x ’110 Something happened’ -x ’140 Something else’ -c red -l
The previous example could alternatively be created via a file named m.txt with just these two lines:
110 Something happened 140 Something else
and running
oltpplot -xfile m.txt -c red -l
If you are using srvctl to relocate a service during a run, and you want to mark the start and finish of the relocate on the graphs, use a shell script that includes something like this:
date -u +%Y.%m.%dT%H:%M:%S srvctl relocate service ... -wait date -u +%Y.%m.%dT%H:%M:%S
After the run, you recreate the graphs for the run with information about the start and completion of the relocate by using the output from the two calls to date in your shell script as the time in the --xmarker options to oltprun.
If you want to provide an actual runnumber, this can be done either using the -r option or simply as (the only) non option argument.
Copyright
© 2023 Oracle Corporation
Licensed under the Universal Permissive License v 1.0 as
shown at https://oss.oracle.com/licenses/upl
oltp(2rwl), oltprun(2rwl), oltpkomment(2rwl)