README.md

Open CAS Telemetry Framework

Open CAS Telemetry Framework (OCTF) contains building blocks for the development of a telemetry and monitoring environment. An example could be an IO tracer for Open-CAS. The major functionality of the OCTF library is:

• creation of telemetry trace with events
• management of captured traces
• parsing traces

Another minor capabilities are:

• providing auto CLI API
• RPC communication interface between OCTF components/services

At the moment the OCTF native Linux library is utilized by Standalone Linux IO Tracer

In this readme:

• Source Code
• Building
• Deployment
• Documentation
• Unit Tests
• Contributing
• Related Projects
• Notice

Source Code

Source code is available in the official OCTF GitHub repository:

git clone https://github.com/open-cas/open-cas-telemetry-framework
cd open-cas-telemetry-framework

Building

To build OCTF, the following tools are needed:

• Google Protocol Buffers, version 3.6.1 or higher, please follow this link for C++ Installation Instructions
• Google Tests for unit tests
• CMake 3.9 or above

NOTE: You can use setup dependencies script to install above tools.

sudo ./setup_dependencies.sh

Building command is:

make

Optionally you can specify environment variables to override:

• build type - 'release' is the default, specifying DEBUG=1 enables 'debug' build.
• build directory - with BUILD_DIR=<dir> statement, default is 'build/<release|debug>.
• installation prefix.

[DEBUG=1] [BUILD_DIR=<BUILD_PATH>] [PREFIX=<INSTALLATION_PATH>] make

Deployment

Installation

For OCTF installation call:

[DEBUG=1] [PREFIX=<INSTALLATION_PATH>] make install

This will install OCTF components: library, headers, configuration file, documentation, etc. If prefix is a relative path then final installation path will be BUILD_PATH/PREFIX. If prefix is an absolute path then final installation path will be PREFIX.

For release build default value of PREFIX is '/'. For debug build (DEBUG=1) default value of PREFIX is './rootfs'.

Configuration

If you would like to change locations where OCTF stores its data, please edit the configuration file. For PREFIX=/ the configuration file is located at /etc/octf/octf.conf.

Configurable variables:

• settings - additional program settings location
• unixsocket - location of creating unix sockets for runtime communication
• trace - trace files location

Default content of file /etc/octf/octf.conf:

{
  "paths": {
  "settings": "/var/lib/octf/settings",
  "unixsocket": "/run/octf/sockets",
  "trace": "/var/lib/octf/trace",
  }
}

Documentation

Doxygen API documentation is available and it can be generated by executing:

make doc

Output doxygen HTML documentation is placed in

build/release/doc/html/index.html

More documentation, tutorial, and examples will be available soon.

Unit Tests

The unit tests are run by executing:

make test

Contributing

Feel like making OCTF better? Don't hesitate to submit a pull request! You can find more information about our contribution process here. In case of any questions feel free to contact maintainers.

Related Projects

Please explore related projects:

• Standalone Linux IO Tracer - the Linux tool for advanced IO tracing that utilizes OCTF
• Open CAS Framework - high performance block storage caching meta-library
• Open CAS Linux - Linux block storage cache

Notice

OCTF uses:

• Google Protocol Buffers
• SeCoe Safe String Library

NOTICE contains more information