Proposal to drive Diagnostics WG initiatives through user journeys

[hekike]

Intro - Problem Statement

The Node.js Diagnostics WG members meet throughout the year to seek alignment on proposals and prioritize efforts in the Node.js diagnostics space. In the last Diagnostics Summit in Munich, March 2019, we identified that the working group doesn't have a clear articulation of the scope of use cases for users trying to diagnose problems with Node.js processes. The lack of a clear definition around supported diagnostics user journeys and the lack of alignment on long-term supported tooling and best practices lead to a fragmented tooling ecosystem with more than 25 Diagnostics WG identified tools.

This large surface area means that the community is spread thin in their efforts, while also creating an undue focus on specific tools and solutions. We propose that the WG should collect the user use cases, existing and ideal user journeys for our diagnostics solutions and tooling, as well as the gaps that exist, and use it to drive efforts to provide solutions like best practices and sufficient tooling over future LTS releases. We expect that shifting our focus to being more user-centric will help us to improve the runtime for the needs of various Node.js developers around diagnostics and facilitate the continued growth of Node.js adoption.

Goal

The goal of this proposal is to help the Diagnostics WG to prioritize work items and shape the next generation of tooling. We also believe that having a story for long term supported, cross-platform, stable, and developer friendly diagnostics tools will give enterprise companies more confidence in investing in Node.js as the runtime of choice for their use-cases. This can improve the number of meaningful contributions made to the various Node.js Foundation projects.

Proposal

The proposal is to collect and document the most common user journeys and recommended tools with pros and cons in specific scenarios and to highlight the existing tooling gaps today.

The current state of the proposal provides a template for collaborating on the use-cases with some draft around existing solutions and ideas for ideal user journeys. Please check out the current version of the ongoing Node.js WG Diagnostics User Journeys document.

Recommended Next Steps

• Seek alignment on goals
• Agree on shifting focus from specific tools to long-term supported user journeys
• Agree on supported workloads in the first round (API servers, workers etc.)
• Agree on long-term user journey support over LTS releases
• Agree on supported use-cases
• Align on recommended tools for use-cases
• Deep dive meetings per use-cases to create ideal user journeys
• Move the content to GitHub repository
• Use User Journeys to drive the Diagnostics Best Practices initiative
• Regroup on tooling gap and create a long term vision for diagnostic tools

The upcoming Berlin Collaborator Summit could be a good place to seek alignment on some of the topics mentioned above.

Node.js WG Diagnostics User Journeys

[mcollina]

Definitely +1.

[legendecas]

Proposed some doc structures additional to https://github.com/nodejs/diagnostics/pull/333 at https://github.com/nodejs/diagnostics/pull/353.

[mmarchini]

I just realized we're not covering WebAssembly diagnostics. This will probably be a good thing to address on a second version of the docs we're creating.

[RichardLitt]

I'm taking a look at this as someone who isn't heavily invested in the Diagnostics WG, in part to help give back after asking so many questions in #365.

As an external viewer, I don't know how this effort is going. Assuming that this thread and the documents it links to are the only resources, I think that there should be a way of getting quorum and agreeing to next steps. A lot of the steps in the initial comment are either already done, or don't have a clear path for resolution. Specifically:

• [x] Seek alignment on goals
• [x] Agree on shifting focus from specific tools to long-term supported user journeys
• [~] Agree on supported workloads in the first round (API servers, workers etc.)
• [x] Agree on long-term user journey support over LTS releases
• [x] Agree on supported use-cases
• [x] Align on recommended tools for use-cases
• [ ] Deep dive meetings per use-cases to create ideal user journeys
• [~] Move the content to GitHub repository
• [ ] Use User Journeys to drive the Diagnostics Best Practices initiative
• [ ] Regroup on tooling gap and create a long term vision for diagnostic tools

These are done, that I can tell, with - [~] meaning in progress.

In order to move this forward, I would propose that the deep dive for use-cases doesn't happen at a live event (as that may not happen for a while, anyway), but instead happens collaboratively on a shared PR or document. Right now, the biggest blocker that I can see to this is that we don't have an example of what a deep dive should look like. All of the User Journey steps in this linked doc are marked TODO, which means that it's much harder for contributors to imagine what they ought to look like.

Can we make the next step in this process to be:

• [ ] Collaboratively write up a single, complete User Journey test case

I suggest the My application doesn’t behave as expected journey, as that is first in the doc and seems to be fairly low-hanging fruit. Ideally, this question should be raised at the next WG meeting, and then someone should volunteer or be assigned as a DRI to have a first draft ready for the next WG, with comments edited in or assumed done at the second WG afterwards. Does that sound like an actionable plan for moving this effort forward?

Hope this helps.

[mmarchini]

Hi @RichardLitt, thank you for investing time on this!

I suggest the My application doesn’t behave as expected journey, as that is first in the doc and seems to be fairly low-hanging fruit. Ideally, this question should be raised at the next WG meeting, and then someone should volunteer or be assigned as a DRI to have a first draft ready for the next WG, with comments edited in or assumed done at the second WG afterwards. Does that sound like an actionable plan for moving this effort forward?

We haven't updated this issue, but we've been doing this for the past few months now during our WG meetings (except when we have a packed agenda, like the last meeting). Since most of us don't have time to commit outside of the meeting to write such documents, working on those collaboratively during the meeting has proven very effective.

I forgot where these docs are though :sweat_smile:. Maybe @gireeshpunathil or @hekike will be able to answer it better.

[RichardLitt]

Awesome! Glad that this is moving forward, and I hope hoping the information here will help others know that is going on (may be surplus). :)

[mmarchini]

Removed from the agenda since we decided to meet for deep dives on User Journeys every other week. Will re-add if the initiative stalls.

[mmarchini]

CPU Issues deep dive: https://docs.google.com/document/d/1Yip9zU_8axfZwN-clGMeoNWVYHZPfBjepLV3Ur2JjwA/edit

[github-actions[bot]]

This issue is stale because it has been open many days with no activity. It will be closed soon unless the stale label is removed or a comment is made.

[mmarchini]

bad bot

[github-actions[bot]]

This issue is stale because it has been open many days with no activity. It will be closed soon unless the stale label is removed or a comment is made.

[gireeshpunathil]

still relevant

[github-actions[bot]]

This issue is stale because it has been open many days with no activity. It will be closed soon unless the stale label is removed or a comment is made.