Page History

...

The following table summarizes the features (or lack thereof) for the various InkAPI "stats" features. Please see the section below on how librecords can be improved to implement some of the features the "V2" implementation adds. I firmly believe that adding these features to librecords will improve the ATS stats system in general, and also make the InkAPI stats APIs based on librecords very flexible. 

Image Modified

Proposal 1: Deprecate old InkAPI stats

...

Going forward, if the "V2" implementation matures, and can replace librecords (both internal and for APIs), it would be good to rename / replace the APIs above with the API names from Proposal #3 (below). This avoids having to migrate to yet another stats API, so while reviewing this, make sure the proposed APIs below will suffice.

Proposal

...

3: Make new librecords based stats APIs

Finally, I'd like to propose adding a new set of APIs to ts/ts.h, exposing the librecords APIs to plugin writers. My proposed APIs are as follows:

  typedef enum
    {
      TS_ERROR = -1,
      TS_SUCCESS = 0
    } TSReturnCode;

  typedef enum
    {
      TS_STAT_TYPE_INT = 1,
      // The following are currently not supported.
      TS_STAT_TYPE_FLOAT,
      TS_STAT_TYPE_STRING,
      TS_STAT_TYPE_COUNTER,
    } TSStatDataType;

  typedef enum
    {
      TS_STAT_PERSISTENT = 1,
      TS_STAT_NON_PERSISTENT
    } TSStatPersistence;

  typedef enum
    {
      TS_STAT_SYNC_SUM = 0,
      TS_STAT_SYNC_COUNT,
      TS_STAT_SYNC_AVG,
      TS_STAT_SYNC_TIMEAVG,
    } TSStatSync;

  inkapi int TSStatCreate(const char *the_name, TSStatDataType the_type, TSStatPersistence persist, TSStatSync sync);

  inkapi INKReturnCodeTSReturnCode TSStatIntIncrement(int the_stat, INK64 amount);
  inkapi INKReturnCodeTSReturnCode TSStatIntDecrement(int the_stat, INK64 amount);
  // Currently not supported.
  // inkapi INKReturnCodeTSReturnCode TSStatFloatIncrement(int the_stat, float amount);
  // inkapi INKReturnCodeTSReturnCode TSStatFloatDecrement(int the_stat, float amount);

  inkapi INKReturnCodeTSReturnCode TSStatIntGet(int the_stat, INK64* value);
  inkapi INKReturnCodeTSReturnCode TSStatIntSet(int the_stat, INK64 value);
  // Currently not supported
  // inkapi INKReturnCodeTSReturnCode TSStatFloatGet(int the_stat, float* value);
  // inkapi INKReturnCodeTSReturnCode TSStatFloatSet(int the_stat, float value);

  inkapi int TSStatFindName(const char* name);

...

I have an implementation for the APIs above that does work. There are four issues with my patch, that would need to be addressed long term (but I think it's OK for a v2.2 release). Most of these are very easy (a few lines of code).

1. Wiki MarkupThe librecords stats system has an internal (static) limitation of 3000 stats. This is easy to bump up to say 8,000 (which my patch does), but it does waste a little memory. There are some multi-dimensional arrays that allocates unnecessary "slots" I think, which we could optimize. These static arrays needs to be modified to be dynamically allocated (and preferably "optimized" to waste less memory), based on the _proxy.config.stat_api.max_stats_allowed_ setting above. This is merely an issue of changing a static allocation (stats\[8000\]) to dynamic allocation at startup (malloc(8000 * sizeof(stats-bucket)).
2. My patch disables the new stats for per hook / plugin counters (they are tied to enabling the V2 stats system). My suggestion would be to rewrite these areas to use the new stats APIs above, once it has been landed. Or even better, use the internal librecords APIs instead, at least where possible (we generally shouldn't use the public InkAPI interfaces in "core" code).
3. I've noticed a noticeable (~30s) time to create 50,000 stats using the new APIs. it's fine for 10,000 stats (which takes less than 0.5 seconds), so it gets progressively worse as more stats are added. This should be examined for sure.
4. The CLI needs to support listing all stats, preferably with substrings and regexes filtering.