Generate metrics reference docs #2164

lambdanis · 2024-02-28T16:57:29Z

Add a metrics reference documentation page, autogenerated with github.com/isovalent/metricstool.

Fixes #1856

willfindlay

This looks AMAZING 🎉

Makefile

mtardy · 2024-02-29T09:25:31Z

Where's the Netlify preview link when we need it?

Preview here.

mtardy

Thanks, that will be a very useful addition to the doc!! Sorry I reviewed that one first but I wanted to highlight some things on the output of the autogenerated page.

mtardy · 2024-02-29T09:26:54Z

cmd/tetra/metrics/print.go

+		"events":    "Tetragon Events",
+	}
+
+	overrides := []metricsmd.LabelOverrides{


do you need to provide "false" values here or can you just pass an empty object? Can be a bit misleading

I could pass empty strings as label values, then the docs would still list the label names but not values.

I'm thinking having example values is helpful (users can see the format), but currently the reference doesn't distinguish between example and real values, so I see how it can be misleading. Maybe the next iteration of metricstool could support rendering example and real label values differently or something.

For the build info labels specifically, we can make them less confusing by updating them on a release too.

docs/content/en/docs/reference/metrics.md

mtardy · 2024-02-29T09:35:27Z

docs/content/en/docs/reference/metrics.md

I made some comments on the output of your tool, I see two ways of tweaking stuff:

maybe you want your output to be consistent with a previous behavior and then we need some sed commands to modify the output as I do with gRPC and Helm (because I don't control the tool).

you can simply modify your tool output directly.

pkg/metrics/policystatemetrics/policystatemetrics.go

This will allow to drop the "autogenerated" comment when rendering the metrics reference as a Hugo docs page. Requested here: cilium/tetragon#2164 (comment) Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

This is useful when the metrics reference is embedded in another markdown document. Requested here: cilium/tetragon#2164 (comment) cilium/tetragon#2164 (comment) Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

This will allow to drop the "autogenerated" comment when rendering the metrics reference as a Hugo docs page. Requested here: cilium/tetragon#2164 (comment) Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

This is useful when the metrics reference is embedded in another markdown document. Requested here: cilium/tetragon#2164 (comment) cilium/tetragon#2164 (comment) Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

This command utilizes github.com/isovalent/metricstool/pkg/metricsmd to generate a metrics reference. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

`make metrics-docs` generates metrics reference documentation page using `tetra metrics-docs` command. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

Split InitMetrics function into multiple functions to divide metrics into logical groups. Introduce InitMetricsForDocs function used in `tetra metrics-docs` command. There are no functional changes in this commit. This refactoring is a preparation for further improvements in the generated metrics docs. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

netlify · 2024-03-01T16:38:43Z

✅ Deploy Preview for tetragon ready!

Name	Link
🔨 Latest commit	`b509234`
🔍 Latest deploy log	https://app.netlify.com/sites/tetragon/deploys/65e212292146b100086a212f
😎 Deploy Preview	https://deploy-preview-2164--tetragon.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

Update metrics-docs tetra command and Makefile rule to split metrics reference into three sections: health metrics, resources metrics and events metrics. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

Initialize tetragon_events_total with all possible event types and example process metadata. Initialize tetragon_policy_events_total with example policy and kprobe. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

Initialize tetragon_generic_kprobe_merge_errors_total with all possible error types and example kprobes. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

Initialize tetragon_syscalls_total with example syscall and process metadata. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

observer.bpfCollector doesn't report any metrics if Tetragon isn't fully initialized - so also when we generate metrics docs with tetra. To include observer BPF metrics in metrics docs, let's define a "fake" collector - observer.bpfZeroCollector - reporting same metrics as observer.bpfCollector but with hardcoded zero values. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

eventmetrics.bpfCollector doesn't report any metrics if Tetragon isn't fully initialized - so also when we generate metrics docs with tetra. To include BPF event metrics in metrics docs, let's define a "fake" collector - eventmetrics.bpfZeroCollector - reporting same metrics as eventmetrics.bpfCollector but with hardcoded zero values. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

policyStateCollector doesn't report any metrics if Tetragon isn't fully initialized - so also when we generate metrics docs with tetra. To include policy state metrics in metrics docs, let's define a "fake" collector - policyStateZeroCollector - reporting same metrics as policyStateZeroCollector but with hardcoded zero values. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

Use a Hugo shortcode so that the comment isn't rendered into the final HTML. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

lambdanis · 2024-03-01T16:49:01Z

Ok, after a few rebases this should be good now.

Here is the final docs preview: https://deploy-preview-2164--tetragon.netlify.app/docs/reference/metrics/
@mtardy Please take another look if you want.

mtardy

I think it looks good now and will be very useful, thanks a lot!

docs/content/en/docs/reference/metrics.md

mtardy · 2024-03-01T16:53:43Z

docs/content/en/docs/reference/metrics.md

+| `commit` | `931b70f2c9878ba985ba6b589827bea17da6ec33` |
+| `go_version` | `go1.22.0` |
+| `modified` | `false` |
+| `time ` | `2022-05-13T15:54:45Z` |


I like that it's referencing the OSS commit 😻

It looks a bit odd as it's not rendered as a link, especially in the TOC. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

lambdanis added area/documentation Improvements or additions to documentation release-note/docs This PR updates the documentation. labels Feb 28, 2024

lambdanis requested review from mtardy, a team and willfindlay as code owners February 28, 2024 16:57

lambdanis mentioned this pull request Feb 28, 2024

Add metricsmd package isovalent/metricstool#3

Merged

willfindlay approved these changes Feb 28, 2024

View reviewed changes

Makefile Show resolved Hide resolved

mtardy reviewed Feb 29, 2024

View reviewed changes

lambdanis force-pushed the pr/lambdanis/metricsmd branch 2 times, most recently from e9566d8 to f775376 Compare March 1, 2024 01:30

lambdanis force-pushed the pr/lambdanis/metrics-init-labels branch from cebc21f to b24e3f1 Compare March 1, 2024 12:47

lambdanis force-pushed the pr/lambdanis/metricsmd branch 2 times, most recently from 52ced09 to 0004b79 Compare March 1, 2024 16:14

lambdanis mentioned this pull request Mar 1, 2024

Initialize metrics with labels #2162

Merged

Base automatically changed from pr/lambdanis/metrics-init-labels to main March 1, 2024 16:32

lambdanis added 3 commits March 1, 2024 16:35

tetra: Add metrics-docs command

bcc9620

This command utilizes github.com/isovalent/metricstool/pkg/metricsmd to generate a metrics reference. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

Makefile: Add metrics-docs rule

71bbde8

`make metrics-docs` generates metrics reference documentation page using `tetra metrics-docs` command. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

lambdanis force-pushed the pr/lambdanis/metricsmd branch from 0004b79 to 96d6f7b Compare March 1, 2024 16:37

lambdanis added 3 commits March 1, 2024 16:45

tetra: Split metrics reference into sections

f4ce807

Update metrics-docs tetra command and Makefile rule to split metrics reference into three sections: health metrics, resources metrics and events metrics. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

eventmetrics: Initialize metrics with example labels for docs

8ab6167

Initialize tetragon_events_total with all possible event types and example process metadata. Initialize tetragon_policy_events_total with example policy and kprobe. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

kprobemetrics: Initialize metrics with example labels for docs

816c97b

Initialize tetragon_generic_kprobe_merge_errors_total with all possible error types and example kprobes. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

lambdanis added 9 commits March 1, 2024 16:45

syscallmetrics: Initialize metrics with example labels for docs

50e20dd

Initialize tetragon_syscalls_total with example syscall and process metadata. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

ci: Check generated metrics docs

4408052

Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

docs: Add autogenerated metrics reference page

a1f6c84

Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

Makefile: Document metrics-docs and lint-metrics-md targets

aaac4a6

Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

docs: Improve metrics reference title and frontmatter

a241c1c

Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

docs: Document how metrics reference is generated

4288a63

Use a Hugo shortcode so that the comment isn't rendered into the final HTML. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

lambdanis force-pushed the pr/lambdanis/metricsmd branch from 96d6f7b to 4288a63 Compare March 1, 2024 16:46

mtardy approved these changes Mar 1, 2024

View reviewed changes

docs: Don't mention github.com/isovalent/metricstool in metrics docs

b509234

It looks a bit odd as it's not rendered as a link, especially in the TOC. Signed-off-by: Anna Kapuscinska <anna@isovalent.com>

lambdanis merged commit 9111a3a into main Mar 1, 2024
39 checks passed

lambdanis deleted the pr/lambdanis/metricsmd branch March 1, 2024 18:53

lambdanis mentioned this pull request Mar 8, 2024

CFP: Improve Cilium Metrics Documentation cilium/cilium#21343

Closed

lambdanis mentioned this pull request Apr 25, 2024

Improve metrics library to enforce best practices #2376

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Generate metrics reference docs #2164

Generate metrics reference docs #2164

lambdanis commented Feb 28, 2024 •

edited

Loading

willfindlay left a comment

mtardy commented Feb 29, 2024

mtardy left a comment

mtardy Feb 29, 2024

lambdanis Feb 29, 2024

lambdanis Feb 29, 2024

mtardy Feb 29, 2024

netlify bot commented Mar 1, 2024 •

edited

Loading

lambdanis commented Mar 1, 2024

mtardy left a comment

mtardy Mar 1, 2024

Generate metrics reference docs #2164

Generate metrics reference docs #2164

Conversation

lambdanis commented Feb 28, 2024 • edited Loading

willfindlay left a comment

Choose a reason for hiding this comment

mtardy commented Feb 29, 2024

mtardy left a comment

Choose a reason for hiding this comment

mtardy Feb 29, 2024

Choose a reason for hiding this comment

lambdanis Feb 29, 2024

Choose a reason for hiding this comment

lambdanis Feb 29, 2024

Choose a reason for hiding this comment

mtardy Feb 29, 2024

Choose a reason for hiding this comment

netlify bot commented Mar 1, 2024 • edited Loading

✅ Deploy Preview for tetragon ready!

lambdanis commented Mar 1, 2024

mtardy left a comment

Choose a reason for hiding this comment

mtardy Mar 1, 2024

Choose a reason for hiding this comment

lambdanis commented Feb 28, 2024 •

edited

Loading

netlify bot commented Mar 1, 2024 •

edited

Loading