Skip to content

Commit

Permalink
refactor: migrate analytics collector to use GA4
Browse files Browse the repository at this point in the history
This change updates the analytics collector collector to use GA4 instead of UA. The motivation behind this change is that UA will stop collecting data in 2023.

BREAKING CHANGE:

`analyticsSharing` option in the global angular configuration has been
removed without replacement. This option was used to configure the Angular CLI to  access to your own users' CLI usage data.

If this option is used, it can be removed using `ng config --global cli.analyticsSharing undefined`.
  • Loading branch information
alan-agius4 committed Oct 11, 2022
1 parent 6c3f281 commit 639a307
Show file tree
Hide file tree
Showing 32 changed files with 555 additions and 807 deletions.
127 changes: 58 additions & 69 deletions docs/design/analytics.md
Expand Up @@ -4,7 +4,7 @@ This document list exactly what is gathered and how.

Any change to analytics should most probably include a change to this document.

# Pageview
## Pageview

Each command creates a pageview with the path `/command/${commandName}/${subcommandName}`. IE.
`ng generate component my-component --dryRun` would create a page view with the path
Expand All @@ -16,7 +16,7 @@ Project names and target names will be removed.
The command `ng run some-project:lint:some-configuration` will create a page view with the path
`/command/run`.

# Dimensions
## Dimensions and Metrics

Google Analytics Custom Dimensions are used to track system values and flag values. These
dimensions are aggregated automatically on the backend.
Expand All @@ -25,94 +25,83 @@ One dimension per flag, and although technically there can be an overlap between
simplicity it should remain unique across all CLI commands. The dimension is the value of the
`x-user-analytics` field in the `schema.json` files.

To create a new dimension (tracking a new flag):

