Skip to main content
Version: Next

Tracking Events

The bundle also ships with basis to easily implement a tracker that tracks events to an Elasticsearch/Opensearch index.

Supports Elasticsearch versions 8. Supports Opensearch versions 2.

Implement Tracker​

To implement a tracker, extend the AbstractElasticsearchTracker or AbstractOpensearchTracker and implement all abstract methods:

  • getIndexName: Define the name of index.
  • buildMappingArray: Define mapping for index as array.
  • trackEvent: Method for actual event tracking that is called by outside world. It takes a parameter array, prepares data for tracking (e.g. extracting information, adding timestamp, etc.) and builds structure expected by the mapping, and then calls doTrackEvent (which does the data backend communication).

The abstract base class takes care of all the generic index creation, alias management and data backend communication.

A sample implementation can be found in DummyTracker.

Tracking Events​

For each event type, a tracker needs to be implemented. The tracker implementations then need to be registered as services and then can be injected to any service or controller.

By calling $tracker->trackEvent($parameters) the events get tracked.

Index Structure​

For performance and data housekeeping reasons, the tracker implements some kind of index rotating. This means data is tracked to an index named <INDEX_NAME>__<YEAR>_<MONTH> which always corresponds to the current month. If the index doesn't exist, it is created automatically.

In addition to creation of the indices, there is also an alias <INDEX_NAME> is created. This alias shows to all existing rolled indices and can be used for querying the statistics.

The abstract base class for the tracker takes care of all necessary steps. There are only two things to consider:

  • When implementing tracker is to extend from the abstract base class and implement the abstract methods.
  • When setting up a data source for the explorer, the index alias needs to be used as index name.

Housekeeping itself needs to be done by the administrator of the data backend cluster - by closing/archiving deleting old indices that are not needed anymore for statistics and updating the index alias.

Index Settings​

New indices are created with number_of_replicas set to 0. Without it, the data backend falls back to its own default of one replica, which can never be allocated on a single node cluster and leaves every monthly index permanently yellow. On a multi node cluster, configure the number of replicas you want:

pimcore_statistics_explorer:
    tracker:
        number_of_replicas: 1

The option is applied to trackers registered as services (autoconfiguration) and only to indices that are created afterwards - existing monthly indices keep their setting and have to be updated on the cluster, e.g. PUT <INDEX_NAME>__<YEAR>_<MONTH>/_settings with {"index": {"number_of_replicas": 0}}.

A tracker that is not registered as a service (created with new) can call setNumberOfReplicas() itself.

A tracker that overrides createIndexSettings() defines the settings of its indices on its own. To keep the configured number of replicas, build on the parent settings: array_replace(parent::createIndexSettings(), $ownSettings).