doc/development/internal_analytics/instrumentation_layer.md
The Single Instrumentation Layer is an event tracking abstraction that allows to track any events in GitLab using a single interface. It uses events definitions from Internal Event framework to declare event processing logic.
The Single Instrumentation Layer allows to:
Event definitions are used as a declarative specification for processing logic and are the single source of truth for event properties, tracking parameters, and other metadata.
When the Instrumentation Layer tracking method is called (InternalEventsTracking.track_internal_event),
the Instrumentation Layer passes the payload to Internal Events. If extra trackers are defined for the event,
they are called in order of declaration and the original payload is passed as a parameter. For more information,
see how to implement it for your tracking system.
flowchart TD
A[Application code] -->|.track_internal_event| B(Instrumentation Layer)
B --> C[Extra trackers]
B --> D[Internal Events]
C -->|Ai Tracking| E[AiTracking.track_event]
C -->|Contribution Analytics| F[ContributionAnalyticsTracking.track_event]
D --> G[Redis/HLL Counters, Service Ping metrics]
D --> |Snowplow tracking enabled?| H[Snowplow]
When an event is intended to be processed by tracking systems (for example, AiTracking), the event definition is extended to include the additional processing logic. example
This logic is declared using additional processing classes using standard interface.
To implement it for your tracking system, you need to:
Add a new event definition or use existing one (see events dictionary).
Implement the processing logic in a new tracking class. The class should have a class method track_event that accepts
an event name and additional named parameters
module Gitlab
module Tracking
class NewTrackingSystemProcessor
def self.track_event(event_name, **kwargs)
# add your tracking logic here
end
end
end
end
Extend the event definition with the new tracking class added in extra_trackers: property
extra_trackers:
- tracking_class: Gitlab::Tracking::NewTrackingSystemProcessor
protected_properties:
processor_type:
description: The type of the processor
protected_properties contains properties to be sent exclusively to the specified tracking class.
Trigger the event in your code using Internal Events framework
**kwargs is used to pass additional parameters to the tracking class from the Internal Events framework.
The actual parameters depend on the tracking parameters passed to the event invocation above.
Usually, it includes user, namespace and project along with protected_properties that can be used to pass any additional data.
The tracking systems are triggered by the order of the extra_trackers: property.