Standalone Linux IO Tracer

Standalone Linux IO Tracer (iotrace) is a tool for block device I/O tracing and management of created traces

For each I/O to target device(s) basic metadata information is captured (IO operation type, address, size), supplemented with extended classification. Extended classification contains information about I/O type (direct / filesystem metadata / file) and target file attributes(e.g. file size).

iotrace is based on Open CAS Telemetry Framework (OCTF). Collected traces are stored in OCTF trace location. Traces can later be converted to JSON or CSV format.

iotrace consists of a kernel tracing module (iotrace.ko) and an executable (iotrace) with command line interface.

In this readme:

• Supported OS
• Documentation
• Source Code
• Deployment
• Examples
• Contributing

Supported OS

Right now the compilation of Standalone Linux IO Tracer is tested on the following OSes:

OS	Version
RHEL/CentOS	7.6

Documentation

You can find the Markdown version of the man page for iotrace here. The man page is also installed during installation.

Source Code

Source code is available in the official Standalone Linux IO Tracer GitHub repository:

git clone https://github.com/open-cas/standalone-linux-io-tracer
cd standalone-linux-io-tracer

Deployment

Prerequisites

• To build and use Standalone Linux IO Tracer, OCTF needs to be set up in the following way:

  git submodule update --init --recursive
  sudo ./modules/open-cas-telemetry-framework/setup_dependencies.sh
  

  OCTF will then be installed along with iotrace in the next step.

  NOTE: Alternatively OCTF can also be installed separately, using instructions found in it's README. This option however right now only allows building the cli binary, and not the kernel module

Build

Both the executable and the kernel module (and OCTF if submodule is present) are built with:

make

Installation

Both the executable and the kernel module (and OCTF if submodule is present) are installed with:

sudo make install

Examples

To allow tracing of block devices, tracing module needs to be loaded first:

modprobe iotrace

• Start tracing two block devices for 1 hour, or until trace file is 1GiB:

  sudo iotrace --start-trace --devices /dev/sda,/dev/sdb1 --time 3600 --size 1024
  

• List created traces:

  iotrace --list-traces
  

  Output:

  {
  "trace": [
    {
     "tracePath": "kernel/2019-05-10_15:24:21",
     "state": "COMPLETE"
    }
  ]
  }
  

• Parse traces (note usage of path returned in --list-traces):

  iotrace --parse-trace --path "kernel/2019-05-10_15:24:21" --format json
  

  Output:

  {"header":{"sid":"1","timestamp":"253654431680"},"deviceDescription":{"id":"1","name":"sda","size":62914560}}
  {"header":{"sid":"2","timestamp":"253654431680"},"deviceDescription":{"id":"2","name":"sdb","size":62914560}}
  {"header":{"sid":"3","timestamp":"254719353975"},"io":{"lba":"29664032","len":8,"ioClass":1,"deviceId":"1","operation":"Write","flush":false,"fua":false}}
  {"header":{"sid":"4","timestamp":"254719353975"},"io":{"lba":"29664032","len":8,"ioClass":1,"deviceId":"2","operation":"Write","flush":false,"fua":false}}
  ...
  

Contributing

Please refer to the OCTF contributing guide.

Related Projects

Please explore related projects:

• Open CAS Telemetry Framework framework containing the building blocks for the development of a telemetry and monitoring environment
• Open CAS Framework - high performance block storage caching meta-library
• Open CAS Linux - Linux block storage cache

Notice

NOTICE contains more information