Events RFC

[mikrostew]

This proposal describes the events that Notion generates and the API that it provides for plugins to consume these events for reporting metrics.

In brief: For all commands and shims, Notion generates event objects for each major operation, and collects those events in an array. Users can configure a plugin to process the array of events. At the end of the execution of the command or shim, the plugin will be executed in a separate process, and will receive the array of events as JSON in stdin. Notion will exit, and the plugin process will be allowed to run to completion independently in the background. The plugin is responsible for generating metrics from the input events and reporting them appropriately. If there is no plugin configured, the events will be discarded at the end of the command or shim.

Rendered

[mikrostew]

Feedback from conversation with @stefanpenner:

Need to define a schema for errors - we can use https://github.com/ember-cli/console-ui/pull/19 for inspiration. Should include environment vars we care about like PATH, PLATFORM, EXEC_PATH, etc. And should be extensible for future additions.

[mikrostew]

Feedback from conversation with @dherman:

Your idea to just spawn the metrics reporting at the end seems promising. Do we care that this means arbitrary latency for collecting data about e.g. the start of a long-running node process? For example, imagine that you're running a server that might run for days or weeks or months. You won't get an event reported until it exits. Or npm start in general.

If we don't know, a good tie-breaker is "let's do the simplest possible thing and try it out", but good to raise the question.

[benblank]

My initial thoughts re: the plugin process dying are that it shouldn't be Notion's concern.

Once the plugin has been launched, I think it should be entirely the responsibility of the plugin to be a "good citizen" and either exit cleanly or provide notification via e.g. a log file, (inherited) stdout, its typical reports channel, etc. I don't know that Notion has much to offer in that process, beyond a stdout/stderr and perhaps a default log file, if Notion has one.

[dherman]

This is a great write-up of our initial design, and now we have an implementation so we should be able to experiment and get some hands-on experience with it.