Allow more than 3 additional properties in Internal Events
Problem
There are many cases where it would be desirable to add additional properties to an event besides just the label
(string), property
(string) and value
(number). To give a few examples:
- AI Gateway is passing more properties as part of code suggestions context - v1.0.0, If we want to migrate it to InternalEvents, we must allow more than 3 additional Properties.
- IDE extensions are passing more properties as part of [code suggestions context - v3.0.0]
- Existing snowplow events uses
extra
attribute from standard context to pass an additional information. - New events also sometimes would ideally require more than 3 attributes and limiting them to less requires combining the attribute.
- Example: In gitlab-org/cluster-integration/gitlab-agent#533 (comment 1846062696) they want to track
agent_version
,kubernetes_version
,os
,architecture
, we at least need to combineos
andarchitecture
in this case, which makes the data less querieable.
- Example: In gitlab-org/cluster-integration/gitlab-agent#533 (comment 1846062696) they want to track
This is good opportunity for Analytics Instrumentation to unify all these use cases into InternalEvents.
Desired Outcome
We should allow additional properties apart from label
(string), property
(string) and value
(number). These can be custom property names or predefined names.
Proposed Solution
Use the extra
field in Standard context since it is already parsed out to send the additional fields. (Outcome of #462378 (comment 1912619617))
API structure should look like the following:
track_internal_event(
"code_suggestion_requested",
additional_properties: {
label: suggestion_id,
property: suggestion_model,
value: token_amount,
lang: suggestion_lang
}
)
While we are using extra
behind the scenes we'll still need to make sure that devs use the additional power correctly, we should still establish guidelines and validations as pointed out by @syasonik above:
- generator should call out usage of
label
,property
,value
first and clearly communicate that these should be used before reaching for further, named properties. - Any additional named property needs to be defined in the event definition and have a description
- Validations should create a warning if
label
,property
are unused when someone defines a custom property in their event definition.
Example event definition:
---
description: A code suggestion was requested
action: suggestion_requested
identifiers:
- user
- namespace
additional_properties:
label:
description: id of the suggestion for cross-referencing events
property:
description: The LLM model being used in the suggestion
value:
description: The amount of tokens input into the LLM
lang:
description: The language a suggestion was requested in
product_section: dev
...