General Overview:

The NSA library provides an easy method of added analytics collection to your software. NSA can easily be added to new or existing software and it is a shared library and can be accessed as such. The library is intended to be used with the dlopen family of functions (dlopen, dlclose, dlsym, etc). While it may be possible to link to the NSA library, it is not a currently supported option.

The NSA library is threaded. Major threads include the communication thread pool, the caching thread with queue and the logging thread with queue. All access to the library MUST be started with a call to NalpLibOpen and ended with a call to NalpLibClose. These calls should occur in the main thread of your program. NalpLibOpen creates the threads and performs some general housekeeping. NalpLibClose issues shutdown orders and waits for the threads to complete what they are doing. Shutdown should not take long. The communication thread will complete any ongoing transaction, then pass off the rest of its jobs to the caching thread. The caching thread will write out all the pending jobs to cache and then shutdown. Closing your program without issuing a NalpLibClose can result in data loss.

Examples:

• Nilm - Test program for licensing and analytics
• NSATest - Test loop for passing analytics to Nalpeiron and displaying usage statistics
• [NSATerm] - Simple interactive, menu-driven program similar to Nilm.
• shaferExample - Simple program showing usage of the NSL and NSA libraries in a binary.

Installation:

The NSA library can be installed anywhere that is convenient. The location of the library and the location of the files it creates is specified at library initialization.

Prevention of Data Loss: To prevent data loss, the NSA library caches any information that hasn't been sent in the case of network interrupt, shutdown, or similar circumstances. The cache file is circular with a maximum size equal to the value you stamped into the library. The cache file grows and shrinks to the minimum size necessary to hold the cached data. However, its maximum size is constrained by the size stamped into the NSA library. Once the maximum size has been reached, the cache file wraps around and begins over writting the oldest data. When a successful connection to Nalpeiron is detected, the entire cache will be automatically sent.

Privacy: Nalpeiron has taken several steps to help our customers cope with the many privacy laws around the world. First, there is a privacy setting that can be stamped into the shared library then accessed and changed via NSA functions. Second, Nalpeiron provides geographical location information to the NSA library and incoming data is tagged by country. If incoming data originates in a region where it is illegal to collect such data, the incoming data is dropped and never stored.

The privacy setting (accessed with NSAGetPrivacy and NSASetPrivacy) is used to enable or disable all NSA functions that collect information. If this value is set (= 1), all such functions are disabled. If this value is not set (= 0), the functions are enabled though data may still not be collected due to local privacy laws. If the value has never been set (= 2), the privacy setting stamped into the library is used. The privacy setting is stored along with the cache file and, if that file is deleted, the privacy setting is deleted as well. In this case, the setting defaults to the value stamped into the library until NSASetPrivacy is used.

Nalpeiron has provided privacy controls with the library so you can tailor your data collection to local laws.