ashplot

NAME
SYNOPSIS
OPTIONS
EXAMPLES
BUGS
COPYRIGHT
SEE ALSO

NAME

ashplot − Create a plot of ash data

SYNOPSIS

ashplot [options] -l u/p@c ashplot.rwl

ashplot [options] -l u/p@c ashplot.rwl title text

The ashplot command is used to create a plot of ash data in several different ways:

	1.		Output a single image using X-Windows when DISPLAY is properly set or using Microsoft Windows.
	2.		Create an image file in svg and/or png format.
	3.		Output a continuously updated window using X-Windows or Microsoft Windows.

All output is generated using the gnuplot which therefore must be installed.

The data used to generate the graphs is retrieved from either live data in gv$active_session_history or from the awr repository in dba_hist_active_sess_history. The former is used by default, the latter is used if you provide the --dbid option.

If you do not provide one of the output options, no graph is created, but you will be shown a date interval (with minute resolution) for which data is available. If your goal is to graph data from the awr repository, you are suggested to first use awrreport to identify the databases, instances and snapshot ranges available. This is particularly useful if you are working with an awr repository that contains awr imports from other databases.

OPTIONS

-l u/p
-l u/p@c

Compulsory option to provide the username, password, and potentially connect string for a database connection that provides access to the necessary gv$ and dba_hist views. If you omit /p, ashplot will prompt for the password.

--dbid=<dbid>

Without this option, data in gv$active_session_history will be used. With this option, data in dba_hist_active_sess_history from the database with the provided dbid will be used.

--fromtime=YYYY.MM.DDTHH24:MI
--totime=YYYY.MM.DDTHH24:MI

The output will be limited to the specified date/time range. Note that dates must be in the exact format shown, which is also the format used when outputting the available date range. You can omit : and the MI part or T and the entire time part, and you can use either or both of these options.

--fromminutes=N

Output will be limited to only include data from at most N minutes ago. If you use this option together with either of the previous two, time limits from all will apply.

--output-X

Output the graph using X-Windows; this requires a properly set DISPLAY environment variable.

--output-png=file.png
--output-svg=file.svg

Create output as an image file in either png or svg format.

--output-image=file

Create output as an image in both png and svg formats; the file names will be suffixed with .png and .svg respectively.

--no-svgmouse

If an svg file is being output, do not include mouse javascript code in the file. This is only relevant if your gnuplot version is older than 4.6.

--include-sys

By default, data from anything running under SYS (i.e. with userid of 0) is excluded; if you include this option SYS data will be included.

--maxsessions=N

By default, the y-axis will cover the range from 0 to the largest number of sessions. If there are a few large spikes, this implies the bulk of the data is shown in only a small part of the y-axis. You can use this option to decrease the range of the y-axis such that the bulk of the data is represented on a larger part of the axis.

--w-pixels=N
--h-pixels=N

Provide the width and/or height of the image in pixels; the default is 640x480.

--boxwidth=N

By default, gnuplot "widens" each plotted bar (box in gnuplot terms) such that it touches the next bar, which ensures a plot that has no holes along the x-axis. If the range is short or you otherwise only have few data points available, you can alternatively make a plot that has holes at missing data points if you set a fixed boxwidth using this option. You need to experiment until you find a proper value starting with the value 1; values above 3 or 4 are unlikely to produce nice plots.

--autoupdate=N
--maxautoupdate=N

When using X-Windows or Microsoft Windows to output the graph, you can use the --autoupdate option to make the graph updated every so often. As a result you will see a continuously updated window similar to how performance tools do it. The display will finish after 3600s, unless a different value is set using --maxautoupdate or it is terminated by pressing ctrl-c.

When using auto update, --output-X and --fromminutes=5 are set by default, and none of the options --fromtime, --totime, --dbid and those handling image file output are used.

title text

If there are positional arguments in addition to options, they will be used as the plot title, which otherwise will have a generated default including the start date and time of the plot.

EXAMPLES

This example shows how you can progressively narrow down a certain database and period for which you create the ash plots. Start by listing all available databases and instances in some repository:

awrreport -l system/{password}@tnsalias

which may generate an output like:

dbid con snap cnt instance list
----------- --- -------- -------------
607296874 / 400 1,2
957347207 P 2 1,2
4001460110 12321 1,2,3,4,5,6,7,8

This tells that there is data from three databases available in the repository. Assume the last one is the interesting one, so first create a plot using X-Windows covering the whole available range:

ashplot --output-X --dbid=4001460110 -l system/{password}@tnsalias

which first will show the actual available range and then (potentially after some time) create the plot:

Data available between 2022.03.21T00:47 and 2022.04.02T23:59

You may then want to narrow down the actual time for which the plot it produced:
ashplot --output-X --fromtime=2022.04.01T12 --totime=2022.04.02T12 --dbid=4001460110 -l system/{password}@tnsalias

And finally, you may want to reduce it further, also create image files, and also include SYS sessions:
ashplot --svgmouse --output-image=/var/www/html/myash/myplot --include-sys --fromtime=2022.04.01T17:30 --totime=2022.04.01T20:30 --output-X --dbid=4001460110 -l system/{password}@tnsalias

The image files will be put in the directory /var/www/html/myash, and will be named myplot.png and myplot.svg respectively; if you view the latter in a browser, it will be clickable. You can see an actual sample image at https://github.com/oracle/rwloadsim/blob/master/docs/sample-ash.png.

This final example shows how you can plot all available live data (i.e. from gv$active_session_history):
ashplot --include-sys --output-X -l system/{password}@tnsalias

BUGS

If there are many ash samples, generating the data and subsequently using gnuplot takes a long time.