1. Create the dimension on analytics.google.com first. Dimensions are not tracked if they aren't
defined on GA.
### Adding dimension or metic.
1. Create the dimension or metric in (https://analytics.google.com/)[Google Analytics] first. These are not tracked if they aren't
defined in Google Analytics.
1. Use the ID of the dimension as the `x-user-analytics` value in the `schema.json` file.
1. Add a new row to the table below in the same PR as the one adding the dimension to the code.
1. New dimension PRs need to be approved by the tooling and DevRel leads.
**This is not negotiable.**
1. New dimension and metrics PRs need to be approved by the tooling lead and require a new (http://go/launch)[Launch].

### Deleting a dimension or metic.
1. Archive the dimension and metric in (https://analytics.google.com/)[Google Analytics].


**DO NOT ADD `x-user-analytics` FOR VALUES THAT ARE USER IDENTIFIABLE (PII), FOR EXAMPLE A
PROJECT NAME TO BUILD OR A MODULE NAME.**

Note: There's a limit of 20 custom dimensions.
### Limits
| Item | Standard property limits |
|-------------------------------- |-------------------------- |
| Event-scoped custom dimensions | 50 |
| User-scoped custom dimensions | 25 |
| All custom metrics | 50 |

### List Of All Dimensions
### List Of User Custom Dimensions

<!--USER_DIMENSIONS_TABLE_BEGIN-->
| Name | Parameter | Type |
|:---:|:---|:---|
| Command | `ep.ng_command` | `string` |
| SchematicCollectionName | `ep.ng_schematic_collection_name` | `string` |
| SchematicName | `ep.ng_schematic_name` | `string` |
| Standalone | `ep.ng_standalone` | `string` |
| Style | `ep.ng_style` | `string` |
| Routing | `ep.ng_routing` | `string` |
| InlineTemplate | `ep.ng_inline_template` | `string` |
| InlineStyle | `ep.ng_inline_style` | `string` |
| BuilderTarget | `ep.ng_builder_target` | `string` |
| Aot | `ep.ng_aot` | `string` |
| Optimization | `ep.ng_optimization` | `string` |
<!--USER_DIMENSIONS_TABLE_END-->

### List Of Event Custom Dimensions

<!--DIMENSIONS_TABLE_BEGIN-->
| Id | Flag | Type |
| Name | Parameter | Type |
|:---:|:---|:---|
| 1 | `CPU Count` | `number` |
| 2 | `CPU Speed` | `number` |
| 3 | `RAM (In GB)` | `number` |
| 4 | `Node Version` | `number` |
| 5 | `Flag: --style` | `string` |
| 6 | `--collection` | `string` |
| 7 | `Flag: --strict` | `boolean` |
| 8 | `Angular CLI Major Version` | `string` |
| 9 | `Flag: --inline-style` | `boolean` |
| 10 | `Flag: --inline-template` | `boolean` |
| 11 | `Flag: --view-encapsulation` | `string` |
| 12 | `Flag: --skip-tests` | `boolean` |
| 13 | `Flag: --aot` | `boolean` |
| 14 | `Flag: --minimal` | `boolean` |
| 15 | `Flag: --standalone` | `boolean` |
| 16 | `Flag: --optimization` | `boolean` |
| 17 | `Flag: --routing` | `boolean` |
| 18 | `Flag: --skip-import` | `boolean` |
| 19 | `Flag: --export` | `boolean` |
| 20 | `Build Errors (comma separated)` | `string` |
| Command | `ep.ng_command` | `string` |
| SchematicCollectionName | `ep.ng_schematic_collection_name` | `string` |
| SchematicName | `ep.ng_schematic_name` | `string` |
| Standalone | `ep.ng_standalone` | `string` |
| Style | `ep.ng_style` | `string` |
| Routing | `ep.ng_routing` | `string` |
| InlineTemplate | `ep.ng_inline_template` | `string` |
| InlineStyle | `ep.ng_inline_style` | `string` |
| BuilderTarget | `ep.ng_builder_target` | `string` |
| Aot | `ep.ng_aot` | `string` |
| Optimization | `ep.ng_optimization` | `string` |
<!--DIMENSIONS_TABLE_END-->

# Metrics

### List of All Metrics
### List Of Event Custom Metrics

<!--METRICS_TABLE_BEGIN-->
| Id | Flag | Type |
| Name | Parameter | Type |
|:---:|:---|:---|
| 1 | `NgComponentCount` | `number` |
| 2 | `UNUSED_2` | `none` |
| 3 | `UNUSED_3` | `none` |
| 4 | `UNUSED_4` | `none` |
| 5 | `Build Time` | `number` |
| 6 | `NgOnInit Count` | `number` |
| 7 | `Initial Chunk Size` | `number` |
| 8 | `Total Chunk Count` | `number` |
| 9 | `Total Chunk Size` | `number` |
| 10 | `Lazy Chunk Count` | `number` |
| 11 | `Lazy Chunk Size` | `number` |
| 12 | `Asset Count` | `number` |
| 13 | `Asset Size` | `number` |
| 14 | ` Polyfill Size` | `number` |
| 15 | ` Css Size` | `number` |
| AllChunksCount | `epn.ng_all_chunks_count` | `number` |
| LazyChunksCount | `epn.ng_lazy_chunks_count` | `number` |
| InitialChunksCount | `epn.ng_initial_chunks_count` | `number` |
| ChangedChunksCount | `epn.ng_changed_chunks_count` | `number` |
| DurationInMs | `epn.ng_duration_ms` | `number` |
<!--METRICS_TABLE_END-->

# Operating System and Node Version

A User Agent string is built to "fool" Google Analytics into reading the Operating System and
version fields from it. The base dimensions are used for those.

Node version is our App ID, but a dimension is also used to get the numeric MAJOR.MINOR of node.

# Debugging

Using `DEBUG=ng:analytics` will report additional information regarding initialization and
decisions made during the usage analytics process, e.g. if the user has analytics disabled.

Using `DEBUG=ng:analytics:command` will show the decisions made by the command runner.

Using `DEBUG=ng:analytics:log` will show what we actually send to GA.
## Debugging

See [the `debug` NPM library](https://www.npmjs.com/package/debug) for more information.
Using `NG_DEBUG=1` will enable Google Analytics debug mode, To view the debug events, in Google Analytics go to `Configure > DebugView`.

# Disabling Usage Analytics
## Disabling Usage Analytics

There are 2 ways of disabling usage analytics:

1. using `ng analytics off --global` (or changing the global configuration file yourself). This is the same
1. using `ng analytics disable --global` (or changing the global configuration file yourself). This is the same
as answering "No" to the prompt.
1. There is an `NG_CLI_ANALYTICS` environment variable that overrides the global configuration.
That flag is a string that represents the User ID. If the string `"false"` is used it will
Expand Down
8 changes: 8 additions & 0 deletions goldens/circular-deps/packages.json
Expand Up @@ -2,5 +2,13 @@
[
"packages/angular_devkit/build_angular/src/utils/bundle-calculator.ts",
"packages/angular_devkit/build_angular/src/webpack/utils/stats.ts"
],
[
"packages/angular/cli/src/analytics/analytics-collector.ts",
"packages/angular/cli/src/command-builder/command-module.ts"
],
[
"packages/angular/cli/src/analytics/analytics.ts",
"packages/angular/cli/src/command-builder/command-module.ts"
]
]
32 changes: 0 additions & 32 deletions packages/angular/cli/lib/config/workspace-schema.json
Expand Up @@ -74,22 +74,6 @@
"type": ["boolean", "string"],
"description": "Share pseudonymous usage data with the Angular Team at Google."
},
"analyticsSharing": {
"type": "object",
"properties": {
"tracking": {
"description": "Analytics sharing info tracking ID.",
"type": "string",
"pattern": "^(GA|UA)?-\\d+-\\d+$"
},
"uuid": {
"description": "Analytics sharing info universally unique identifier.",
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
},
"cache": {
"description": "Control disk cache.",
"type": "object",
Expand Down Expand Up @@ -149,22 +133,6 @@
"type": ["boolean", "string"],
"description": "Share pseudonymous usage data with the Angular Team at Google."
},
"analyticsSharing": {
"type": "object",
"properties": {
"tracking": {
"description": "Analytics sharing info tracking ID.",
"type": "string",
"pattern": "^(GA|UA)?-\\d+-\\d+$"
},
"uuid": {
"description": "Analytics sharing info universally unique identifier.",
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
},
"completion": {
"type": "object",
"description": "Angular CLI completion settings.",
Expand Down

0 comments on commit 639a307

Please sign in to comment.