dart-lang / tools Goto Github PK

This repository is home to tooling related Dart packages.

License: BSD 3-Clause "New" or "Revised" License

Shell 0.06% Dart 99.94%

tools's Introduction

Overview

This repository is home to tooling related Dart packages. Generally, this means packages published through the tools.dart.dev publisher that don't naturally belong to other topic monorepos (like dart-lang/build, dart-lang/test, or dart-lang/shelf).

Packages

Package	Description	Version
cli_config	A library to take config values from configuration files, CLI arguments, and environment variables.
extension_discovery	A convention and utilities for package extension discovery.
graphs	Graph algorithms that operate on graphs in any representation
unified_analytics	A package for logging analytics for all Dart and Flutter related tooling to Google Analytics.

Publishing automation

For information about our publishing automation and release process, see https://github.com/dart-lang/ecosystem/wiki/Publishing-automation.

For additional information about contributing, see our contributing page.

tools's People

Contributors

Stargazers

Watchers

Forkers

eliasyishak keertip jayoung-lee jcollins-g dantup chris-forks polina-c bkonyi jonasfj kenzieschmoll dyu leighajarett yassminn456 loic-sharma nobodyiam95 parlough

tools's Issues

Delete the locally persisted file log when a user opts out

As discussed with P Counsel

Clean up consent message based on tool using package

When the Flutter tool is using this package the consent message should be

flutter --disable-telemetry

Currently it prints out the confusing command

[dart|flutter] --disable-telemetry

[cli_config] Fix coverage setup

The simple coverage setup from #42 seems to not show up on https://coveralls.io/github/dart-lang/tools.

Either it's misconfigured, or we need to approve it somewhere.

Also, we need to configure it that it's for a sub-package here. As this is a mono-repo with multiple packages.

Explore options for automatically creating a table of events to the readme that have been added

It's hard to tell exactly what events have been added to this package -- we can explore using GitHub actions or something to automatically generate a markdown table that clearly shows what's been added and when.

[nit] Fix dartdocs to have sentences end in periods

Add error handling for malformed session json file

If the user somehow alters the session.json file that is responsible for tracking Google Analytics sessions and it is no longer able to be decoded as json, we need to add some error handling so that any tool using this package doesn't crash

Investigate how to handle malformed log files

I only noticed this when I accidentally typed invalid characters and saved it into the log file, but if the parser is not able to parse each row of the json file, the entire process will fail. As a result, anything that requires calling for analytics.logFileStats() will fail, which includes fetching available surveys.

Sample of what caused the error in my case below

{"client_id":"fe4a035b-bba8-4d4b-a651-ea213e9b8a2c","events":[{"name":"lint_usage_count","params":{"count":1,"name":"unnecessary_parenthesis"}}],"user_properties":{"session_id":{"value":1695847559001},"flutter_channel":{"value":null},"host":{"value":"macOS"},"flutter_version":{"value":"3.14.0-14.0.pre.518"},"dart_version":{"value":"3.2.0-199.0.dev"},"analytics_pkg_version":{"value":"4.0.0"},"tool":{"value":"vscode-plugins"},"local_time":{"value":"2023-09-27 16:46:01.831138 -0400"}}}
{"client_id":"fe4a035b-bba8-4d4b-a651-ea213e9b8a2c","events":[{"name":"lint_usage_count","params":{"count":4,"name":"prefer_final_fields"}}],"user_properties":{"session_id":{"value":1695847559001},"flutter_channel":{"value":null},"host":{"value":"macOS"},"flutter_version":{"value":"3.14.0-14.0.pre.373"},"dart_version":{"value":"3.2.0-174.0.dev"},"analytics_pkg_version":{"value":"3.1.0"},"tool":{"value":"vscode-plugins"},"local_time":{"value":"2023-09-27 16:46:01.866532 -0400"}}}
}}
{"client_id":"fe4a035b-bba8-4d4b-a651-ea213e9b8a2c","events":[{"name":"lint_usage_count","params":{"count":4,"name":"prefer_final_in_for_each"}}],"user_properties":{"session_id":{"value":1695847559001},"flutter_channel":{"value":null},"host":{"value":"macOS"},"flutter_version":{"value":"3.14.0-14.0.pre.373"},"dart_version":{"value":"3.2.0-174.0.dev"},"analytics_pkg_version":{"value":"3.1.0"},"tool":{"value":"vscode-plugins"},"local_time":{"value":"2023-09-27 16:46:01.902782 -0400"}}}

