Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Diagnostics Best Practices Guide content definition meeting #254

Closed
gireeshpunathil opened this issue Nov 21, 2018 · 20 comments
Closed

Diagnostics Best Practices Guide content definition meeting #254

gireeshpunathil opened this issue Nov 21, 2018 · 20 comments
Labels
diag-deepdive-agenda Used for agenda items related to diagnostic deep dive sessions never stale stale

Comments

@gireeshpunathil
Copy link
Member

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 gireeshpunathil mentioned this issue Nov 21, 2018
Closed
@gireeshpunathil
Copy link
Member Author

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
Copy link
Member Author

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

@mhdawson mhdawson added the diag-deepdive-agenda Used for agenda items related to diagnostic deep dive sessions label Jan 14, 2019
@mhdawson mhdawson mentioned this issue Jan 15, 2019
Closed
@gireeshpunathil
Copy link
Member Author

gireeshpunathil commented Feb 6, 2019 •
edited by RafaelGSS
Loading

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
Copy link
Contributor

Use cases from Diagnostics Summit

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

gireeshpunathil added a commit to gireeshpunathil/diagnostics that referenced this issue Mar 22, 2019
@gireeshpunathil
bestpractices: add crash pre-requisites
dad35e0 
This covers the preparation of crash diagnostics
Refs: nodejs#254
gireeshpunathil added a commit to gireeshpunathil/diagnostics that referenced this issue Mar 22, 2019
@gireeshpunathil
bestpractices: add crash pre-requisites
0138556 
This covers the preparation of crash diagnostics
Refs: nodejs#254
@gireeshpunathil gireeshpunathil mentioned this issue Mar 22, 2019
Closed
@hekike hekike mentioned this issue Apr 22, 2019
Open
@gireeshpunathil gireeshpunathil mentioned this issue Sep 11, 2019
Closed
gireeshpunathil added a commit to gireeshpunathil/diagnostics that referenced this issue Sep 25, 2019
@gireeshpunathil
bestpractices: add crash pre-requisites
2640f91 
This covers the preparation of crash diagnostics
Refs: nodejs#254
@gireeshpunathil
Copy link
Member Author

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
Copy link
Contributor

hekike commented Oct 9, 2019

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
Copy link
Member Author

acknowledged, thanks!

gireeshpunathil added a commit to gireeshpunathil/diagnostics that referenced this issue Oct 16, 2019
@gireeshpunathil
bestpractices: add documentation structure
13616b0 
Refs: nodejs#254 (comment)
@gireeshpunathil gireeshpunathil mentioned this issue Oct 16, 2019
Closed
gireeshpunathil added a commit that referenced this issue Oct 22, 2019
@gireeshpunathil
doc: add documentation structure
ddf7d13 
Refs: #254

PR-URL: #333
Reviewed-By: Michael Dawson <[email protected]>
Reviewed-By: Matheus Marchini <[email protected]>
gireeshpunathil added a commit to gireeshpunathil/diagnostics that referenced this issue Oct 24, 2019
@gireeshpunathil
bestpractices: add crash pre-requisites
471aa1b 
This covers the preparation of crash diagnostics
Refs: nodejs#254
gireeshpunathil added a commit to gireeshpunathil/diagnostics that referenced this issue Oct 26, 2019
@gireeshpunathil
bestpractices: add crash pre-requisites
656947e 
This covers the preparation of crash diagnostics
Refs: nodejs#254
gireeshpunathil added a commit to gireeshpunathil/diagnostics that referenced this issue Oct 26, 2019
@gireeshpunathil
bestpractices: add crash pre-requisites
3e283aa 
This covers the preparation of crash diagnostics
Refs: nodejs#254
gireeshpunathil added a commit that referenced this issue Oct 26, 2019
@gireeshpunathil
doc: add crash pre-requisites [ best practices ]
38a577a 
This covers the preparation of crash diagnostics
Refs: #254

PR-URL: #285
Reviewed-By: Michael Dawson <[email protected]>
Reviewed-By: Peter Marton <[email protected]>
@naugtur naugtur mentioned this issue Oct 27, 2019
Closed
@naugtur
Copy link
Contributor

naugtur commented Oct 27, 2019

Anything covered here: https:/naugtur/node-diagnostics-howtos is available to be added to the guide. I'm hoping to participate as much as my limited free time permits.

@gireeshpunathil
Copy link
Member Author

@naugtur - thank you very much for the offer, and the link. Yes, please feel free to pick up any items of your choice!

After several iterations in diagnostic summit and other working group meetings, we frozen on the prioritized content as defined in #254 (comment) and desired structure as defined in #254 (comment) . So while your content is highly consumable, it would be great if that can be translated to fit to this style?

@naugtur
Copy link
Contributor

naugtur commented Nov 9, 2019

I'm happy to get it to be consistent with the structure there.
Do we have guidelines around tools mentioned in the guides? I don't think we should limit ourselves by avoiding established tools and packages, but I also don't think I should plug my diagnostics experiments package...

@gireeshpunathil
Copy link
Member Author

gireeshpunathil commented Nov 11, 2019 •
edited
Loading

@naugtur - I don't think so (that guidance on tools exists); my take is: best tool for the work at hand:

  • open source / free tool vs. proprietary / paid ones
  • proven ones vs. unproven
  • stable vs. under development
  • minimal features but easy to use vs versatile but complex

If there are specific tools you have in mind, let us discuss it here, in case if that helps.

mhdawson added a commit to mhdawson/io.js that referenced this issue Jan 24, 2020
@mhdawson
doc: guide - using valgrind to debug memory leaks
12d0fe0 
Add doc for using valgrind to debug native
memory leaks.

