Merge pull request #361 from stateful/T-monitoring-stack

docs: add monitoring guide

Author: edeediong

docs/configuration/runme-gist.md

@@ -0,0 +1,67 @@
+# Runme Gist
+
+Would you love to share or store your plain texts or code snippets securely with others in your team without needing a full repository or document?
+Runme Gist makes this possible and prioritizes your information's sensitivity by keeping sensitive information secret. In this section, we will explain how Runme Gist works.
+
+## **What is Runme Gist?**
+
+Runme Gist combines GitHub Gist with Runme capabilities to run, share, and store plain texts or code snippets in your Markdown file. What makes Runme Gist powerful is its ability to capture outputs and mask sensitive data without copying and pasting or integrating a third-party tool. You have everything done inside your Markdown file. Amazing right?
+
+## **Installation**
+
+- To utilize the Runme Gist feature, ensure the [Runme extension](../installation/installrunme) is installed in your VS Code. If you already have Runme installed in your VS Code, ensure you are upgraded to v3.4.0.
+- Set Runme as your [default Markdown viewer](../installation/installrunme) to ensure all Markdown files in your code editor are automatically opened as a Runme notebook.
+
+## **Setting Up Runme Gist**
+
+As stated earlier, Runme Gist combines GitHub Gist with Runme capabilities to enable you to securely run, share, and store code snippets. In this section, we will explain how Runme Gist works using a step-by-step guide.
+
+1. Open your Markdown File
+   Create a `README.md` file and open it in your VS Code. If you already have the file you want to use, open it in VS Code.
+2. Run Cells
+   Run your notebook cells, and ensure the [auto-save feature](../configuration/auto-save) is turned on to save your outputs without manual intervention.
+
+![runme gist Autosave ](../../static/img/configuration-page/runme-gist-autosave.png)
+
+3. View Sessions Output
+   Session output is a Runme feature that stores your generated cell outputs to a separate file to enable you access the output whenever you need. See the [Session output](../configuration/auto-save#session-outputs) guide.
+
+To view your session output, click “Sessions Outputs” to inspect the locally recorded session. Alternatively, you can find it on the left-hand side of your VS Code right inside your current working directory.
+
+![Runme gist session output](../../static/img/configuration-page/runme-gist-sessionoutput.png)
+
+The Session Outputs feature is only available when the autosave is enabled and the Runme cell is run.
+
+4. Toggle Between Mask and Unmask
+   You can decide if you want your session outputs to be masked or unmasked.
+   The masked and unmasked options are how Runme keeps your sensitive information secret. If you want to keep your sensitive information secret, you should toggle the mask option otherwise, choose the unmasked option.
+   Otherwise, Runme uses the open-source `data-guardian` library to mask sensitive information on a best-effort basis.
+
+![Runme gist unmask](../../static/img/configuration-page/runme-gist-unmask.png)
+
+## **Creating and Managing Gist with Runme using Secret Gists**
+
+GitHub Gist is a service provided by GitHub that allows users to share code snippets, notes, and other small pieces of text with others. With a single click, you can push your Runme Session Output to GitHub Gist from your Markdown file.
+To do this, click on “Generate Gist”.
+
+![Runme gist](../../static/img/configuration-page/runme-gist.png)
+
+Runme will first prompt you to log into your GitHub account and grant write access to your Gist. After a successful login, a notification containing a link to the Runme Gist hosted on your GitHub will be displayed.
+
+The link is generated as a “Secret Gist,” which will stay private as long as you keep it private. Ensure you secure the link cautiously before pushing your sessions to GitHub Gist.
+Lastly, use the Runme mask feature to keep your sensitive pieces secured.
+
+## **Visual Representation of Runme Gist**
+
+Here is a video that showcases the power of Runme Gist.
+
+<video autoPlay loop muted playsInline controls>
+  <source src="/videos/Runme-gist.mp4" type="video/mp4" />
+  <source src="/videos/Runme-gist.webm" type="video/webm" />
+</video>
+
+Congratulations! You have successfully learned how to use the Runme Gist feature.
+
+Note that session output files can be kept offline and locally.
+You can read about that [here](https://runme.dev/blog/runme-v3-pipeline-logs-and-artifacts). If you love this feature, kindly give [Runme a star](https://github.com/stateful/runme/stargazers) on GitHub.
+

docs/guide/monitoring-stack.md

@@ -0,0 +1,211 @@
+# How to Set Up a Monitoring Stack For Your Application by Leveraging Runme
+
+A monitoring stack is a set of tools that collect, process, and visualize data from various sources to improve the performance and security of systems and applications.
+
+Most often, instructions which define setting up and configuration of monitoring stack procedures are set in multiple documents which can be overwhelming. This is where Runme comes in! Runme provides a platform that helps you document all the standardized processes needed to set up and configure your monitoring stack, centralizing your procedures and processes in an interactive runbook accessible to you and your team.
+
+With Runme, you create a set of predefined procedures and instructions for installing and configuring all dependencies needed for your monitoring stack, such as [Prometheus](https://prometheus.io/), [Grafana](https://grafana.com/) and others.
+
+In this guide, we will walk you through configuring a monitoring stack and creating a Runbook for your application setup and configuration using Runme.
+
+## Prerequisites
+
+To follow up on the steps in this guide, ensure you have the following:
+
+- Runme Extension: Install the [Runme extension](https://marketplace.visualstudio.com/items?itemName=stateful.runme) in your VS Code editor. You can make Runme your [default Markdown viewer](https://docs.runme.dev/installation/installrunme#how-to-set-vs-code-as-your-default-markdown-viewer), ensuring all your Markdown files are automatically opened as a Runme Notebook. Additionally, it provides other client interfaces where you can run your Markdown file. See the [Runme installation](https://docs-runme-jg6ocbnyb-stateful.vercel.app/installation/) guide.
+- Clone Repository: We have provided an example repo to help you follow this tutorial. Clone the [repository here](https://github.com/stateful/blog-examples/tree/main/kubernetes/monitoring-stack). If you are a Linux user, navigate to the [Linux file](https://github.com/stateful/blog-examples/blob/main/kubernetes/monitoring-stack/linux.md). For Mac users, see the [Mac file](https://github.com/stateful/blog-examples/blob/main/kubernetes/monitoring-stack/mac.md).
+   This guide focuses on the Linux README.md file; other operating systems also work.
+
+## Install a Node Exporter
+
+A [Node Exporter](https://github.com/prometheus/node_exporter) allows for detailed monitoring of system-level metrics like CPU usage, memory usage, disk, and network activity, providing valuable insights into the health and performance of the underlying infrastructure.
+
+To install a Node Exporter in Runme, navigate to the “[Install Node Exporter](https://github.com/stateful/blog-examples/blob/main/kubernetes/monitoring-stack/linux.md#install-node-exporter)” section in the cloned repository, enter the command in your Runme cell, and click on run.
+
+![install node exporter](../../static/img/guide-page/runme-install-exporter.png)
+
+Runme uses its [environment variable prompt feature](https://docs.runme.dev/getting-started/features#environment-variable-prompts) to prompt users to enter a value for the version and the platform. Runme will store these values, so you no longer need to enter them when working on this project.
+
+![env prompt for node exporter](../../static/img/guide-page/node-exporter-env-prompt.png)
+
+## Configure Your Node Exporter In Your Runbook
+
+To configure your Node Exporter, you must follow three steps.
+
+Step One: Set Up Node Exporter as a Service
+
+Create a `systemd` service file that ensures the Node Exporter is properly configured as a background service. This will allow it to continuously collect and export system metrics to Prometheus for monitoring and analysis. To do this, navigate to the “[Setup Node Exporter as a Service](https://github.com/stateful/blog-examples/blob/main/kubernetes/monitoring-stack/linux.md#setup-node-exporter-as-a-service)” section in your cloned repository and run the command in your Runme cell.
+
+```sh
+cat <<EOF > sudo tee /etc/systemd/system/node_exporter.service > /dev/null
+[Unit]
+Description=Prometheus Node Exporter
+After=network.target
+
+[Service]
+ExecStart=/usr/local/bin/node_exporter
+
+[Install]
+WantedBy=default.target
+
+EOF
+
+```
+
+**Output**:
+
+![Node exporter service](../../static/img/guide-page/create-node-exporter-service.png)
+
+Step Two: Run Node Exporter as a Service
+
+In this step, you are required to run your Node Exporter service, check its status, and restart it if necessary. To do this, navigate to the “[Run Node Exporter as a Service](https://github.com/stateful/blog-examples/blob/main/kubernetes/monitoring-stack/linux.md#run-node-exporter-as-a-service)” section and run the command in your Runme cell.
+
+```sh
+sudo cp -rf ${PWD}/node_exporter/node_exporter.service /etc/systemd/system/
+
+sudo systemctl daemon-reload
+
+sudo systemctl enable node_exporter
+echo "node exporter enable"
+
+sudo systemctl start node_exporter
+echo "node_exporter has started."
+
+
+sudo systemctl status node_exporter
+
+sudo systemctl restart node_exporter
+```
+
+**Output**:
+
+![node exporter service](../../static/img/guide-page/runme-node-exporter-service.png)
+
+## Install Prometheus
+
+In a monitoring stack, Prometheus gathers metrics, monitors system and application health, generates alerts based on a predefined rule, and provides insights into system and application performance and availability.
+
+To install Prometheus in Runme, navigate to the “[Install Prometheus](https://github.com/stateful/blog-examples/blob/main/kubernetes/monitoring-stack/linux.md#install-prometheus)” section in your cloned repository, enter and run the command in your Runme cell.
+
+![Install prometheus](../../static/img/guide-page/install-promtheus.png)
+
+Runme will leverage its environment prompt feature to prompt you to input the version of Prometheus you want to install. Once you input the version, you will have an output similar to the one above.
+
+## Configure your Prometheus
+
+To configure your Prometheus, you will be required to follow three steps:
+
+Step One: Setup your Prometheus configuration
+Create a Prometheus configuration file that specifies how Prometheus should collect metrics from the Node Exporter. To do this, navigate to the section on “[Setting up Prometheus Configuration](https://github.com/stateful/blog-examples/blob/main/kubernetes/monitoring-stack/linux.md#setup-your-prometheus-configuration)”, enter the command, and run it in your Runme cell.
+
+```sh
+cat <<EOF > ${PWD}/prometheus/prometheus.yml
+global:
+  scrape_interval: 15s
+  evaluation_interval: 15s
+scrape_configs:
+  - job_name: 'node_'
+    metrics_path: /metrics
+    static_configs:
+      - targets:
+        - 10.90.2.1:9116
+EOF
+```
+
+**Output**:
+
+![promtheus yaml file](../../static/img/guide-page/runme-promtheus-yaml-file.png)
+
+Step Two: Set up Prometheus as a service
+Create a `systemd` service file for the Prometheus Agent Mode, which will facilitate federation and data collection from multiple Prometheus instances or remote targets. To do this, navigate to the “[Setting up prometheus as a Service](https://github.com/stateful/blog-examples/blob/main/kubernetes/monitoring-stack/linux.md#setup-prometheus-as-a-service)” section, enter the command, and run it in your Runme cell.
+
+```sh
+cat <<EOF > ${PWD}/prometheus/prometheus.service
+[Unit]
+Description=Prometheus Agent Mode
+After=network-online.target
+[Service]
+User=${USER}
+WorkingDirectory=${PWD}
+ExecStart=${PWD}/prometheus/prometheus --config.file=${PWD}/prometheus/prometheus.yml --enable-feature=agent
+[Install]
+WantedBy=multi-user.target
+EOF
+```
+
+**Output**:
+
+![prometheus service](../../static/img/guide-page/create-promtheus-service.png)
+
+Step Three: Run Prometheus as a Service
+Now, run Prometheus as a service. To do this, navigate to the “[Run Prometheus as a Service](https://github.com/stateful/blog-examples/blob/main/kubernetes/monitoring-stack/linux.md#run-prometheus-as-a-service)” section, enter the command, and run it in your Runme cell.
+
+![prometheus](../../static/img/guide-page/prometheus-service-runme.png)
+
+Step four: Open the app
+
+Run the code below in your Runme cell, it will open the prometheus User Interface page.
+
+```sh
+open http://localhost:9090
+```
+
+## Install Grafana
+
+Grafana provides a user-friendly interface for visualizing and analyzing metrics, logs, and other monitoring data in your monitoring stack. To install Grafana for your monitoring stack, navigate to the “[Install Grafana](https://github.com/stateful/blog-examples/blob/main/kubernetes/monitoring-stack/linux.md#install-grafana)” section and run the command in your Runme cell.
+
+![Install Grafaba](../../static/img/guide-page/install-grafana-runme.png)
+
+Open the App:
+
+You installed Grafana on your local machine using Runme in the previous step. Now, you need to open the Grafana user interface on your local machine. To do this, enter the command below in your Runme cell and run the command.
+
+```sh
+open http://localhost:3000
+```
+
+## Install Alertmanager
+
+An Alertmanager is a component of a monitoring stack that handles alerts sent by monitoring tools like Prometheus. It is responsible for grouping, deduplication, and routing alerts to the appropriate recipients. To install an Alertmanager and make it a part of your monitoring stack, navigate to the “[Install Alertmanager](https://github.com/stateful/blog-examples/blob/main/kubernetes/monitoring-stack/linux.md#install-alert-manager)” section in the cloned repository, enter the command in your Runme cell, and run it.
+
+![Install Alertmanager](../../static/img/guide-page/alertmanager-runme.png)
+
+You can edit your `alertmanager.yml` file to define the alerting configurations, notification integrations, and routing rules. To do that, run this command in your Runme cell `nano /etc/alertmanager/alertmanager.yml`
+
+## Configure and Run Your Alertmanager
+
+You will follow three steps to configure and run your Alertmanager.
+
+Step One: Set Up Alertmanager as a Service
+Create a `systemd` service file for Alertmanager, specify its description, user-startup command, and target for activation. To do this, navigate to the “[Setup Alertmanager as a Service](https://github.com/stateful/blog-examples/blob/main/kubernetes/monitoring-stack/linux.md#setup-alert-manager-as-a-service)” section, enter the command, and run it in your Runme cell.
+
+![alertmanager](../../static/img/guide-page/Alertmanager.service.png)
+
+Step Two: Run Alertmanager as a Service
+Now, you can run your Alertmanager as a service. To do this, navigate to the “[Run Alert as a Service](https://github.com/stateful/blog-examples/blob/main/kubernetes/monitoring-stack/linux.md#run-alert-manager-as-a-service)” section, enter the command in your Runme cell, and run it.
+
+![alertmanager-service](../../static/img/guide-page/runme-alertmanager.png)
+
+Step Three: Open the app
+
+To open the Alertmanager page on your local machine, run the command below in your Runme cell.
+
+```sh
+open http://localhost:9093
+```
+
+## Why use Runme
+
+Rather than having your codes, commands, or processes in separate files or performing a task repeatedly, Runme enables you to have everything inside your Markdown file, which can be automated whenever you need to run this process.
+Some key features of Runme that make it a choice platform for your monitoring stack include:
+
+- Environment Variable Prompts
+   As you can see from the procedure above, the [environment variable prompt](https://docs.runme.dev/getting-started/features#environment-variable-prompts) is one feature that makes it a choice platform for this task. This feature comes in handy when your runbooks need user-specific values. It allows you to input values directly within your notebook environment, thus making your task execution more efficient.
+- Run Sections
+   Runme makes [running the script by section](https://docs.runme.dev/configuration/cellsection) possible. For example, in your monitoring-stack notebook, you can choose to run each section (“Node Exporter,” “Prometheus,” “Grafana”) rather than individual cells. This feature makes running this task easier and faster.
+- Auto-Save
+   Runme makes saving your outputs easier without manual intervention by triggering the [auto-save feature](https://docs.runme.dev/configuration/auto-save). This way, you can focus on your task and run your commands without worrying about losing your outputs.
+- Share Runbook With Members of Your Team
+   Runme makes sharing of outputs from an executed cell with team members easy. You only need to leverage Runme’s autosave feature to save your output, and you have unlocked the access to share that output with your team members.
+
+These are just a few features of Runme. We continually work to improve your experience with Runme by providing you with more features and updates to enhance your documentation and automation processes. To explore other features of Runme, see the [Runme guide](https://docs.runme.dev/) for comprehensive details.