Updates docs

butschster · butschster · commit ed4163ff160e · 2024-05-24T17:48:05.000+04:00
1. Adds information about metrics
2. Adds information about webhooks
3. How to setup dev environment
4. How to contribute into docs
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -1,4 +1,4 @@
-import {defineConfig} from 'vitepress'
+import { defineConfig } from 'vitepress'
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
@@ -8,7 +8,7 @@ export default defineConfig({
     themeConfig: {
         // https://vitepress.dev/reference/default-theme-config
         nav: [
-            {text: 'Docs', link: '/'},
+            { text: 'Docs', link: '/' },
         ],
 
         sidebar: [
@@ -38,22 +38,31 @@ export default defineConfig({
             {
                 text: 'Integrations',
                 items: [
-                    {text: 'XHProf', link: '/config/xhprof'},
-                    {text: 'VarDumper', link: '/config/var-dumper'},
-                    {text: 'Ray', link: '/config/ray'},
-                    {text: 'Sentry', link: '/config/sentry'},
-                    {text: 'SMTP server', link: '/config/smtp'},
-                    {text: 'Monolog', link: '/config/monolog'},
-                    {text: 'Inspector', link: '/config/inspector'},
-                    {text: 'Http Dumps', link: '/config/http-dumps'},
+                    { text: 'XHProf', link: '/config/xhprof' },
+                    { text: 'VarDumper', link: '/config/var-dumper' },
+                    { text: 'Ray', link: '/config/ray' },
+                    { text: 'Sentry', link: '/config/sentry' },
+                    { text: 'SMTP server', link: '/config/smtp' },
+                    { text: 'Monolog', link: '/config/monolog' },
+                    { text: 'Inspector', link: '/config/inspector' },
+                    { text: 'Http Dumps', link: '/config/http-dumps' },
                 ]
             },
 
             {
                 text: 'Configuration',
                 items: [
-                    {text: 'Single Sign On (SSO)', link: '/config/sso'},
-                    {text: 'External Database', link: '/config/external-db'},
+                    { text: 'Webhooks', link: '/config/webhooks' },
+                    { text: 'Single Sign On (SSO)', link: '/config/sso' },
+                    { text: 'External Database', link: '/config/external-db' },
+                    { text: 'Metrics', link: '/config/metrics' },
+                ]
+            },
+
+            {
+                text: 'Cookbook',
+                items: [
+                    { text: 'Dev environment', link: '/cookbook/dev-env' }
                 ]
             },
 
@@ -64,10 +73,6 @@ export default defineConfig({
                         text: 'Getting Started',
                         link: '/contributing',
                     },
-                    {
-                        text: 'Architecture',
-                        link: '/contributing/architecture',
-                    },
                     {
                         text: 'Server',
                         link: '/contributing/server',
@@ -76,14 +81,18 @@ export default defineConfig({
                         text: 'Frontend',
                         link: '/contributing/frontend',
                     },
+                    {
+                        text: 'Documentation',
+                        link: '/contributing/docs',
+                    },
                 ]
             },
         ],
 
         socialLinks: [
-            {icon: 'github', link: 'https://github.com/buggregator/server'},
-            {icon: 'discord', link: 'https://discord.gg/vDsCD3EKUB'},
-            {icon: 'twitter', link: 'https://twitter.com/buggregator'},
+            { icon: 'github', link: 'https://github.com/buggregator/server' },
+            { icon: 'discord', link: 'https://discord.gg/vDsCD3EKUB' },
+            { icon: 'twitter', link: 'https://twitter.com/buggregator' },
         ]
     }
 })
diff --git a/docs/config/metrics.md b/docs/config/metrics.md
@@ -0,0 +1,52 @@
+# Configuration — Metrics
+
+Buggregator has a new feature that collects metrics on how many events we receive. This feature lets you use tools like
+Prometheus and Grafana to check on event trends, find issues, and set up alerts.
+
+This new feature will keep track of how many events Buggregator gets. It will sort these events by their types like
+sentry, monolog, var-dumper, ray, inspector, http-dump, profiler, and smtp.
+
+### How It Works
+
+1. **Event Counting:** Each time an event is received, it’s counted and sorted into its type.
+2. **Metric Updating:** The system updates the metrics to show the latest counts for each event type.
+
+## Prometheus Endpoint
+
+Buggregator has a built-in Prometheus friendly endpoint that you can use to collect metrics. Metrics are available at
+`2112` port inside the container. To access the metrics outside the container, you need to expose the port.
+
+```bash
+docker run --pull always \
+  ... \
+  -p 2112:2112 \
+  ghcr.io/buggregator/server:latest
+```
+
+> **Note:** Read more about server configuration [here](../getting-started.md).
+
+After starting the server, you can access the metrics at `http://<server_address>:2112` address.
+
+## Metric Format
+
+Here is what the metric format looks like:
+
+```plaintext
+# HELP events The total number of received events.
+# TYPE events counter
+events{type="sentry"} 10
+events{type="smtp"} 1
+```
+
+Each line shows how many events of a specific type we have received.
+
+## Grafana Integration
+
+You can use these metrics to make dashboards in Grafana. This helps you see the data in a way that makes sense for you.
+We will provide steps on how to connect Buggregator’s metrics to Grafana.
+
+### Setting Up Grafana
+
+1. **Add Prometheus as a Data Source:** First, connect Prometheus (which has your Buggregator metrics) to Grafana.
+2. **Create Dashboards:** Next, create dashboards in Grafana to show the metrics. You can make graphs and charts that
+   help you understand the event trends.
diff --git a/docs/config/webhooks.md b/docs/config/webhooks.md
@@ -0,0 +1,83 @@
+# Configuration — Webhooks
+
+Webhooks are a useful way to help Buggregator communicate in real-time with other applications when certain events
+happen. This guide simplifies setting up and managing webhooks for enhancing automation and integration with other
+tools.
+
+This guide will help you understand how to set up and use webhooks.
+
+### What is a Webhook?
+
+A webhook allows applications to share information as soon as specific events occur. Unlike regular APIs that require
+checking for updates periodically, webhooks provide this information automatically, saving time and resources.
+
+### Why Use Webhooks in Buggregator?
+
+- **Automate Tasks:** Automatically trigger actions in other services like [n8n](https://n8n.io/) when events happen in
+  Buggregator.
+- **Integrate with Other Tools:** Connect Buggregator with various tools like messaging apps, issue tracking software,
+  or custom apps effortlessly.
+
+## Docker Configuration
+
+Currently, Buggregator does not have an admin interface for managing webhooks. Instead, you manage them through
+configuration files within a Docker container.
+
+**Here's how you can mount a volume containing webhook configurations:**
+
+```bash
+docker run --pull always \
+  -v /path/to/webhooks:/app/runtime/webhooks \
+  ghcr.io/buggregator/server:latest
+```
+
+or using `docker-compose`:
+
+```yaml
+buggregator-server:
+  ...
+  volumes:
+    - /path/to/webhooks:/app/runtime/webhooks
+```
+
+## Configuring a Webhook
+
+Place each webhook configuration in a YAML file within the `runtime/webhooks` directory. Each configuration file should
+contain one webhook setup.
+
+Here’s what a typical webhook configuration looks like:
+
+```yaml
+webhook:
+  event: sentry.received
+  url: http://example.com/webhook
+  headers:
+    Content-Type: application/json
+    Secret-Key: my-secret-key
+  verify_ssl: false
+  retry_on_failure: true
+```
+
+**Key Components of a Webhook Configuration:**
+
+- **Event:** The specific event in Buggregator that will trigger the webhook.
+- **URL:** Where the webhook sends data.
+- **Headers:** Any additional headers needed for the webhook request.
+- **Verify SSL:** Choose whether to check SSL certificates during the webhook call.
+- **Retry on Failure:** If the webhook should retry sending data if the first attempt fails. (3 retries with exponential
+  backoff)
+
+> **Note:** You can test webhooks using tools like https://webhook.site.
+
+### Types of Events Supported:
+
+Buggregator can currently handle the following events:
+
+- sentry.received
+- monolog.received
+- var-dumper.received
+- ray.received
+- inspector.received
+- http-dump.received
+- profiler.received
+- smtp.received
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -12,7 +12,7 @@ label. This makes it easier for you to find ways to participate.
 Additionally, we use labels such as `c:easy`, `c:medium`, and `c:difficult` to indicate the complexity level of issues,
 helping you choose tasks that match your skill level.
 
-## The Benefits of Contributing to Open Source for Developers
+## Benefits
 
 Contributing to open source projects offers a wealth of benefits, particularly for junior developers.
 
@@ -31,13 +31,20 @@ Contributing to open source projects offers a wealth of benefits, particularly f
 5. **Making a Real-World Impact:** Your contributions can significantly influence the project and its users. The
    satisfaction of seeing your code being used and appreciated by others is incredibly rewarding.
 
-**Remember, every expert was once a beginner. Contributing to open source is a valuable step in your development
-journey. So, dive in and start making your mark!**
+**Help us enhance Buggregator and make a real difference!**
 
 **We appreciate any contributions to help make Buggregator better!**
 
-Buggregator consist of two repositories
+## Repositories
 
-1. Server part. This is the places where an application will send events which will be handled by server and sent to the client browser. Server also is REST API endpoint where a client requests received events
+There are the following repositories in the Buggregator project:
 
-2. Frontend part. This is the place where a client can observe incomming events such as var dumps and 
+1. [Server](https://github.com/buggregator/server). Manages and sends events to the client. It also serves as a REST API
+   endpoint for event requests.
+2. [Frontend](https://github.com/buggregator/frontend). Allows clients to view incoming events like variable dumps.
+3. [Trap](https://github.com/buggregator/trap). A lightweight alternative to the full Buggregator server, designed for
+   local debugging.
+4. [Documentation](https://github.com/buggregator/docs). Contains all the documentation for the Buggregator project.
+5. [Site](https://github.com/buggregator/buggregator.dev). The official website for Buggregator.
+6. [PHPStorm Plugin](https://github.com/buggregator/phpstorm-plugin). A plugin for PHPStorm that integrates with
+   Buggregator.
diff --git a/docs/contributing/architecture.md b/docs/contributing/architecture.md
diff --git a/docs/contributing/docs.md b/docs/contributing/docs.md
@@ -0,0 +1,48 @@
+# Contributing — Documentation
+
+Buggregator uses [VitePress](https://vitepress.dev/) for its documentation. This makes it easy to contribute to the
+project's documentation by following the steps below.
+
+## Getting Started
+
+### Clone the Repository
+
+First of all you need to clone the repository to your local machine.
+
+```bash
+git clone git@github.com:buggregator/docs.git
+```
+
+> **Note**: If you don't have access to the repository, you can fork it and clone your forked repository.
+
+### Install Dependencies
+
+After cloning the repository, navigate to the project directory and install the dependencies.
+
+```bash
+npm install
+```
+
+### Start the Development Server
+
+To start the development server and preview the documentation, run the following command:
+
+```bash
+npm run docs:dev
+```
+
+This command will start a local development server and open the documentation in your default browser.
+
+## Structure
+
+The documentation is structured as follows:
+
+- `docs/`: Contains the documentation files.
+- `docs/.vitepress/config.mts`: Site configuration and navigation.
+
+All you need is to edit the markdown files in the `docs/` directory. If you want to add a new page, create a new
+markdown file in the `docs/` directory and add it to the navigation in the `docs/.vitepress/config.mts` file.
+
+---
+
+That's it! You're now ready to contribute to the Buggregator documentation.
diff --git a/docs/contributing/server.md b/docs/contributing/server.md
@@ -10,21 +10,18 @@ crucial for handling the information that flows through Buggregator.
 
 ## Key Technologies:
 
-It's built on a foundation of robust and reliable technologies, including the Spiral Framework, RoadRunner, and
-Centrifugo.
+It's built on a foundation of robust and reliable technologies, including the Spiral Framework, RoadRunner, Centrifugo
+and Doltdb.
 
 - [Spiral Framework](https://spiral.dev/) - A PHP framework that's the foundation of our server.
 - [RoadRunner](https://roadrunner.dev/) - Manages different server tasks like HTTP, TCP, queues, and caching.
 - [Centrifugo](https://centrifugal.dev/) - Handles real-time messaging through WebSockets.
+- [Doltdb](https://github.com/dolthub/dolt) - A SQL database that's built on top of a Git repository.
 
 ## Server requirements
 
 1. Minimum PHP version: 8.2
 
 ## Installation
 
-1. Clone repository `git clone https://github.com/buggregator/server.git`
-2. Install backend dependencies `composer install`
-3. Download RoadRunner binary `vendor/bin/rr get-binary`
-4. Install Centrifugo server `cd bin && ./get-binaries.sh`
-5. Run RoadRunner server `./rr serve`
+To set up environment for local development read the [development environment setup guide](../cookbook/dev-env.md).
diff --git a/docs/cookbook/dev-env.md b/docs/cookbook/dev-env.md