In the example above, the third line item is not a valid record, if we encounter something like this, the package should ignore the malformed line and have the malformed line get phased out on its own since we cap the number of records to store locally

Add flag to `Analytics` instance that disables analytics for that specific run

fyi @bwilkerson

On opt-out, empty the CLIENT_ID, session, and log files

Once the PDD revision has landed, we will need to have the contents of the CLIENT_ID, dart-flutter-telemetry-session.json, and dart-flutter-telemetry.log files deleted when a user decides to opt out. If the user has decided to opt back in, then a new client id will be populated in the CLIENT_ID file, session data will begin to get persisted, and logs will continue to be saved in the log file

PR to remove the PDD flag: #86
PR to clear necessary files on opt-out: #87

☂️ Create a survey handler class to enable package to share surveys

This new class will enable the package to pull information for available surveys from a remote location and work with certain clients of this package (Language server) to share those surveys

fyi @jayoung-lee

Main feature branch:

#109

PR(s) tracking this functionality:

These can be done after pilot:

flutter/uxr#104

[feature request] Add functions for converting between various graph representations

Each of these are valid ways to represent a graph:

Sometimes one particular representation is well suited to an application/algorithm. Implementing such conversions here will be convenient to save packages/applications from doing this work on a per-package basis.

Create new constructor for development with test GA instance

It would be really useful for other Google developers to have access to the test instance in Google Analytics so that there events being sent during testing won't get lost in the production instance.

To achieve this, we should create another constructor Analytics.development(...) that will use different credentials for the test instance

unified_analytics does not understand opt-out from legacy analytics

@jacob314

Currently, unified_analytics does not recognize opt-outs from the legacy analytics. Jacob indicated that this functionality has been discussed as being a possible enhancement for 3.0 to reduce unnecessary prompting, so we should add the ability to read legacy analytics and forward an opt-out there to a reporting=0 in the new config file. We should only forward an opt-out.

Break up single test file into logical files

Currently, there is only one large test file with all of the test cases. They should instead be broken up into logical files so that future maintenance of this package will be easier

Tests for each event constructor to ensure constructors don't change

Refers to comment:

#178 (review)

We should have a test file that constructs each Event constructor (including optional parameters) so that we know if any changes have been made to events that could be a breaking change.

Add an implementation of `transitiveClosure`

https://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm

This should let us deprecate the one in package:collection
https://www.dartdocs.org/documentation/collection/1.14.3/collection/transitiveClosure.html

New event for internal usage within package for logging errors; `UnifiedAnalyticsError`

There are a few areas in the code for the analytics package where we may return null or silently reset the .dart-tool directory to ensure that the clients of this package don't crash the user using flutter, dart, or any other dash tool. We do this because having the analytics package fail should not block users from writing dart code, running flutter apps, etc.

However, there is still value for us to know what is happening to cause these issues. We should create a new event that is fired internally when these silent crashes happen so that we can be aware of what is happening. Or potentially look into setting up crash reporting as well.

Create a querying interface for locally persisted logs

This may not be necessary if we can handle all of the conditions needed for displaying surveys through LogFileStats

Call `initializeDateFormatting` from `package:intl` within constructor of tool

[cli_config] Come up with a schema abstraction

