Skip to content

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:

  1. 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.
  2. IDE extensions are passing more properties as part of [code suggestions context - v3.0.0]
  3. Existing snowplow events uses extra attribute from standard context to pass an additional information.
  4. New events also sometimes would ideally require more than 3 attributes and limiting them to less requires combining the attribute.

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:

  1. generator should call out usage of label, property, value first and clearly communicate that these should be used before reaching for further, named properties.
  2. Any additional named property needs to be defined in the event definition and have a description
  3. 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
...
Edited by Sebastian Rehm