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.

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

Docs information architecture refactor pass 1 #1259

Merged
merged 13 commits into from
Oct 18, 2024

Conversation

grafsean
Copy link
Contributor

Hi all, I've put together a first pass at refactoring and improving the information architecture of our documentation with a focus on the getting started experience. Please let me know if you'd like to discuss anything.

Changes

  • Move standalone set up to the repo only, most of our users will use Kubernetes in production
  • Move k8s walkthrough to quickstart
  • Move Helm Alloy tutorial to set up, as it covers a different set up method
  • Remove the getting started tutorial in favour of quickstarts and other set up documentation
  • Move the RED metrics dashboard section from the getting started tutorial to it's own article
  • Rename various menu titles
  • Improve navigation structure and content order
  • Remove stability guarantees page

For the stability guarantees page, is that something we typically add to products or documentation? If we want to keep it, is it up to date?

Navigation before

Screenshot 2024-10-15 at 12 01 11

Navigation after

Screenshot 2024-10-15 at 12 03 11

Next steps

None of the content has been edited in this PR other than updating for link changes. I'd like to do a editing pass over everything to address Vale errors and edit for consistency.

I'd also like to update the language quickstarts to use Docker and code tabs. By using code tabs we can condense many articles into one and present a single language quickstart article.

When this refactor series is complete I'd like to get onto further content enhancement and additions.

Background

Last quarter in Slack, I discussed a few areas of the documentation (setup, tutorials, and quickstarts) that covered similar ground. Last week I checked with Mario about content similarities and areas we could make improvements.

@codecov-commenter
Copy link

codecov-commenter commented Oct 15, 2024

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 80.69%. Comparing base (f5000b2) to head (fcb7a7c).
Report is 1 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #1259      +/-   ##
==========================================
- Coverage   80.77%   80.69%   -0.08%     
==========================================
  Files         131      131              
  Lines       13465    13465              
