-
Notifications
You must be signed in to change notification settings - Fork 18
/
ociping.html
398 lines (288 loc) · 13 KB
/
ociping.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
<!-- Creator : groff version 1.22.3 -->
<!-- CreationDate: Mon Mar 18 08:51:13 2024 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title>ociping</title>
</head>
<body>
<h1 align="center">ociping</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#ORDINARY OPTIONS">ORDINARY OPTIONS</a><br>
<a href="#CONCURRENCY OPTIONS">CONCURRENCY OPTIONS</a><br>
<a href="#USAGE">USAGE</a><br>
<a href="#CONCURRENT RUN">CONCURRENT RUN</a><br>
<a href="#EXAMPLE">EXAMPLE</a><br>
<a href="#CONCURRENCY EXAMPLE">CONCURRENCY EXAMPLE</a><br>
<a href="#NOTES">NOTES</a><br>
<a href="#COPYRIGHT">COPYRIGHT</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<hr>
<h2>NAME
<a name="NAME"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">ociping −
Find OCIPing rates over a database connection</p>
<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>ociping -l
u/p@c [--no-timestamp] [--csvoutput=file] [--interval=N]
[--period=N] [--flush-output] [--flush-csv] [--unixepoch]
[--utctime] [--utcformat=fmt] [--csvexcel] [--concurrency
...]</b></p>
<p style="margin-left:11%; margin-top: 1em">The ociping
utility executes something similar to ping repeatedly
showing the time it takes to execute a single OCIPing over a
database connection. It can be run in concurrency mode,
where the result from many (almost) concurrent executions
will be plotted in a graph. If you also want to show the
time taking to establish connections, use
<a href="connping.html">connping(2rwl)</a>.</p>
<h2>ORDINARY OPTIONS
<a name="ORDINARY OPTIONS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>-l u/p <br>
-l u/p@c</b></p>
<p style="margin-left:17%;">Compulsory option to provide
the username, password, and potentially connect string for a
database connection. If you omit /p, rwloadsim will prompt
for the password.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--interval=N</b></p>
<p style="margin-left:17%;">The interval (in seconds)
between each ping; default 1s.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--period=N</b></p>
<p style="margin-left:17%;">The period in seconds to run
ping; default 60s.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--no-timestamp</b></p>
<p style="margin-left:17%;">Do not include timestamp (in
seconds) in output.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--csvoutput=file</b></p>
<p style="margin-left:17%;">Output timestamp (unless
--no-timestamp) and the OCIPing time separated by space to
the named file.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--flush-output
<br>
--flush-csv</b></p>
<p style="margin-left:17%;">These will flush respectively
stdout and the csv file after each line. This is e.g. useful
if you send stdout to a pipeline using the tee command, or
if you are running tail -f of the csvfile.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--unixepoch</b></p>
<p style="margin-left:17%;">Timestamps will be output in
seconds since the UNIX epoch.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--utctime</b></p>
<p style="margin-left:17%;">Timestamps will be output as
UTC time in format YYYY.MM.DD.HH24:MI:SS.FF2 unless the next
option is also provided.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--utcformat=formatstring</b></p>
<p style="margin-left:17%;">If --utctime is in effect, use
an alternative format string, which musts comply with the
requirements of the Oracle TO_CHAR function.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--csvexcel</b></p>
<p style="margin-left:17%;">If a csv file is being
generated, the header line will not have an initial
’#’, the field separator will be ’;’
and the file will have CRLF line terminators. It it
suggested to also use --utctime
--utcformat=’YYYY/MM/DD HH24:MI:SS’.</p>
<h2>CONCURRENCY OPTIONS
<a name="CONCURRENCY OPTIONS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>--concurrency=N</b></p>
<p style="margin-left:17%;">Specify a number of runs to
perform concurrently with results eventually plotted as
graphs using gnuplot. In this mode, you should normally
always provide values for the next four options. See below
under CONCURRENT RUN for usage details.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--runname=string</b></p>
<p style="margin-left:17%;">Specify a name of your
concurrency run, the name will be use in many generated file
name. It should be a short name consisting of letters,
numerals, hyphen or underscore.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--runtitle=’text
string’</b></p>
<p style="margin-left:17%;">Provide a title that will be
printed on the graphics files.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--imagedir=directory</b></p>
<p style="margin-left:17%;">The resulting image files named
after the runname with a suffix of .svg and .png will be put
in this directory. If at all possible, it is recommended to
chose a directory that can subsequently be browsed from a
browser, i.e. a directory that is made visible by a http
server. The directory will be created using ’mkdir
-p’.</p>
<p style="margin-left:17%; margin-top: 1em">Note that the
default value is the same as resultdir and that you should
always provide a different directory, typically somewhere
under /var/www/html. You can use --imagedir=. to create the
image files in your current directory.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--pngdir=directory</b></p>
<p style="margin-left:17%;">Provide an alternative
directory where the png files will be put.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--resultdir=directory</b></p>
<p style="margin-left:17%;">A concurrency run creates
several intermediate files, in particular csv files with
actual OCIPing() times. These will by default be put in a
temporary directory, which is removed after completion
unless no --imagedir option is provided.</p>
<p style="margin-left:17%; margin-top: 1em">If you want to
inspect these or e.g. modify some gnuplot settings, you can
explicitly name a directory using this option. The directory
will be created using ’mkdir -p’ and a warning
will be shown if it already exists and already has files
from a previous run with the same runname.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--min-ms=D
<br>
--max-ms=D</b></p>
<p style="margin-left:17%;">The y-axis of the graphics will
be the OCIPing() time in ms, and the range will be set from
zero to a value of 4ms by default. You can use these options
to provide a different min or max value on the y-axis.</p>
<p style="margin-left:11%; margin-top: 1em"><b>--plotwith=text
<br>
--plotkey=text</b></p>
<p style="margin-left:17%;">In the graphics plot, that is
generated using gnuplot, the results will by default be
plotting with ’points ps 0.5’ and with the keys
put ’right outside’. You can use these options
to change either of these.</p>
<h2>USAGE
<a name="USAGE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">When executing,
it will show timestamp (unless --no-timestamp is provided)
and the time to perform an OCIPing until the run period is
over, and at the end show averages, standard deviation, min
and max values. The output is in ms. You can kill execution
prematurely by typing ctrl-c.</p>
<h2>CONCURRENT RUN
<a name="CONCURRENT RUN"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">In cases where
the OCIPing() times varies, it is typically useful to see
actual times from a number of executions of ociping. This
can very well be done using a shell script or a simple for
loop in the shell, followed by analyzing the results. To
simplify this, ociping can be executed in concurrency mode,
which does the following:</p>
<p style="margin-left:11%; margin-top: 1em">1. Establish a
number of (almost) concurrent connections to the
database.</p>
<p style="margin-left:11%; margin-top: 1em">2. Use each of
these to run ociping for some period.</p>
<p style="margin-left:11%; margin-top: 1em">3. Save results
from all executions in separate csv files.</p>
<p style="margin-left:11%; margin-top: 1em">4. Use gnuplot
to create a single graph with plots from all executions.</p>
<p style="margin-left:11%; margin-top: 1em">To do so,
provide the --concurrency option to set the number of
concurrent runs together with the --runname, --imagedir and
--runtitle options. The first of these will be used to
generate various file names including the two graphic files
that will be named {runname}.svg and {runname}.png
respectively. All intermediate files will be stored in the
directory provided by --resultdir (by default a directory
created using mktemp -d) and the graphic files will be put
in the --imagedir directory, which should be view-able from
a browser. The --period and --interval options have the same
effect is in normal ociping execution, but none of the
options to format the output or the csv output can be used.
The normal output from ociping will not be shown, but a
simple counter will show progress.</p>
<p style="margin-left:11%; margin-top: 1em">It is
recommended that you use a new runname for each run, as
previous files otherwise will get overwritten.</p>
<p style="margin-left:11%; margin-top: 1em">The generated
svg file will be clickable through the ’mouse
standalone’ option. However, if your gnuplot version
is earlier than 5.2, such as 4.6, you should configure your
webbrower with access to /usr/share/gnuplot/4.6/js as
earlier versions do not support ’mouse
standalone’.</p>
<h2>EXAMPLE
<a name="EXAMPLE"></a>
</h2>
<pre style="margin-left:11%; margin-top: 1em">ociping --csvoutput=ping.csv --period=10 -l username/{password}
RWP*Load Simulator Release 3.0.2.4 Development on Wed, 10 Aug 2022 10:02:47 UTC
Connected default database to:
Oracle Database 21c Enterprise Edition Release 21.0.0.0.0 - Production
0.051 0.0
0.054 1.0
0.196 2.0
0.051 3.0
0.049 4.0
0.050 5.0
0.048 6.0
0.051 7.0
0.064 8.0
0.048 9.0
ociping (ms) mean=0.066, stddev=0.043, min=0.048, max=0.196</pre>
<p style="margin-left:11%; margin-top: 1em">You could
subsequently plot the results using gnuplot with an input
like this:</p>
<pre style="margin-left:11%; margin-top: 1em">set yrange[0:*]
plot "ping.csv" using 1:2 with lines title "OCIPing"</pre>
<h2>CONCURRENCY EXAMPLE
<a name="CONCURRENCY EXAMPLE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">After the above
example, it may be useful to make a concurrency run with 10
executions:</p>
<pre style="margin-left:11%; margin-top: 1em">ociping --period=30 -l username/{password} --concurrency=10 --imagedir=/var/www/html/ping --min-ms=0.03 --max-ms=0.07 --resultdir=$HOME/pingres --runname=myping --runtitle=’text on image files’</pre>
<p style="margin-left:11%; margin-top: 1em">This will
create two files myping.svg and myping.png in the
/var/www/html/ping directory. Note that due to --max-ms=0.07
any outliers longer that 0.07ms will not be put on the
graphs. After execution, $HOME/pingres will contain all 10
csv files and an input file for gnuplot. The latter will be
called myping.plot containing (with some omissions):</p>
<pre style="margin-left:11%; margin-top: 1em">set terminal svg mouse standalone size 640,480
set output ’/var/www/html/ping/myping.svg’
set yrange [0.03:0.07]
set title ’text on image files’
set key right outside
set ylabel ’OCIPing() time in ms (capped at 0.07ms)’
plot ’/home/username/pingres/myping.0001.csv’ using 2:1 with points ps 0.5 title ’1’ , ...
set terminal png
set output ’/var/www/html/ping/myping.png’
replot</pre>
<p style="margin-left:11%; margin-top: 1em">If required,
you can edit this file and rerun gnuplot to change the
plot.</p>
<h2>NOTES
<a name="NOTES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">If you are
using the full distribution of rwloadsim, ociping is an
executable shell script in the bin directory that calls
rwloadsim with the -u option getting ociping.rwl from the
public directory. As a stand alone binary distribution,
ociping is an executable with the ociping.rwl code
embedded.</p>
<h2>COPYRIGHT
<a name="COPYRIGHT"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">Copyright
© 2023 Oracle Corporation <br>
Licensed under the Universal Permissive License v 1.0 as
shown at https://oss.oracle.com/licenses/upl</p>
<h2>SEE ALSO
<a name="SEE ALSO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><a href="rwloadsim.html">rwloadsim(1rwl)</a>,
<a href="connping.html">connping(2rwl)</a>, <a href="utilities.html">utilities(2rwl)</a></p>
<hr>
</body>
</html>