docs: add Developer document for Performance Profiling in zot #128

mbshields · 2023-09-26T22:16:23Z

What type of PR is this?

documentation

Which issue does this PR fix:

[Feat]: Include a profiling article in the docs
127

What does this PR do / Why do we need it:

explains to developers how to make use of the performance profiling feature in zot

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

andaaron · 2023-09-27T14:38:35Z

docs/developer-guide/pprofiling.md

+
+    /v2/_zot/pprof/
+
+> :pencil2: You must be authenticated to access `/v2/` API commands.


Suggested change

> :pencil2: You must be authenticated to access `/v2/` API commands.

> :pencil2: If you have authentication enabled, only an admin user can access this API.

Done: "If authentication is enabled, only an admin user can access this API."

andaaron · 2023-09-27T14:41:08Z

docs/developer-guide/pprofiling.md

+
+!!! note "Documentation comments"
+
+    Is this section helpful?  Need a more interesting illustration (maybe Flame?)


Need a more typical example, if possible.

rchincha · 2023-09-27T21:14:45Z

docs/developer-guide/pprofiling.md

+
+> :point_right: Use zot's built-in profiling tools to collect and analyze runtime performance.
+
+The profiling capabilities within zot allow a zot administrator to collect and export a range of diagnostic performance data such as CPU intensive function calls, memory allocations, and execution traces. The collected data can then be analyzed using go tools and a variety of available visualization tools.


would add a link from "administrator" to authN/authZ content

Done: "...allow a zot administrator to collect..."

rchincha · 2023-10-06T22:30:53Z

Put profiling document under "Articles" and cross-ref from admin guide (since admin creds/authZ) and developer guide.

rchincha · 2023-10-06T22:31:40Z

docs/developer-guide/pprofiling.md

+
+To collect and export any available profile, use the following API command format:
+
+    /v2/_zot/pprof/<profile-name>[?<query-parameters>]


<profile-type>

Moved to "Articles" and added cross-ref links from other guides.

rchincha · 2023-10-06T22:33:58Z

docs/developer-guide/pprofiling.md

+    /v2/_zot/pprof/
+
+> :pencil2: If authentication is enabled, only an admin user can access this API.
+


Supported Profile Types

