contrib/scripts/lioprof/README

   1 # This file is provided under a dual BSD/GPLv2 license.  When using or
   2 # redistributing this file, you may do so under either license.
   3 #
   4 # GPL LICENSE SUMMARY
   5 #
   6 # Copyright(c) 2016 Intel Corporation.
   7 #
   8 # This program is free software; you can redistribute it and/or modify
   9 # it under the terms of version 2 of the GNU General Public License as
  10 # published by the Free Software Foundation.
  11 #
  12 # This program is distributed in the hope that it will be useful, but
  13 # WITHOUT ANY WARRANTY; without even the implied warranty of
  14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 # General Public License for more details.
  16 #
  17 # Contact Information:
  18 # Cong Xu, cong.xu@intel.com
  19 #
  20 # BSD LICENSE
  21 #
  22 # Copyright(c) 2016 Intel Corporation.
  23 #
  24 # Redistribution and use in source and binary forms, with or without
  25 # modification, are permitted provided that the following conditions
  26 # are met:
  27 #
  28 # * Redistributions of source code must retain the above copyright
  29 # notice, this list of conditions and the following disclaimer.
  30 # * Redistributions in binary form must reproduce the above copyright
  31 # notice, this list of conditions and the following disclaimer in
  32 # the documentation and/or other materials provided with the
  33 # distribution.
  34 # * Neither the name of Intel Corporation nor the names of its
  35 # contributors may be used to endorse or promote products derived
  36 # from this software without specific prior written permission.
  37 #
  38 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  39 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  40 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  41 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  42 # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  43 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  44 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  45 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  46 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  47 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  48 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  49
  50
  51
  52
  53 1. Introduction to launcher.sh
  54     This LIOProf logging services script is used to record detailed I/O Tracing
  55 information carried out on Lustre OSS nodes, it requires superuser privilege.
  56
  57 [Input]
  58 (1) Input usage information
  59     Usage: launcher.sh [-a] [-d] [-l] [-h] [-m] [-n] [-o] [-u]
  60         -a  command to launch application
  61         -d  shared nfs directory to store LIOProf logs
  62         -l  lowest Lustre OSS node [Hostname]
  63         -h  highest Lustre OSS node [Hostname]
  64         -m  lowest Lustre Client [Hostname]
  65         -n  highest Lustre Client [Hostname]
  66         -o  use Obdfilter-survey to measure Lustre bandwidth
  67         -u  user name
  68
  69 (2) Input example
  70     a. Launch application
  71         # su
  72         # launcher.sh -l wolf-33 -h wolf-36 -m wolf-38 -n wolf-41 -u USER_NAME \
  73         # -d /home/USER_NAME/lioprof_home -a "mpirun -np 4 hostname"
  74     b. Launch Obdfilter-survey to measure Lustre bandwidth
  75         # su
  76         # launcher.sh -l wolf-33 -h wolf-36 -u USER_NAME \
  77         # -d /home/USER_NAME/lioprof_home -o
  78
  79 [Output]
  80 (1) Output location
  81     All the outputs locate in the directory configured by '-d' argument. In the
  82 above example, logs are stored in /home/USER_NAME/lioprof_home directory.
  83
  84 (2) Application output information
  85     a. job-output: Output of the job.
  86     b. brw:  Disk I/O sizes
  87     c. iostat: Disks bandwidth, CPU utilization
  88     d. rpc: Lustre rpc tracing information
  89
  90 (3) Obdfilter-survey output information
  91     a. obdfilter: Lustre OST bandwidth
  92     *Note: OBDfilter-survey will be running in the background, it will take
  93 some time to finish the measurement. Need to check the status until you see "done!"
  94 in the output of obdfilter.
  95
  96 2. Introduction to parser.sh
  97     This LIOProf RPC Parser is used to parse rpc logs collected from OSS nodes,
  98 it can be run as a normal user (non-admin).
  99
 100 [Input]
 101 (1) Input usage information
 102     Usage: parser.sh [-i] [-x] [-y] [-t]
 103         -i  path to LIOProf rpc tracing logs
 104         -x  lowest Lustre Client [IB IP Address]
 105         -y  highest Lustre Client [IB IP Address]
 106         -t  Type of Operation Code (OPC) (OST_READ 3, OST_WRITE 4)
 107
 108 (2) Input example
 109     # parser.sh -i /home/USER_NAME/lioprof_home/job-1468618740/rpc \
 110     # -x 192.168.1.38 -y 192.168.1.41 -t 3
 111
 112 [Output]
 113 (1) Output location
 114     Output is stored in the same directory as input rpc log. In the above
 115 example, output locates in /home/USER_NAME/lioprof_home/job-1468618740/rpc-out
 116
 117 (2) Output information
 118     Count I/O requests per second.