When using JSON/yaml configs and this package, at some point we read data out of the contents-agnostic cli_config and populate a specific config. Some examples:

  List<void Function(Config)> _readFieldsFromConfig() {
    return [
      (config) => _outDir = config.path(outDirConfigKey, mustExist: true),
       // ...

https://github.com/dart-lang/native/blob/973f3ed93dace19864903e17e771a44a2d9955b7/pkgs/native_assets_cli/lib/src/model/build_config.dart#L206

  Map<List<String>, Specification> _getSpecs() {
    return <List<String>, Specification>{
      [strings.llvmPath]: Specification<String>(
        requirement: Requirement.no,
        validator: llvmPathValidator,
        extractor: llvmPathExtractor,
        defaultValue: () => findDylibAtDefaultLocations(),
        extractedResult: (dynamic result) {
          _libclangDylib = result as String;
        },
      ),
     // ...

https://github.com/dart-lang/ffigen/blob/9030eb5120c9e6bfd4e7867ff4cf8e0aded870d3/lib/src/config_provider/config.dart#L255

(This is for the parsing, but often we also have unparsing.)

It would be nice if we could give guidance on how to build these type of abstractions.

In both cases the parsed config always has final late fields to support populating the fields one by one in a loop with closures. So that is common pattern number one.

Moreover, it would be nice if the abstraction would be in such a fashion that it could generate a schema, it that would be possible. This will likely lead to slightly more verbosity:

  List<Specification> _readFieldsFromConfig() {
    return [
      Specification(
        key: outDirConfigKey
        type: path, /* some kind of enum that mirrors the methods on `Config` */
        parse: (config, key) => _outDir = config.path(key, mustExist: true), /* This can be more complicated and throw more validation errors. */
        unparse: (buildConfig, key) => { key : buildConfig.outDir.toFilePath() }
      ),
      // ...

I don't really know how to get rid of the key arguments for parse and unparse.
Also I don't know how to get rid of path and config.path needing to be consistent.
A third question is how to deal with nested specifications.
If anyone has bright ideas, let us know!

Implement futures list internal to analytics instance

Whenever the analytics.send(...) method is invoked, we should add the future into an internal list and await and pending futures when we invoke the analytics.close() method.

This will allow clients using this package to not get blocked by http requests until they are exiting.

Create an issue / PR template for adding new events

We should add an issue and / or PR template to make it easier for package users to add new events

[unified_analytics Bug] Default to `NoOpAnalytics` if write permissions are disabled on home directory

If user's have the permissions on their home directory restricted (ie. read-only), the package should not error out causing the tool using this package to crash. It should instead silently fail for PathAccessException errors and default to disabling analytics for that user.

Reported in flutter/flutter repo

flutter/flutter#127055

[extension_discovery] `findExtensions` fails when there is a package in `package_config.json` with no `packageUri`

I discovered this using flutter gallery. I got an exception and had to add some further print statements to get to the bottom of it, but it turns out the issue was the flutter_gen package. In the package_config.json file, this package is listed as such:

{"name":"flutter_gen","rootUri":"flutter_gen","languageVersion":"2.12"}

This appears to be the only package without a package_uri key. Is the flutter_gen package special? Can we fail gracefully when something like this pops up? This does not affect whether we can find extensions for other packages.

Ensure that `eventData` in the send event method doesn't have any nesting

Valid example for eventData

{
  "x": [1, 2, 3],
  "y": 555,
  "z": false
{

Invalid example

{
  "x": [1, 2, 3],
  "y": 555,
  "z": {     <--- We cannot have additional maps/objects as values
    "a": 5,
    "b": [1, 2]
  }
{

Unclear Description

How are you supposed to use this library? The examples don't make it clear what I have to do to start using the library and what functions I have available.

[cli_config] Configurable Parsers and Validators

Do we want for everything 1. a custom parser, 2 a custom validator. For example, maybe one wants on accept foo and bar as values, but would like to transform a FOO to foo before accepting.
We could have something similar for the config keys as well, where currently I have hardcoded the regexps for what we accept.

Making these things configurable does require us to settle on an API for these.
For example, must the validator callback always throw FormatExceptions?
And what about recoverable errors? If the parse callback recovers from an error (by changing FOO to foo). Should these callbacks always take an Logger? logger argument?

Originally posted by @dcharkes in #45 (comment)

The main thing is right now is by far the easiest time to modify the API, and bolting on different ways of doing validation later is likely going to just make for a cludgy API with lots of ways of doing the same thing.

Agreed. We should deprecate and remove it if we want anther solution before releasing a v1.0.

[unified_analytics] Disable filtering out data from google3

This data is quite useful for me to see what happens when there is an exception. It might make sense to do it for third-party messages, but not for the first party ones. Is it possible to add an option for switch it off when the Dart Analysis Server is compiled inside google3?

Incorrectly sending empty `CLIENT_ID` when enabling telemetry

Currently, when a user runs analytics.setTelemetry(true), we send an event to GA4 saying that the user has opted back in. However, because we clear the CLIENT_ID file when a user opts out, the tool attempts to send an empty string for the CLIENT_ID when opting back in.

We should move the logic to create the client id file before we construct the payload so that the event is being sent with a valid client id.

[unified_analytics] Create class NoOpAnalytics implements Analytics

To un-block rolling flutter/flutter#124015 internally, I had to write a class NoOpAnalytics implements Analytics from this package. However, this will cause problems the next time this interface changes when we try to roll package:unified_analytics internally. Thus, the class should be implemented in this package.

Also, the type ToolInfo should be exported from this package, since it is returned from a public method on Analytics.

Add DashEvent for toggling telemetry collection

Correct usage guide on how to show consent message

https://github.com/dart-lang/tools/blob/main/pkgs/unified_analytics/USAGE_GUIDE.md#displaying-consent-message-to-users

This shows the previous iteration when we were implementing a static method to show the consent message to the client tool. Instead it should be corrected to use the instance getter as shown below

if (analytics.shouldShowMessage) {
  
  // Simulates displaying the message, this will vary from
  // client to client; ie. stdout, popup in IDE, etc.
  print(analytics.getConsentMessage);

  // After receiving confirmation that the message has been
  // displayed, invoking the below method will successfully
  // onboard the tool into the config file and allow for
  // events to be sent on the next creation of the analytics
  // instance
  //
  // The rest of the example below assumes that the tool has
  // already been onboarded in a previous run
  analytics.clientShowedMessage();
}

PR(s) addressing issues:

Creation of event for sending errors from within `package:unified_analytics` itself

This will be helpful to find the name of the error, but this won't include any debugging data (ie. stacktraces). This will help us to find certain errors (ie. unable-to-load-asset, invalid-argument) and how they are trending across different dart and flutter versions.

For example, if we are encountering errors when we try to parse the json file for surveys, we silently catch this error so that clients of this package don't crash. This feature would send an event to GA4 letting us know this happened while still failing silently.

Dart command keep crashing on non-latin environment if google analytics is not available

The dart command keep crashing when

google analytics is not available
the exception contains non-latin letters

PS D:\> dart --disable-analytics
An unexpected error was encountered by the Dart CLI.
Please file an issue at https://github.com/dart-lang/sdk/issues/new with the following details:

Invocation: 'dart --disable-analytics'
Exception: 'Invalid argument (string): Contains invalid characters.: "ClientException with SocketException: 远程计算机拒绝网络连接。\r\n (OS Error: 远程计算机拒绝网络连接。\r\n, errno = 1225), address = www.google-analytics.com, port = 1413, uri=https://www.google-analytics.com/mp/collect?measurement_id=G-04BXPVBCWJ&api_secret=Ka1jc8tZSzWc_GXMWHfPHA"'
Stack Trace:
#0      _UnicodeSubsetEncoder.convert (dart:convert/ascii.dart:85:9)
#1      Latin1Codec.encode (dart:convert/latin1.dart:40:46)
#2      new Response (package:http/src/response.dart:37:49)
#3      GAClient.sendData (package:unified_analytics/src/ga_client.dart:73:47)
<asynchronous suspension>
#4      DartdevRunner.runCommand (package:dartdev/dartdev.dart:180:7)
<asynchronous suspension>
#5      runDartdev (package:dartdev/dartdev.dart:59:16)
<asynchronous suspension>
#6      main (file:///C:/b/s/w/ir/x/w/sdk/pkg/dartdev/bin/dartdev.dart:11:3)
<asynchronous suspension>

update sdk repo for next roll

When rolling this into the sdk, we'll need to update the analyzer code base to account for the changes in #161.

cc @eliasyishak

Remove NoOp Session handler from session.dart

We had shipped a noop session handler because the PDD was not approved at the time of launch, now that it has been approved, we can remove this unused class

Static method to retrieve `DashTool`s logged in the config file

It will be helpful to have access to the different DashTools that have been onboarded on a given user's machine without having to create an instance of the Analytics class. Certain tools may want to know if they have already been added to the config file first because creating the instance would log them into the config file.

Create `suppress` functionality for `Analytics` instance

Currently we have the ability to permanently enable or disable telemetry collection. However, there may be use cases where we want to suppress telemetry collection for one run only. We should add functionality that can suppress collection for the current invocation.

crash reporting

Are there plans for the dash_analytics package to provide support for crash reporting?

add package:dash_analytics

@eliasyishak, we now have a general mono repo for Dart tooling packages. Feel free to open a PR adding dash_analytics here; you'll want to put it as a subdirectory of the pkgs/ dir. You shouldn't need to include any files from your .github dir.

This repo doesn't have a CI set up yet, but I'll do that once we have 1 package here.

Expose the `clientId` on the `Analytics` instance

Currently, we don't have a way to expose the current user's clientId to the dash tool using this package. Exposing this on the Analytics instance as well as the FakeAnalytics instance will be helpful to determine if we are using a NoOp instance.

`LogFileStats` to return record counts by tool and flutter channel count

Currently we have a total aggregate count of all records across all tools, it would be good to also return a count by each tool.

For example:

20 total records

12 flutter-tools
5 dart-tools
3 language-server

We should also extend this logic so that we are collecting which channels recorded which events for flutter

For example:

20 total records

12 stable (flutter channel)
5 beta (flutter channel)
3 master (flutter channel)

Create mock/fake instance to ship out with package

Having a mock that can be provided by the package will enable clients of this tool to validate events are being sent correctly

Functionality to restrict surveys from being shown for certain `DashTools`

We should add functionality that will prevent a survey from being returned by the analytics instance for a given tool. For example, if I had a survey that I don't want to be shown to the flutter tool, we should add a field in the metadata file for excluded tools and have the package handle that.

Use a less generic file name than `config.json`

How about extensions.json? package_extensions.json?

Investigate race conditions on analytics related files

Investigate the potential problems and solutions for the situation where there are multiple dash tools running with this package and are attempting to write to the same log file.

How should we handle this?

Is it okay if some tools have persisted logs that don't get stored locally as a result of simultaneous write operations?

Possibly a lock file, but will this result in some tools hanging on exit as other processes finish writing to logs?

[extension_discovery] Consider `extension/<package>/config.yaml` instead?

Should we use YAML instead of JSON, in extension/<package>/config.yaml, it's more consistent with other tooling.

A bit slower, but given how much we're able to leverage caching in extension_discovery using file modification timestamp, the overhead of parsing YAML might not be so bad. Since we'd never need to do it every time. Only when a config.yaml has been modified since the cache was created.

@kenzieschmoll, wdyt? I think we should do it now or never :D