[Usage collection] Usage counters

[Bamieh]

Usage Counters

Usage counters allows plugins to report user triggered events from the server. This api has feature parity with UI Counters on the public plugin side of usage_collection.

Usage counters provide instrumentation on the server to count triggered events such as "api called", "threshold reached", and miscellaneous events count.

It is useful for gathering semi-aggregated events with a per day granularity.
This allows tracking trends in usage and provides enough granularity for this type of telemetry to provide insights such as

• "How many times this threshold has been reached"
• "What is the trend in usage of this api"
• "How frequent are users hitting this error per day"
• "What is the success rate of this operation"
• "Which option is being selected the most/least"

How to use it

To create a usage counter for your plugin, use the API usageCollection.createUsageCounter as follows:

// server/plugin.ts
import { Plugin, CoreStart } from '../../../core/public';
import { UsageCollectionSetup, UsageCounter } from '../../../plugins/usage_collection/server';

export class MyPlugin implements Plugin {
  private usageCounter?: UsageCounter;
  public setup(
    core: CoreStart,
    { usageCollection }: { usageCollection?: UsageCollectionSetup }
  ) {

    /**
     * Create a usage counter for this plugin. Domain ID must be unique.
     * It is advised to use the plugin name as the domain ID for most cases.
     */
    this.usageCounter = usageCollection?.createUsageCounter('<Domain ID>');
    try {
      doSomeOperation();
      this.usageCounter?.incrementCounter({
        counterName: 'doSomeOperation_success',
        incrementBy: 1,
      });
    } catch (err) {
      this.usageCounter?.incrementCounter({
        counterName: 'doSomeOperation_error',
        counterType: 'error',
        incrementBy: 1,
      });
      logger.error(err);
    }
  }
}

Pass the created usageCounter around in your service to instrument usage.

That's all you need to do! The Usage counters service will handle piping these counters all the way to the telemetry service.

Telemetry reported usage

Usage counters are reported inside the telemetry usage payload under stack_stats.kibana.plugins.usage_counters.

{
  usage_counters: {
    dailyEvents: [
      {
        domainId: '<Domain ID>',
        counterName: 'doSomeOperation_success',
        counterType: 'count',
        lastUpdatedAt: '2021-11-20T11:43:00.961Z',
        fromTimestamp: '2021-11-20T00:00:00Z',
        total: 3,
      },
      {
        domainId: '<Domain ID>',
        counterName: 'doSomeOperation_success',
        counterType: 'count',
        lastUpdatedAt: '2021-11-21T10:30:00.961Z',
        fromTimestamp: '2021-11-21T00:00:00Z',
        total: 5,
      },
      {
        domainId: '<Domain ID>',
        counterName: 'doSomeOperation_error',
        counterType: 'error',
        lastUpdatedAt: '2021-11-20T11:43:00.961Z',
        fromTimestamp: '2021-11-20T00:00:00Z',
        total: 1,
      },
    ],
  },
}

Code reviewer?

Closes #81645

I've updated the usage_collection.mocks file which might have affected a few files outside the core team owned files. If you are requested a review please filter by CODEOWNERS and look for changes ❤️ .

Implementation Notes

RxJS is used to handle buffering the events every 5s to avoid redundant SO calls from the same counter.
The service uses a single source$ which keeps the implementation light and allows batching multiple counters as a future enhancement (currently not supported by savedObjects.incrementCounter).

Daily-aggregated events are deleted by a rollup function once they become older than 5 days. Until then telemetry will keep reporting these events in the daily payload.

We've chosen 5 days to make sure all triggered events are reported while accomodating to "The weekend effect".

If usageCollection.usageCounters.enabled is set to false the service will not subscribe to the events source effectively it stops collecitng the data avoiding redundant function calls and if statements. Currently the service will keep on collecting data usage even if telemetry is disabled to stay consistent with other collection services. This can be easily changed via rxjs by changing the subject.connect logic from automtic on subscribe to manually calling connect in the telemetry plugin on start.

Usage counters will be flushed to savedobjects on start once SO is ready. During setup the service will cache any counter increments in an in memory buffer (Rx.RelaySubject).

UI Counters is now using usage counters api to store the counters data. The collector is also fetching the data from the Usage Counters service and filtering on uiCounter domain ID.

UI Counters will trigger roll ups against the deprecated ui-counter saved objects registry until all the previous data is drained. Migration from one SO registry to another is not yet supported hence this draining logic is needed to make sure we dont lose any data from the no longer used ui-counter SO registry. In a future release we can remove the UI Counters roll up code.

The service was implemented closely to how we've implemented other service inside core to allow easier transfer of usage_collection to core in the future.

The service is fully tested: api_integration/usage_counters, api_integration/telemetry, plugin_functional (demo plugin), and unit tests!

[afharo]

Wow! What an effort! Great job @Bamieh! I've added a few comments and NITs. Will review more in detail on Tuesday or when the PR is released from draft. Have a great weekend.

[flash1293]

Kibana app changes LGTM, code review only. Only mock import changes in tests.

[afharo]

I've noticed a potential bug, holding the SOs from being stored.

[pgayvallet]

Only a few NITs and questions

[mattkime]

app services changes look good to me

[afharo]

Tested locally (and played with the APIs). LGTM!

Great PR @Bamieh! 🎉

[pgayvallet]

LGTM once the config renaming is done

[kibanamachine]

💚 Build Succeeded

• continuous-integration/kibana-ci/pull-request
• Commit: 281abd3
• Storybooks Preview

Metrics [docs]

Saved Objects .kibana field count

Every field in each saved object type adds overhead to Elasticsearch. Kibana needs to keep the total field count below Elasticsearch's default limit of 1000 fields. Only specify field mappings for the fields you wish to search on or query. See https://www.elastic.co/guide/en/kibana/master/development-plugin-saved-objects.html#_mappings

id	before	after	diff
usage-counters	-	2	+2

History

• 💚 Build #119524 succeeded 1163f59
• 💚 Build #119372 succeeded 333f0cd
• 💚 Build #119319 succeeded 8619dfc
• 💚 Build #119103 succeeded 0778186
• 💚 Build #118636 succeeded 204134e

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

[kibanamachine]

💚 Backport successful

Status	Branch	Result
✅	7.x

This backport PR will be merged automatically after passing CI.