==========================================
- Hits        10876    10866      -10     
- Misses       2079     2086       +7     
- Partials      510      513       +3     
Flag Coverage Δ
integration-test 60.95% <ø> (-0.26%) ⬇️
k8s-integration-test 57.29% <ø> (-0.02%) ⬇️
oats-test 36.37% <ø> (-0.03%) ⬇️
unittests 53.31% <ø> (-0.02%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@grafsean grafsean changed the title Documentation information architecture refactor pass 1 Docs information architecture refactor pass 1 Oct 15, 2024
@grafsean grafsean added documentation Improvements or additions to documentation enhancement labels Oct 15, 2024
@grafsean grafsean self-assigned this Oct 15, 2024
Copy link
Contributor

@mariomac mariomac left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mostly LGTM! Thanks for the improvement!

I have some minor comments about the main page.

Copy link
Contributor

@grcevski grcevski left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking great @grafsean, I left a few comments on the wording in a few places.

@@ -266,14 +267,14 @@ Because of the AppArmour restriction, to run Beyla as unprivileged container, yo
- Set `container.apparmor.security.beta.kubernetes.io/beyla: "unconfined"` in your Kubernetes deployment files.
- Set a modified AppArmour policy which allows Beyla to perform `mount`.

**Note** Since the `beyla` container does not have the privileges required to mount or un-mount the BPF filesystem, this sample leaves the BPF filesystem mounted on the host, even after the sample is deleted. This samples uses a unique path for each namespace to ensure re-use the same mount if Beyla is re-deployed, but to avoid collisions if multiple instances of Beyla is run in different namespaces.
**Note** Since the `beyla` container does not have the privileges required to mount or un-mount the BPF filesystem, this sample leaves the BPF filesystem mounted on the host, even after the sample is deleted. This samples uses a unique path for each namespace to ensure re-use the same mount if Beyla is re-deployed, but to avoid collisions if multiple instances of Beyla is run in different namespaces.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a note for future reference, this will no longer be the case in upcoming (major? cc @grcevski ) releases. It's no longer the case in the 'main' branch, so I believe we can delete this paragraph altogeteher - @grcevski thoughts?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's leave it for now, we can follow up with a PR to remove all references to the BPF file system in docs, examples etc.


**Note** Loading BPF programs requires that Beyla is able to read the Linux performance events, or at least be able to execute the Linux Kernel API `perf_event_open()`.
**Note** Loading BPF programs requires that Beyla is able to read the Linux performance events, or at least be able to execute the Linux Kernel API `perf_event_open()`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In addition to this, it may be worth at least mentioning https://docs.kernel.org/admin-guide/sysctl/kernel.html#unprivileged-bpf-disabled

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you @rafaelroquetto I'll do another pass to update further content. This pass focused on improving the information architecture and deprecated articles. See Next steps in the description.

## Requirements

- Linux with Kernel 5.8 or higher with BPF Type Format [(BTF)](https://www.kernel.org/doc/html/latest/bpf/btf.html)
enabled. BTF became enabled by default on most Linux distributions with kernel 5.14 or higher.
You can check if your kernel has BTF enabled by verifying if `/sys/kernel/btf/vmlinux` exists on your system.
If you need to recompile your kernel to enable BTF, the configuration option `CONFIG_DEBUG_INFO_BTF=y` must be
set.
- Alternatively, RHEL 4.18 Linux kernels (at least build 348) are also supported, due to their heavily backported nature.
- Beyla also supports RedHat-based distributions: RHEL8, Centos 8, Rocky8, AlmaLinux8, and others, which ship a Kernel 4.18 that backports eBPF-related patches.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Grafana.Spelling] Did you really mean 'Centos'? The Grafana dictionary might not know of this word yet. To add a new word, refer to Add words to the Grafana Labs dictionary. Alternatively, raise an issue and a maintainer will add it for you. For UI elements, use bold formatting. The spell checker doesn't check words with bold formatting. For paths; configuration; user input; code; class, method, and variable names; statuscodes; and console output, use code formatting. The spell checker doesn't check words with code formatting.

If the rule is incorrect or needs improving, report an issue.

If you have reason to diverge from the style guidance, to skip a rule, refer to Skip rules.

## Requirements

- Linux with Kernel 5.8 or higher with BPF Type Format [(BTF)](https://www.kernel.org/doc/html/latest/bpf/btf.html)
enabled. BTF became enabled by default on most Linux distributions with kernel 5.14 or higher.
You can check if your kernel has BTF enabled by verifying if `/sys/kernel/btf/vmlinux` exists on your system.
If you need to recompile your kernel to enable BTF, the configuration option `CONFIG_DEBUG_INFO_BTF=y` must be
set.
- Alternatively, RHEL 4.18 Linux kernels (at least build 348) are also supported, due to their heavily backported nature.
- Beyla also supports RedHat-based distributions: RHEL8, Centos 8, Rocky8, AlmaLinux8, and others, which ship a Kernel 4.18 that backports eBPF-related patches.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[Grafana.WordList] Use 'CentOS' instead of 'Centos'.

For more information, refer to https://grafana.com/docs/writers-toolkit/write/style-guide/word-list/.

If the rule is incorrect or needs improving, report an issue.

If you have reason to diverge from the style guidance, to skip a rule, refer to Skip rules.


Because of the AppArmour restriction, to run Beyla as unprivileged container, you need to either:

- Set `container.apparmor.security.beta.kubernetes.io/beyla: "unconfined"` in your Kubernetes deployment files.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[Grafana.Kubernetes] Use 'Kubernetes Deployment' instead of 'Kubernetes deployment'.

For more information, refer to https://grafana.com/docs/writers-toolkit/write/style-guide/capitalization-punctuation/#kubernetes-objects.

If the rule is incorrect or needs improving, report an issue.

If you have reason to diverge from the style guidance, to skip a rule, refer to Skip rules.

@grafsean grafsean merged commit 66e17c6 into main Oct 18, 2024
11 of 12 checks passed
@grafsean grafsean deleted the grafsean/getting-started-tutorial-refactor-1 branch October 18, 2024 09:38
@grafsean
Copy link
Contributor Author

Thank you all for your feedback ❤️ I'll keep the enhancement PRs coming 🙂

mattdurham pushed a commit to mattdurham/beyla that referenced this pull request Jan 22, 2025
* Move content and remove tutorial
* Move helm alloy
* Remove tutorial section
* Add k8s walkthrough to quickstart
* Add notes about standalone
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

5 participants