client-cpp  0.10.0
Logging

Log subsystem is based on auto-generated classes according to the log schema used during sdk generation.

Usage

Using default implementations

Kaa library contains default implementation of:

  • log storage;
  • log upload strategy;
  • log upload configuration.

Log storage default implementation persists log records in memory until records aren't uploaded or application restarts.

For example if we have log schema alike:

{
"name": "ExampleLogRecord",
"namespace": "org.kaaproject.kaa.client.example",
"type": "record",
"fields": [
{
"name": "data",
"type": "string"
}
]
}

Which will be converted into:

struct ExampleLogRecord {
std::string data;
};

To create a log record of "ExampleLogRecord" (assuming Kaa client is initialized and started) use:

using namespace kaa;
...
ExampleLogRecord record;
record.data = "Simple log entry";
Kaa::getKaaClient().getLogCollector().addLogRecord(record);

After this record will be added to the storage and LogCollector automatically will check if after adding this record it should start log uploading.
Log upload will start if call to implementation of kaa::ILogUploadStrategy::isUploadNeeded(const kaa::ILogUploadConfiguration* configuration, const kaa::ILogStorageStatus* status) will return kaa::LogUploadStrategyDecision::UPLOAD decision.
In order to define custom log upload strategy see custom_strategy

Creating custom log storage

C++ client sdk provides ability to create custom log storage by implementing kaa::ILogStorage interface.
Once custom log storage implementation is given it is necessary to provide kaa::ILogStorageStatus implementation which monitors log storage statistics for kaa::ILogUploadStrategy.
Use kaa::Kaa::getClient().getLogCollector().setStorage(ILogStorage * storage) and kaa::Kaa::getClient().getLogCollector().setStorageStatus(ILogStorageStatus * storage) to set up custom log storage.

Creating custom log upload strategy

C++ client sdk provides ability to define custom log upload strategy via implementing kaa::ILogUploadStrategy.

Library will invoke kaa::ILogUploadStrategy::isUploadNeeded(const kaa::ILogUploadConfiguration* configuration, const kaa::ILogStorageStatus* status) method on each log record is being added.
This method must return one of kaa::LogUploadStrategyDecision where:

  • NOOP means that no operation should be made;
  • UPLOAD means that log collector should start log upload;
  • CLEANUP means that log collector should shrink log storage to fit the log storage available size.

For example if it is needed to upload each log record immediately method kaa::ILogUploadStrategy::isUploadNeeded(const kaa::ILogUploadConfiguration* configuration, const kaa::ILogStorageStatus* status) should look like:

using namespace kaa;
class ForceUploadStrategy : public ILogUploadStrategy {
public:
LogUploadStrategyDecision isUploadNeeded(const ILogUploadConfiguration* configuration, const ILogStorageStatus* status) {
return LogUploadStrategyDecision::UPLOAD;
}
};

Set up custom upload strategy by calling

ILogUploadStrategy * strategy = new ForceUploadStrategy();
Kaa::getKaaClient().getLogCollector().setUploadStrategy(strategy);

Creating custom log collector configuration holder

Use kaa::ILogUploadConfiguration to configure log upload parameters.
By default log upload configuration contains 3 parameters:

  • max size of log block which can be sent on the wire with single request (8 Kb);
  • max size of memory which can log storage occupy (1 Mb);
  • size of logs when collector should start upload (32 Kb).

See also