Diagnostics Best Practices Guide content definition meeting

[gireeshpunathil]

As derived in #211 I have setup a doodle with an expiry set for 24th to poll for a consensus on meeting dates. The proposed dates are 27/28/29th of this month. Please cast your availability. Thanks in advance!

/cc @mhdawson @mmarchini @mike-kaufman @joyeecheung @naugtur @amiller-gh @i0natan

/cc @nodejs/diagnostics

[gireeshpunathil]

the doodle got only 3 polls, so I guess we need to schedule it for a later date. I will make a new one with revised dates and post it here.

[gireeshpunathil]

I started a fresh poll for 16th, please cast your vote, thanks!

[gireeshpunathil]

As discussed in the 01/16th meeting, here is a draft table that outlines the top symptoms that we would like to have guides for, and associated tools that I picked up based on understanding about the capability of those. Feel free to:

• add yourself to the table
• add items as you deem fit
• propose amendments if any

Symptom Type	Tool/API Name	Guide developer	Guide priority order	Remarks
Memory	heapdump	@naugtur, @hekike, @mmarchini, @mhdawson
Memory	heap profiler	@naugtur, @starkwang
Crash	llnode	@gireeshpunathil
profiling	v8 profiler
profiling	linux profiler	@RafaelGSS
tracing	trace events
live debugging	inspector	@hekike
abnormal termination	many	@hekike, @legendecas
hang	trace cli	@legendecas

[mmarchini]

Use cases from Diagnostics Summit

• Memory leak
• GC pressure
• Premature object promotion to old space
• Event loop saturation
• Hot code paths
• ...

[gireeshpunathil]

We have been thinking further on how to structure the documentation for user jounrey and the best practices, with a reasonable decoupling between them while making a meaningful association.

Here is what I think we can structure it: the user journey document contains journeys (definition of speicif user story, associated symptoms and external manifestations) and then link it with the specific best practice document that deals with the problem determination of that user journey.

This approach addresses two issues:

• the user journey document does not get overloaded with too much content
• improves the discoverability and consumability of the best practices with most relevant document flow

For example:

documentation/user_journeys.md (contains journeys and then points to one of the specific Best practices)

• documentation/abnormal_termination/
  • /setup.md
  • /investigation_flow.md
    • /step1 - using_exit_stack_traces.md
    • /step2 - using_diagnostic_report.md
    • /step3 - using_lldb.md
  • case_study.md
• /Memory/
  • /setup.md
  • /investigation_flow.md
    • /step1 - using_heap_dump.md
    • /step2 - using_gc_traces.md
    • /step3 - using_native_tools.md
  • /case_study.md

We can discuss this further in the upcoming diagnostic working group meeting.

cc @hekike @mhdawson

[hekike]

Discussed on the WG meeting today that it would make sense to consolidate user journey Google Docs into this structure. I can open a PR after the initial structure is merged in.

[gireeshpunathil]

acknowledged, thanks!