Blueprints: Collect usage statistics

[bgrgicak]

We would like to understand better how blueprints are used by the community to answer questions like how much certain steps are used what PHP and WP versions users use and similar.

To get some statistics we need to start collecting anonymous data about blueprints.
Playground has a Google Analytics (GA) integration, so we could send custom events to GA and create reports there.

I suggest that we send one event to GA on page load with a structure like this:

{
  event: 'blueprint',
  phpVersion: '<VERSION>',
  wpVersion: '<VERSION>',
  networking: '<true|false>',
  plugins<NUMBER>: '<SLUG>',
  login: '<true|false>',
  phpExtensionBundles: '<STRING>',
  step<NUMBER>: '<STRING>', // name of the step
}

In places where we can have multiple values for a key, I suggest we add a number at the end (plugins1, plugins2).
This way we can still filter all keys that start with plugins in GA to get the values.

@adamziel what do you think about this data structure?

My main concern is that we would need to keep this event up to date as we add new blueprint features, but this way we ensure no sensitive data is sent.

[adamziel]

Would plugins3 be the third installed plugin? Or would it be the plugin installed in the third blueprint step?

My main concern is that we would need to keep this event up to date as we add new blueprint features, but this way we ensure no sensitive data is sent.

Is the flat data structure a technical requirement? Or is it possible to log a deeply nested data structure? Perhaps we could send over a subset of a Blueprint extracted based on a schema? We're already building the TypeScript types to a JSON schema, it wouldn't be that difficult to add a @telemetry annotation to Blueprint properties that are safe to log – that way the curation process would become semi-automated.

[bgrgicak]

We should also add a flag to blueprints that will allow users to opt-out of sending these events.
Maybe features.tracking and make it true by default.

[bgrgicak]

Would plugins3 be the third installed plugin? Or would it be the plugin installed in the third blueprint step?

It would be the third installed plugin. The numbers would be based on the order of keys added and wouldn't have any additional meaning.

Is the flat data structure a technical requirement? Or is it possible to log a deeply nested data structure?

From what I could find in the GA docs it's flat. Now after reading more, it seems like we need to register parameters, so even the naming with numbers wouldn't work.

Alternatively, we can send one event for load with phpVersion, wpVersion, networking, login, and phpExtensionBundles.
Then send separate events for each step. This would be cleaner to implement.

We're already building the TypeScript types to a JSON schema, it wouldn't be that difficult to add a @telemetry annotation to Blueprint properties that are safe to log – that way the curation process would become semi-automated.

Let's do that.

[adamziel]

We should also add a flag to blueprints that will allow users to opt-out of sending these events. Maybe features.tracking and make it true by default.

Such a flag would make sense on the web, but not in Node.js or VS Code or in WordPress core. This sounds like a good query API candidate, e.g. ?tracking=false

[bgrgicak]

Makes sense, we can add it to the query API.

The implementation I had in mind would run only in the browser, so there is no need to add it to blueprints.

[bgrgicak]

Implemented in #1040