Skip to content

Home

Jump to bottom
Steven Galgano edited this page Dec 14, 2016 · 1 revision

Welcome to the OpenStatistic wiki!

OpenStatistic is a minimally intrusive library for instrumenting C++ applications with measurement capabilities and realtime data extraction.

OpenStatistic is a self-contained version of EMANE's statistic service.

Latest stable version: 1.0.1

==

Using OpenStatistic

OpenStatistic exists as a singleton service within an application. A singleton is used to make it easier to add instrumentation to applications big and small without requiring extensive refactoring.

Registering Statistics and Tables

To create statistics and tables you register them with the registrar using Registrar::registerNumeric(), Registrar::registerNonNumeric() or Registrar::registerTable().

OpenStatistic retains ownership of all statistics and tables, providing you with borrowed references.

 auto & registrar = OpenStatistic::Service::instance()->registrar();

When you create statistics and tables you choose whether they can be cleared by a connected client.

auto pCount1 =
  registrar.registerNumeric<std::uint64_t>("foo.bar.moo.count1",
                                           OpenStatistic::StatisticProperties::CLEARABLE);

auto pCount2 =
  registrar.registerNumeric<std::uint64_t>("foo.bar.moo.count2",
                                           OpenStatistic::StatisticProperties::CLEARABLE);

auto pCount3 =
   registrar.registerNumeric<std::uint64_t>("foo.bar.count3",
                                             OpenStatistic::StatisticProperties::NONE);

auto pMoo =
  registrar.registerNumeric<std::uint64_t>("moo",
                                           OpenStatistic::StatisticProperties::NONE);

auto pFooTable = registrar.registerTable<std::uint64_t>("foo.bar.moo.FooTable",
  {"Foo","Bar","Moo"},
   OpenStatistic::StatisticProperties::NONE,
   "FooTable description");

Starting the Service

Once all statistics and tables are registered you must start the OpenStatistic service and specify an endpoint to listen on. An endpoint has the following syntax: (<IPv4> | '[' <IPv6> ']' | <hostname> )':' <port>.

OpenStatistic::Service::instance()->start("localhost:47001");

Once the OpenStatistic service has started you can no longer register statistics or tables.

Statistics

Statistics can be any one of the following types:

  • std::int64_t
  • std::uint64_t
  • double
  • bool
  • std::string

Only std::string statistics require the use of Registrar::registerNonNumeric(). All other types use Registrar::registerNumeric().

You can use a registered statistic just like a pointer to its underlying template type.

++*pCount1;

Tables

When you register a table you supply the template index type that will be used to identify a table row and the table column labels. The number of labels determines the number of columns in the table.

Each cell in the table is an OpenStatistic::Any instance and can hold a value of any of the following types:

  • std::int64_t
  • std::uint64_t
  • double
  • bool
  • std::string

When you add a new row you must specify the index for that row and the values to use for the columns.

pFooTable->addRow(i,
    {OpenStatistic::Any{static_cast<uint64_t>(i)},
        OpenStatistic::Any{static_cast<uint64_t>(i*2)},
            OpenStatistic::Any{"moo"}});

You can update all the values of a specified row or just an individual cell.

pFooTable->setCell(1,1,OpenStatistic::Any{pCount3->get()});

Stopping the Service

When you finished with the OpenStatistic service you can stop it to prevent client connections.

OpenStatistic::Service::instance()->stop();

Naming Convention

Statistic and table name format consists of a tree like naming convention where each element in the name tree is separated by a '.'. The more elements in a name, the more specific the name. Client queries are compared to registered names and those query names that match the registered name from the start of the registered name through the length of the query name are returned.

For example, a statistic named A.B.C.D may belong to a logical grouping of statistics consisting of A.B.C.D, A.B.C.E and A.B.C.F. Querying for A.B.C.D will only match that single registered statistic. Querying for A.B.C will match A.B.C.D, A.B.C.E and A.B.C.F. Likewise, specifying just A will match all registered statistics that start with A.

Threading

OpenStatistic is thread safe. Each registered statistic and table is protected by its own synchronization object.

Accessing Statistics and Tables

You can access statistics and tables using the ostatistic utility.

usage: ostatistic [OPTION]... <hostname> <command> <target> [names]...

positional arguments:
  hostname              libostatistic host name or address
  {get,clear}           command action
  {stat,table}          target of command action
  names                 names of individual items to target where none
                        means all

optional arguments:
  -h, --help            show this help message and exit
  -p PORT, --port PORT  libostatistic listen port [default: 47001]

Below are some examples using ostatistic.

[me@host ~]$ ostatistic localhost get stat
 foo.bar.count3 = 8
 foo.bar.moo.count1 = 8
 foo.bar.moo.count2 = 8
 moo = 8

 [me@host ~]$ ostatistic localhost get stat foo
 foo.bar.count3 = 11
 foo.bar.moo.count1 = 11
 foo.bar.moo.count2 = 11

 [me@host ~]$ ostatistic localhost get stat foo.bar.moo
 foo.bar.moo.count1 = 16
 foo.bar.moo.count2 = 16

 [me@host ~]$ ostatistic localhost get stat m
 moo = 21

 [me@host ~]$ ostatistic localhost get table
 foo.bar.moo.BarTable
 | Bar | Foo | Moo |

 foo.bar.moo.FooTable
 | Foo | Bar | Moo |
 | 0   | 0   | moo |
 | 1   | 26  | moo |
 | 2   | 4   | moo |
 | 3   | 6   | moo |
 | 4   | 8   | moo |
 | 5   | 10  | moo |
 | 6   | 12  | moo |
 | 7   | 14  | moo |
 | 8   | 16  | moo |
 | 9   | 18  | moo |
Clone this wiki locally