zot incorporates golang`s pprof package and therefore the following profile types are supported.

profile
heap
...

These are listed in the previous section "## What data is available?". I added the golang pprof link to that section.

rchincha · 2023-10-06T22:34:27Z

docs/developer-guide/pprofiling.md

+
+    /v2/_zot/pprof/<profile-name>[?<query-parameters>]
+
+The following example shows an API request for the CPU usage profile named `profile` using a collection window of 10 seconds:


... assuming zot is running at localhost:8080

Or at top of this article ...
unless specified, the examples and code snippets in this article assume zot running at localhost:8080

Added note in the top section: "All examples in this article assume that the zot registry is running at localhost:8080."

rchincha · 2023-10-06T22:35:53Z

docs/developer-guide/pprofiling.md

+
+The following example shows an API request for the CPU usage profile named `profile` using a collection window of 10 seconds:
+
+    $ curl -s -v http://localhost:8080/v2/_zot/pprof/profile?seconds=10 > cpu10.prof


Drop the -v and all the curl logs below.

" > cpu.prof"

Changes made.

rchincha · 2023-10-06T22:36:13Z

docs/developer-guide/pprofiling.md

+    { [107 bytes data]
+    * Connection #0 to host localhost left intact
+
+This command creates an output data file named "cpu10.prof".


rchincha · 2023-10-06T22:36:35Z

docs/developer-guide/pprofiling.md

+
+The pprof package can generate graphic representations of profile data in many formats. This example generates a GIF file representing the CPU usage in the "cpu10.prof" file.
+
+    $ go tool pprof -gif cpu10.prof


rchincha · 2023-10-06T22:37:44Z

docs/developer-guide/pprofiling.md

+
+You can collect trace data with the `trace` profile, as in this example:
+
+      $ curl -s -v http://localhost:8080/v2/_zot/pprof/trace?seconds=10 > trace10.prof


"trace.prof"

Also standardize "seconds=30"

rchincha · 2023-10-06T22:38:41Z

mkdocs.yml

@@ -110,6 +110,7 @@ nav:
  - Developer Guide: 
    - Onboarding: developer-guide/onboarding.md
    - Extensions: developer-guide/extensions-dev.md
+    - Performance Profiling: developer-guide/pprofiling.md


Move this under Articles and xref.

rchincha · 2023-10-06T22:39:39Z

docs/developer-guide/pprofiling.md

@@ -0,0 +1,146 @@
+# Performance Profiling in zot


Instead of assets/profile001.gif
Convert this into jpg or png

Rename this file and profiling-001.png

Rename assets/images/flame.svg and profiling-flame.svg

Signed-off-by: mbshields <[email protected]>

rchincha · 2023-10-11T18:18:08Z

docs/general/whats-new.md

@@ -52,6 +52,14 @@

 - You can adjust the background scheduler based on your deployment requirements for tasks that are handled in the background, such as garbage collection.  See [Configuring zot](../admin-guide/admin-configuration.md).

+### Performance profiling for troubleshooting


same thing copied twice here?

Signed-off-by: mbshields <[email protected]>

rchincha

lgtm

mbshields requested a review from rchincha September 26, 2023 22:26

andaaron reviewed Sep 27, 2023

View reviewed changes

andaaron linked an issue Sep 27, 2023 that may be closed by this pull request

[Feat]: Include a profiling article in the docs #127

Closed

rchincha reviewed Sep 27, 2023

View reviewed changes

rchincha reviewed Oct 6, 2023

View reviewed changes

mbshields added 6 commits October 11, 2023 10:35

docs: add Developer document for Performance Profiling in zot

fef91b0

Signed-off-by: mbshields <[email protected]>

docs: rebase and add profiling to What's New

5fff818

Signed-off-by: mbshields <[email protected]>

docs: address initial comments

67b9033

Signed-off-by: mbshields <[email protected]>

docs: address additional comments

2057fad

Signed-off-by: mbshields <[email protected]>

docs: address additional comments - spellcheck

81ebfc2

Signed-off-by: mbshields <[email protected]>

docs: added performance profiling to What's New

681f687

Signed-off-by: mbshields <[email protected]>

mbshields force-pushed the docs_mishield_pprof branch from d01c51c to 681f687 Compare October 11, 2023 17:56

rchincha reviewed Oct 11, 2023

View reviewed changes

docs: remove duplicated entry in What's New

f45d9e2

Signed-off-by: mbshields <[email protected]>

rchincha approved these changes Oct 12, 2023

View reviewed changes

rchincha merged commit 86ba036 into project-zot:main Oct 12, 2023
4 checks passed

mbshields deleted the docs_mishield_pprof branch October 24, 2023 19:54

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add Developer document for Performance Profiling in zot #128

docs: add Developer document for Performance Profiling in zot #128

mbshields commented Sep 26, 2023 •

edited

Loading

andaaron Sep 27, 2023

mbshields Oct 2, 2023

andaaron Sep 27, 2023

mbshields Oct 2, 2023

rchincha Sep 27, 2023

mbshields Oct 2, 2023

rchincha commented Oct 6, 2023

rchincha Oct 6, 2023 •

edited

Loading

mbshields Oct 9, 2023

mbshields Oct 9, 2023

rchincha Oct 6, 2023

mbshields Oct 9, 2023

rchincha Oct 6, 2023

rchincha Oct 6, 2023 •

edited

Loading

mbshields Oct 9, 2023

rchincha Oct 6, 2023

rchincha Oct 6, 2023

mbshields Oct 9, 2023

rchincha Oct 6, 2023

mbshields Oct 9, 2023

rchincha Oct 6, 2023

mbshields Oct 9, 2023

rchincha Oct 6, 2023

rchincha Oct 6, 2023

mbshields Oct 9, 2023

rchincha Oct 6, 2023

mbshields Oct 9, 2023

rchincha Oct 6, 2023

rchincha Oct 6, 2023

mbshields Oct 9, 2023

rchincha Oct 11, 2023

mbshields Oct 11, 2023

rchincha left a comment


		/v2/_zot/pprof/

		> :pencil2: You must be authenticated to access `/v2/` API commands.

	> :pencil2: You must be authenticated to access `/v2/` API commands.
	> :pencil2: If you have authentication enabled, only an admin user can access this API.


		!!! note "Documentation comments"

		Is this section helpful? Need a more interesting illustration (maybe Flame?)


		> :point_right: Use zot's built-in profiling tools to collect and analyze runtime performance.

		The profiling capabilities within zot allow a zot administrator to collect and export a range of diagnostic performance data such as CPU intensive function calls, memory allocations, and execution traces. The collected data can then be analyzed using go tools and a variety of available visualization tools.


		To collect and export any available profile, use the following API command format:

		/v2/_zot/pprof/<profile-name>[?<query-parameters>]

		/v2/_zot/pprof/

		> :pencil2: If authentication is enabled, only an admin user can access this API.


		/v2/_zot/pprof/<profile-name>[?<query-parameters>]

		The following example shows an API request for the CPU usage profile named `profile` using a collection window of 10 seconds:


		The following example shows an API request for the CPU usage profile named `profile` using a collection window of 10 seconds:

		$ curl -s -v http://localhost:8080/v2/_zot/pprof/profile?seconds=10 > cpu10.prof


		The pprof package can generate graphic representations of profile data in many formats. This example generates a GIF file representing the CPU usage in the "cpu10.prof" file.

		$ go tool pprof -gif cpu10.prof


		You can collect trace data with the `trace` profile, as in this example:

		$ curl -s -v http://localhost:8080/v2/_zot/pprof/trace?seconds=10 > trace10.prof

		@@ -52,6 +52,14 @@

		- You can adjust the background scheduler based on your deployment requirements for tasks that are handled in the background, such as garbage collection. See [Configuring zot](../admin-guide/admin-configuration.md).

		### Performance profiling for troubleshooting

docs: add Developer document for Performance Profiling in zot #128

docs: add Developer document for Performance Profiling in zot #128

Conversation

mbshields commented Sep 26, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rchincha commented Oct 6, 2023

rchincha Oct 6, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Supported Profile Types

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rchincha Oct 6, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rchincha left a comment

Choose a reason for hiding this comment

mbshields commented Sep 26, 2023 •

edited

Loading

rchincha Oct 6, 2023 •

edited

Loading

rchincha Oct 6, 2023 •

edited

Loading