Updates docs

buggregator · May 24, 2024 · ce5bb0a · ce5bb0a
1 parent 99925aa
commit ce5bb0a
Show file tree

Hide file tree

Showing 4 changed files with 208 additions and 31 deletions.
diff --git a/docs/config/inspector.md b/docs/config/inspector.md
@@ -1,6 +1,6 @@
 # Integration — Inspector
 
-Buggregator is also compatible with Inspector reports, providing you with a lightweight alternative for local
+Buggregator is compatible with Inspector reports, providing you with a lightweight alternative for local
 development. With it, you can easily configure your Inspector client URL to send data directly to the server, making it
 easier to identify and fix issues during the development phase.
 
@@ -38,3 +38,51 @@ most popular languages.
 
 > **Note:**
 > You can find out documentation on [official site](https://docs.inspector.dev/)
+
+## Secret key validation
+
+Buggregator lets you send reports freely by default, but you can boost your security by setting up a secret key.
+
+In our example, we will use `my-secret-key` as the secret key. Let's see how to set it up.
+
+### Server configuration
+
+To use a secret key, set the `INSPECTOR_SECRET_KEY` environment variable on your server.
+
+**Here’s how to do it:**
+
+```bash
+docker run --pull always \
+ -p ... \
+ -e INSPECTOR_SECRET_KEY=my-secret-key \
+ ghcr.io/buggregator/server:latest
+```
+
+> **Note:** Read more about server configuration [here](../getting-started.md).
+
+When you set the secret key, the server checks the `X-Inspector-Key` header to make sure it matches the secret key.
+
+### Client configuration
+
+To set the secret key on a client, change your DSN like this:
+
+**Laravel**
+
+```dotenv
+INSPECTOR_INGESTION_KEY=my-secret-key
+```
+
+**Other platforms**
+
+```php
+use Inspector\Inspector;
+use Inspector\Configuration;
+
+$configuration = new Configuration('my-secret-key');
+$configuration->setUrl('http:https://[email protected]:8000');
+$inspector = new Inspector($configuration);
+
+// ...
+```
+
+> **Note:** Read more about ingestion key configuration on [official site](https://docs.inspector.dev/)
diff --git a/docs/config/ray.md b/docs/config/ray.md
@@ -1,15 +1,15 @@
 # Integration — Spatie Ray
 
-Buggregator is compatible with `spatie/ray` package. The Ray debug tool supports PHP, Ruby, JavaScript, TypeScript,
-NodeJS, Go and Bash applications. After installing one of the libraries, you can use the ray function to quickly dump
-stuff. Any variable(s) that you pass will be sent to the Buggregator.
+[Ray](https://myray.app/) is a debug tool that was created by Spatie. It is a great alternative to the Symfony
+VarDumper component especially for Laravel applications. Buggregator is compatible with the Ray, and it's a good free
+alternative for debugging your applications.
+
+> **Note:** Some of the features of Ray are not available in Buggregator, like colors, sizes, and other visual features.
 
 ![ray](https://github.com/buggregator/server/assets/773481/168b27f7-75b1-4837-b0a1-37146d5b8b52)
 
-**Supported features**: Simple data, Labels, Caller, Trace, Counter, Class name of an object, Measure, Json, Xml,
-Carbon, File, Table, Image, Html, Text, Notifications, Phpinfo, Exception, Show queries, Count queries, Show events,
-Show jobs, Show cache, Model, Show views, Markdown, Collections, Env, Response, Request, Application log, Show Http
-client requests
+Ray provides packages for PHP, Ruby, JavaScript, TypeScript, NodeJS, Go, and Bash applications. So using it you can
+dump variables in many languages straight to the Buggregator.
 
 ## Laravel
 
@@ -28,9 +28,9 @@ [email protected] # Ray server host (Current HTTP buggregator port)
 RAY_PORT=8000 # Ray server port
 ```
 
-## Framework agnostic PHP
+## Framework-agnostic PHP
 
-In framework agnostic projects you can use this template as the ray config file.
+In framework-agnostic projects you can use this template as the ray config file.
 
 ```php
 <?php
@@ -69,5 +69,13 @@ return [
 ];
 ```
 
-You can find out more information about installation and configuration
-on [official site](https://spatie.be/docs/ray/v1/introduction)
+## Other languages
+
+- [JavaScript](https://myray.app/docs/javascript/vanilla-javascript/getting-started)
+- [Bash](hhttps://myray.app/docs/other-languages/bash/installation)
+- [Go](https://myray.app/docs/other-languages/go/getting-started)
+- [Ruby](https://myray.app/docs/other-languages/ruby/getting-started)
+
+---
+
+That's it! Now you can use the `ray()` function as usual. The output will be sent to the remote server.
diff --git a/docs/config/sentry.md b/docs/config/sentry.md
@@ -1,15 +1,16 @@
 # Integration — Sentry exceptions
 
-Buggregator offers seamless integration with Sentry reports, making it a reliable tool for local development. With
-it, you can easily configure your Sentry DSN to send data directly to the server, providing you with a lightweight
-alternative for debugging your application.
+Buggregator integrates seamlessly with Sentry reports, making it ideal for local development. You can easily configure
+your app to send data to the Buggregator server, offering a lightweight alternative for debugging without any limits
+or registration. Send exceptions as many times as you need, without any restrictions.
 
 ![sentry](https://github.com/buggregator/server/assets/773481/e979fda5-54c8-42cc-8224-a1c5d828569a)
 
-By using Buggregator to receive Sentry reports, you can identify and fix issues with your application before deploying
-it to production. This ensures that your application is robust and efficient, providing a smooth experience for your
-users. So, if you're looking for an easy and efficient way to receive Sentry reports during local development,
-Buggregator is the perfect tool for you.
+Using Buggregator with Sentry helps you identify and fix issues before production, ensuring a smooth user experience.
+For easy and efficient Sentry report handling during development, choose Buggregator.
+
+> **Note:** For local debugging, Buggregator is an excellent tool, but Sentry is the recommended solution for full-scale
+> production needs.
 
 ## What is Sentry?
 
@@ -50,7 +51,8 @@ SENTRY_DSN=http:https://[email protected]:8000/1
 
 ### Installation
 
-Magento 2 is supported via the following package, you can read more about it [here](https://github.com/justbetter/magento2-sentry)
+Magento 2 is supported via the following package, you can read more about
+it [here](https://github.com/justbetter/magento2-sentry)
 
 ### Configuration
 
@@ -70,8 +72,72 @@ or
  ...
 ]
 ```
+
 in the `app/etc/env.php`
 
+## WordPress
+
+### Installation and configuration
+
+> Make sure `WP_ENVIRONMENT_TYPE`is set to `local`. [Local](https://localwp.com/) (by WPEngine) does that by default.
+
+1. Install [WP Sentry](https://wordpress.org/plugins/wp-sentry-integration/). You don't have to activate it. We
+ will [load it early](https://github.com/stayallive/wp-sentry/tree/v7.13.0?tab=readme-ov-file#loading-sentry-before-wordpress),
+ to catch errors early.
+
+2. In `wp-config.php` add:
+
+```php
+// NOTE: WP_ENVIRONMENT_TYPE must be defined and set to 'local'.
+if (defined('WP_ENVIRONMENT_TYPE') && 'local' === WP_ENVIRONMENT_TYPE) {
+ define( 'WP_SENTRY_PHP_DSN', 'http:https://[email protected]:8000/1' );
+ define( 'WP_SENTRY_ERROR_TYPES', E_ALL & ~E_NOTICE & ~E_USER_NOTICE );
+ require_once __DIR__ . '/wp-content/plugins/wp-sentry-integration/wp-sentry.php';
+}
+```
+
+## JavaScript
+
+Buggregator provides an HTTP endpoint `/sentry/<project>.js` to include in your project. It's a fast and easy way to
+start using Buggregator with your JavaScript application.
+
+Read more about the [Sentry JavaScript SDK](https://docs.sentry.io/platforms/javascript/#install)
+
+In order to get started using the Sentry JavaScript SDK, add the following code to the top of your application, before
+all other scripts:
+
+```html
+
+<script src="http:https://127.0.0.1:8000/sentry/1.js"></script>
+```
+
+This script will load the Sentry SDK and configure it to send errors to the Buggregator.
+
+### Configuration
+
+Before you can use it, you need to configure server ENV variables. By default, Buggregator uses the following ENV
+variables:
+
+```dotenv
+# Sentry SDK URL (Actual version can be found here https://docs.sentry.io/platforms/javascript/install/loader/#cdn)
+SENTRY_JS_SDK_URL=https://browser.sentry-cdn.com/7.69.0/bundle.tracing.replay.min.js 
+
+# Sentry DSN host that will be used in the SDK
+SENTRY_JS_DSN_HOST=http:https://[email protected]:8000 
+```
+
+You can override them by setting the following ENV variables:
+
+```bash
+docker run --pull always \
+ -p ... \
+ -e SENTRY_JS_DSN_HOST=http:https://[email protected]:8000 \
+ -e SENTRY_JS_SDK_URL=https://browser.sentry-cdn.com/7.69.0/bundle.tracing.replay.min.js \
+ ghcr.io/buggregator/server:latest
+```
+
+> **Note:** Read more about server configuration [here](../getting-started.md).
+
 ## Other platforms
 
 To report to Buggregator you’ll need to use a language-specific SDK. The Sentry team builds and maintains these for most
@@ -82,3 +148,34 @@ After you have installed the SDK, you can configure Sentry DSN to report to Bugg
 ```dotenv
 SENTRY_DSN=http:https://[email protected]:8000/1
 ```
+
+## Secret key validation
+
+Buggregator lets you send exceptions freely by default, but you can boost your security by setting up a secret key.
+
+In our example, we will use `my-secret-key` as the secret key. Let's see how to set it up.
+
+### Server configuration
+
+To use a secret key, set the `SENTRY_SECRET_KEY` environment variable on your server.
+
+**Here’s how to do it:**
+
+```bash
+docker run --pull always \
+ -p ... \
+ -e SENTRY_SECRET_KEY=my-secret-key \
+ ghcr.io/buggregator/server:latest
+```
+
+> **Note:** Read more about server configuration [here](../getting-started.md).
+
+When you set the secret key, the server checks the `X-Sentry-Auth` header to make sure it matches the secret key.
+
+### Client configuration
+
+To set the secret key on a client, change your DSN like this:
+
+```dotenv
+SENTRY_DSN=http:https://my-secret-key:[email protected]:8000/1 
+```
diff --git a/docs/config/var-dumper.md b/docs/config/var-dumper.md
@@ -1,19 +1,16 @@
 # Integration — Symfony VarDumper server
 
-Buggregator is fully compatible with
-the [Symfony VarDumper](https://symfony.com/doc/current/components/var_dumper.html#the-dump-server) component. This is a
-big deal for PHP developers because it makes debugging a lot smoother and more intuitive.
+The Symfony VarDumper tool is essential for debugging PHP applications. It helps inspect and understand PHP variables
+clearly. Normally, `dump()` and `dd()` functions show their output in the browser or console.
 
-![var-dumper](https://github.com/buggregator/server/assets/773481/b77fa867-0a8e-431a-9126-f69959dc18f4)
-
-## What is Symfony VarDumper?
+A great feature of VarDumper is redirecting debug outputs to a remote server. Using Buggregator as the remote server,
+you can receive all debug outputs from your application, making debugging smoother and more intuitive for PHP
+developers.
 
-1. **Essential Debugging Tool:** Symfony VarDumper is a powerful tool for debugging PHP applications. It helps you
- inspect and understand PHP variables in a more readable format.
+For more details, check
+the [official documentation](https://symfony.com/doc/current/components/var_dumper.html#the-dump-server).
 
-2. **Default Behavior:** By default, the `dump()` and `dd()` functions output their contents in the same browser window
- or console terminal as your own application. This can be confusing at times, as it mixes the real output with the
- debug output.
+![var-dumper](https://github.com/buggregator/server/assets/773481/b77fa867-0a8e-431a-9126-f69959dc18f4)
 
 ## Installation
 
@@ -44,3 +41,30 @@ or via PHP if there is no `.env` file in your project:
 $_SERVER['VAR_DUMPER_FORMAT'] = 'server';
 $_SERVER['VAR_DUMPER_SERVER'] = '127.0.0.1:9912';
 ```
+
+That's it! Now you can use the `dump()` and `dd()` functions as usual. The output will be sent to the remote server.
+
+## Browser performance
+
+VarDumper send data to the server in HTML format. So if you dump an object with a lot of properties and nested objects,
+it can significantly slow down the browser. To partially solve this issue, you can use `VAR_DUMPER_PREVIEW_MAX_DEPTH`
+env variable to limit the depth of the preview on the events list page.
+
+All you need to do is add environment variable to a command that starts Buggerator server:
+
+```bash
+docker run --pull always \
+ -p ... \
+ -e VAR_DUMPER_PREVIEW_MAX_DEPTH=3 \
+ ghcr.io/buggregator/server:latest
+```
+
+> **Note:** Read more about server configuration [here](../getting-started.md).
+
+And the server will show only 3 levels of nested objects in the preview, but you can still see the full dump by opening
+the event page.
+
+## Trap
+
+Please consider to use [Buggregator Trap](../trap/what-is-trap.md) to dump variables in your application. It uses
+the Symfony VarDumper component under the hood, but it's more powerful and has additional features.