Started writing this up as part of an effort
in the Diagnostic WG but think it's better
to have it in the core guides and then be referenced
by the docs in the Diagnostic WG repo.

For more details on the Diagnostic WG effort see
nodejs/diagnostics#254 (comment)
This guide is related to `/step3 - using_native_tools.md`
@mhdawson mhdawson mentioned this issue Jan 24, 2020
Closed
3 tasks
@mhdawson
Copy link
Member

PR for valgrind guide - nodejs/node#31501. Will PR reference to it into our https:/nodejs/diagnostics/blob/master/documentation/memory/step4/using_native_tools.md doc once it lands.

mhdawson added a commit to nodejs/node that referenced this issue Feb 14, 2020
@mhdawson
doc: guide - using valgrind to debug memory leaks
79296dc 
Add doc for using valgrind to debug native
memory leaks.

Started writing this up as part of an effort
in the Diagnostic WG but think it's better
to have it in the core guides and then be referenced
by the docs in the Diagnostic WG repo.

For more details on the Diagnostic WG effort see
nodejs/diagnostics#254 (comment)
This guide is related to `/step3 - using_native_tools.md`

PR-URL: #31501
Reviewed-By: Gireesh Punathil <[email protected]>
Reviewed-By: Denys Otrishko <[email protected]>
Reviewed-By: James M Snell <[email protected]>
codebytere pushed a commit to nodejs/node that referenced this issue Feb 27, 2020
@mhdawson @codebytere
doc: guide - using valgrind to debug memory leaks
db291aa 
Add doc for using valgrind to debug native
memory leaks.

Started writing this up as part of an effort
in the Diagnostic WG but think it's better
to have it in the core guides and then be referenced
by the docs in the Diagnostic WG repo.

For more details on the Diagnostic WG effort see
nodejs/diagnostics#254 (comment)
This guide is related to `/step3 - using_native_tools.md`

PR-URL: #31501
Reviewed-By: Gireesh Punathil <[email protected]>
Reviewed-By: Denys Otrishko <[email protected]>
Reviewed-By: James M Snell <[email protected]>
codebytere pushed a commit to nodejs/node that referenced this issue Mar 15, 2020
@mhdawson @codebytere
doc: guide - using valgrind to debug memory leaks
df2355f 
Add doc for using valgrind to debug native
memory leaks.

Started writing this up as part of an effort
in the Diagnostic WG but think it's better
to have it in the core guides and then be referenced
by the docs in the Diagnostic WG repo.

For more details on the Diagnostic WG effort see
nodejs/diagnostics#254 (comment)
This guide is related to `/step3 - using_native_tools.md`

PR-URL: #31501
Reviewed-By: Gireesh Punathil <[email protected]>
Reviewed-By: Denys Otrishko <[email protected]>
Reviewed-By: James M Snell <[email protected]>
codebytere pushed a commit to nodejs/node that referenced this issue Mar 17, 2020
@mhdawson @codebytere
doc: guide - using valgrind to debug memory leaks
693b5d6 
Add doc for using valgrind to debug native
memory leaks.

Started writing this up as part of an effort
in the Diagnostic WG but think it's better
to have it in the core guides and then be referenced
by the docs in the Diagnostic WG repo.

For more details on the Diagnostic WG effort see
nodejs/diagnostics#254 (comment)
This guide is related to `/step3 - using_native_tools.md`

PR-URL: #31501
Reviewed-By: Gireesh Punathil <[email protected]>
Reviewed-By: Denys Otrishko <[email protected]>
Reviewed-By: James M Snell <[email protected]>
codebytere pushed a commit to nodejs/node that referenced this issue Mar 30, 2020
@mhdawson @codebytere
doc: guide - using valgrind to debug memory leaks
de275d0 
Add doc for using valgrind to debug native
memory leaks.

Started writing this up as part of an effort
in the Diagnostic WG but think it's better
to have it in the core guides and then be referenced
by the docs in the Diagnostic WG repo.

For more details on the Diagnostic WG effort see
nodejs/diagnostics#254 (comment)
This guide is related to `/step3 - using_native_tools.md`

PR-URL: #31501
Reviewed-By: Gireesh Punathil <[email protected]>
Reviewed-By: Denys Otrishko <[email protected]>
Reviewed-By: James M Snell <[email protected]>
@mmarchini
Copy link
Contributor

I thought the issue was going to be created today. Did it not work?

@gireeshpunathil
Copy link
Member Author

me too thought the same. looks like the schedule is not ON. will check with @mhdawson to find out the reason.

@mmarchini
Copy link
Contributor

No worries, I'll crate the issue manually this week.

@mhdawson mhdawson mentioned this issue Jul 27, 2020
Closed
@mhdawson mhdawson mentioned this issue Aug 10, 2020
Closed
@github-actions
Copy link

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.

@github-actions github-actions bot added the stale label Sep 29, 2020
@gireeshpunathil
Copy link
Member Author

work is still on

@RafaelGSS RafaelGSS mentioned this issue Nov 11, 2020
Closed
@github-actions
Copy link

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.

@github-actions github-actions bot added the stale label Feb 10, 2021
@RafaelGSS
Copy link
Member

I've added the never stale since it's still in the diag-agenda

This was referenced Aug 15, 2021
Closed
Merged
@github-actions
Copy link

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.

@github-actions github-actions bot added the stale label Jul 25, 2022
@github-actions github-actions bot closed this as completed Aug 9, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
diag-deepdive-agenda Used for agenda items related to diagnostic deep dive sessions never stale stale
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@naugtur @hekike @mmarchini @gireeshpunathil @mhdawson @RafaelGSS