Skip to content

Commit 0580d20

Browse files
authored
feat(unified_analytics): add dependency telemetry to Event.dartCliCommandExecuted (#2425)
- Added optional `pubspecHasFlutterSdk`, `pubspecEnvironmentSdk`, and `pubspecDependencies` parameters to the `Event.dartCliCommandExecuted` constructor. - Implemented FNV-1a hash-based deterministic sorting and chunking for dependencies salted with the canonical dependency set to eliminate alphabetical and global package bias under GA4 parameter limits. - Bumped package version to 8.0.18-wip.
1 parent 1b36aab commit 0580d20

7 files changed

Lines changed: 347 additions & 6 deletions

File tree

‎.github/workflows/unified_analytics.yaml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@ jobs:
2828
include:
2929
- sdk: dev
3030
run-tests: true
31+
- sdk: dev
32+
check-formatting: true
3133
steps:
3234
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
3335
with:
@@ -41,7 +43,7 @@ jobs:
4143
- run: dart analyze --fatal-infos
4244

4345
- run: dart format --output=none --set-exit-if-changed .
44-
if: ${{matrix.run-tests}}
46+
if: ${{matrix.check-formatting}}
4547

4648
- run: dart test
4749
if: ${{matrix.run-tests}}

‎pkgs/unified_analytics/CHANGELOG.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,18 @@
1+
## 8.0.18-wip
2+
3+
- Added optional `pubspecHasFlutterSdk`, `pubspecEnvironmentSdk`, and
4+
`pubspecDependencies` parameters to the `Event.dartCliCommandExecuted`
5+
constructor.
6+
- Dependencies are deterministically sorted and chunked using a hash-based
7+
algorithm salted with the canonical dependency set to fit within Google
8+
Analytics 4 parameter limitations without alphabetical or global package bias.
9+
110
## 8.0.17
211
- Added optional `agentPlugin` parameter to the `Event.dartMCPEvent` constructor to identify
312
agent plugin usage.
413

514
## 8.0.16
6-
715
- Added `Event.packageSkillsEvent` to track events from package:skills.
8-
- Run `dart format`.
916

1017
## 8.0.15
1118
- Added IDE and plugin information to `Event.serverSession`.

‎pkgs/unified_analytics/USAGE_GUIDE.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,38 @@ if (analytics.shouldShowMessage) {
124124
It is important to note events will not be sent if there is a new version of
125125
the consent message.
126126

127+
## Dependency Telemetry & GA4 Parameter Chunking
128+
129+
When transmitting CLI command execution events via
130+
`Event.dartCliCommandExecuted`, the `dart` CLI tool may pass optional project
131+
SDK constraints (`pubspecEnvironmentSdk`), Flutter SDK flags
132+
(`pubspecHasFlutterSdk`), and public dependency lists (`pubspecDependencies`).
133+
134+
To comply with Google Analytics 4 (GA4) string length restrictions (maximum 100
135+
characters per event parameter), `unified_analytics` deterministically sorts
136+
and shuffles the dependency list using a 32-bit FNV-1a hash salted with the
137+
canonical dependency set before partitioning it across 20 distinct event
138+
parameters (`pubspec_dep_0` through `pubspec_dep_19`). This eliminates
139+
alphabetical bias while preventing ecosystem-wide starvation of specific package
140+
names across projects, ensuring statistically uniform ecosystem sampling.
141+
142+
### Guidance for CLI Tool Authors
143+
144+
* **Privacy Filtering**: Callers MUST cross-reference all discovered
145+
dependencies against the authoritative `.dart_tool/package_config.json`
146+
file. Only packages explicitly resolved with a hosted source pointing to
147+
`pub.dev` (or approved public registries) should be passed in
148+
`pubspecDependencies`. Path, git, and intra-workspace member dependencies
149+
must be stripped to prevent leaking confidential internal package names.
150+
* **Project-Level Caching**: In `package:unified_analytics`, a `session_id`
151+
rolls over only after 30 minutes of inactivity. When a developer switches
152+
between different package directories in a workspace within that 30-minute
153+
window, relying on session-level deduplication causes later projects to be
154+
under-reported. CLI tools should maintain a local project state cache
155+
(e.g., a 24-hour TTL mapping project root paths to their last-reported
156+
pubspec hash) so dependencies are captured per project directory without
157+
redundantly re-transmitting on every CLI invocation.
158+
127159
## Developing Within `package:unified_analytics`
128160

129161
### Adding new data classes

‎pkgs/unified_analytics/lib/src/constants.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ const int kMaxLogFileSize = 25 * (1 << 20);
8787
const String kLogFileName = 'dart-flutter-telemetry.log';
8888

8989
/// The current version of the package, should be in line with pubspec version.
90-
const String kPackageVersion = '8.0.17';
90+
const String kPackageVersion = '8.0.18-wip';
9191

9292
/// The minimum length for a session.
9393
const int kSessionDurationMinutes = 30;

‎pkgs/unified_analytics/lib/src/event.dart‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44

55
import 'dart:convert';
66

7+
import 'package:meta/meta.dart';
8+
79
import 'enums.dart';
810

911
final class Event {
@@ -458,16 +460,44 @@ final class Event {
458460
///
459461
/// * [exitCode] - the process exit code set as a result of running the
460462
/// command.
463+
///
464+
/// * [pubspecHasFlutterSdk] - whether the project's pubspec explicitly
465+
/// declares a dependency on the Flutter SDK (e.g. `sdk: flutter` or
466+
/// `environment.flutter`).
467+
///
468+
/// * [pubspecDependencies] - a set of public package names depended upon by
469+
/// the project. Callers MUST verify packages against
470+
/// `.dart_tool/package_config.json` to ensure only public hosted packages
471+
/// (published to pub.dev or public registries) are passed. Non-hosted
472+
/// packages (path, git, un-versioned workspace members) must be excluded
473+
/// to prevent leaking proprietary or internal package names.
474+
///
475+
/// * [pubspecEnvironmentSdk] - the Dart SDK version constraint declared in
476+
/// the project's pubspec (e.g. `^3.5.0` from `environment.sdk:`).
477+
///
478+
/// NOTE FOR MAINTAINERS: Google Analytics 4 limits each event to at most 25
479+
/// custom parameters. With standard metadata fields taking up 4–5 slots and
480+
/// dependency chunking consuming up to 20 parameters (`pubspec_dep_0` through
481+
/// `pubspec_dep_19`), adding any new parameters to this constructor requires
482+
/// decreasing `maxChunks` in [chunkDependencies] to prevent dropping event
483+
/// parameters.
461484
Event.dartCliCommandExecuted({
462485
required String name,
463486
required String enabledExperiments,
464487
int? exitCode,
488+
bool? pubspecHasFlutterSdk,
489+
Set<String>? pubspecDependencies,
490+
String? pubspecEnvironmentSdk,
465491
}) : this._(
466492
eventName: DashEvent.dartCliCommandExecuted,
467493
eventData: {
468494
'name': name,
469495
'enabledExperiments': enabledExperiments,
470496
'exitCode': ?exitCode,
497+
'pubspec_has_flutter_sdk': ?pubspecHasFlutterSdk,
498+
'pubspec_environment_sdk': ?pubspecEnvironmentSdk,
499+
if (pubspecDependencies != null)
500+
...chunkDependencies(pubspecDependencies),
471501
},
472502
);
473503

@@ -1209,3 +1239,106 @@ abstract base class CustomMetrics {
12091239
/// This must be a JSON-encodable [Map].
12101240
Map<String, Object> toMap();
12111241
}
1242+
1243+
/// Public helper in unified_analytics to sort and chunk dependencies.
1244+
///
1245+
/// Respects GA4's 100-character limit per parameter and 25-parameter limit
1246+
/// per event.
1247+
///
1248+
/// To eliminate alphabetical bias (e.g., always omitting packages starting
1249+
/// with 'z' when exceeding the 20-chunk cap) while preventing ecosystem-wide
1250+
/// starvation of specific package names across projects, dependencies are
1251+
/// sorted deterministically using a 32-bit FNV-1a hash salted with the
1252+
/// project's canonical dependency set.
1253+
///
1254+
/// This ensures:
1255+
/// 1. **Cross-Machine Stability**: Identical dependency sets always produce the
1256+
/// exact same deterministic chunk payload across developers and CI runs.
1257+
/// 2. **Cross-Project Diversity**: Different projects produce different hash
1258+
/// permutations, ensuring no package is globally starved across the
1259+
/// ecosystem under truncation.
1260+
/// 3. **Zero PII**: Salt is derived strictly from public package names without
1261+
/// relying on local paths, usernames, or private project identifiers.
1262+
@visibleForTesting
1263+
Map<String, String> chunkDependencies(Set<String> deps) {
1264+
if (deps.isEmpty) return const {};
1265+
1266+
// Compute a deterministic project-level salt from the canonical
1267+
// (alphabetically sorted) dependency set.
1268+
final sortedBase = deps.toList()..sort();
1269+
var setSalt = 2166136261;
1270+
for (final dep in sortedBase) {
1271+
setSalt = _fnv1a(dep, setSalt);
1272+
}
1273+
1274+
// Sort deterministically by salted FNV-1a hash value. Fall back to
1275+
// alphabetical comparison if there is a hash collision to guarantee absolute
1276+
// determinism.
1277+
final sortedDeps = deps.toList()
1278+
..sort((a, b) {
1279+
final hashA = _fnv1a(a, setSalt);
1280+
final hashB = _fnv1a(b, setSalt);
1281+
if (hashA != hashB) {
1282+
return hashA.compareTo(hashB);
1283+
}
1284+
return a.compareTo(b);
1285+
});
1286+
1287+
final chunks = <String, String>{};
1288+
var currentChunk = <String>[];
1289+
var currentLength = 0;
1290+
var chunkIndex = 0;
1291+
1292+
// We have a maximum of 25 parameters per event in GA4. Standard event
1293+
// parameters (name, enabledExperiments, exitCode, pubspec_has_flutter_sdk)
1294+
// take up to 4 slots, leaving 21 slots. Capping at 20 chunks guarantees
1295+
// safety.
1296+
const maxChunks = 20;
1297+
1298+
for (final dep in sortedDeps) {
1299+
// Guard: Skip package names that are somehow longer than 100 characters
1300+
// to prevent violating GA4's value length limit.
1301+
if (dep.length > 100) continue;
1302+
1303+
final lengthToAdd = dep.length + (currentChunk.isEmpty ? 0 : 1);
1304+
if (currentLength + lengthToAdd > 100) {
1305+
chunks['pubspec_dep_$chunkIndex'] = currentChunk.join(',');
1306+
chunkIndex++;
1307+
1308+
// Stop adding chunks if we reach the GA4 parameter count safety limit
1309+
if (chunkIndex >= maxChunks) {
1310+
currentChunk = const [];
1311+
break;
1312+
}
1313+
1314+
currentChunk = [dep];
1315+
currentLength = dep.length;
1316+
} else {
1317+
currentChunk.add(dep);
1318+
currentLength += lengthToAdd;
1319+
}
1320+
}
1321+
1322+
if (currentChunk.isNotEmpty && chunkIndex < maxChunks) {
1323+
chunks['pubspec_dep_$chunkIndex'] = currentChunk.join(',');
1324+
}
1325+
1326+
return chunks;
1327+
}
1328+
1329+
/// Computes a deterministic 32-bit FNV-1a hash of a string with an optional
1330+
/// seed.
1331+
///
1332+
/// This is used to shuffle dependency names in a stable, pseudo-random
1333+
/// way to eliminate alphabetical and global package bias when sampling packages
1334+
/// for telemetry while maintaining 100% determinism across runs.
1335+
int _fnv1a(String s, [int seed = 2166136261]) {
1336+
var hash = seed;
1337+
for (var i = 0; i < s.length; i++) {
1338+
hash ^= s.codeUnitAt(i);
1339+
// Split the multiplication to prevent exceeding the 53-bit safe integer
1340+
// limit on the web.
1341+
hash = (((hash & 0xff) << 24) + (hash * 403)) & 0xffffffff;
1342+
}
1343+
return hash;
1344+
}

‎pkgs/unified_analytics/pubspec.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: >-
55
# LINT.IfChange
66
# When updating this, keep the version consistent with the changelog and the
77
# value in lib/src/constants.dart.
8-
version: 8.0.17
8+
version: 8.0.18-wip
99
# LINT.ThenChange(lib/src/constants.dart)
1010
repository: https://github.com/dart-lang/tools/tree/main/pkgs/unified_analytics
1111
issue_tracker: https://github.com/dart-lang/tools/issues?q=is%3Aissue+is%3Aopen+label%3Apackage%3Aunified_analytics

0 commit comments

Comments
 (0)