Merge pull request #2070 from brefphp/rework-monitoring-docs

Rewrite monitoring docs

Author: mnapoli

docs/monitoring.mdx

@@ -0,0 +1,74 @@
+import Image from 'next/image';
+import cloudXrayTrace from './monitoring/cloud-xray-trace.png';
+import cloudXrayFiltersGeneral from './monitoring/cloud-xray-filters-general.png';
+import cloudXrayFiltersAnnotations from './monitoring/cloud-xray-filters-annotations.png';
+import cloudOverview from './monitoring/cloud-overview.png';
+import cloudLogs from './monitoring/cloud-logs.png';
+
+# Monitoring
+
+By default, AWS Lambda publishes PHP logs and metrics to [AWS CloudWatch](https://aws.amazon.com/cloudwatch/). These include HTTP response times, code execution duration, error rates, and more.
+
+Here is a summary of recommended tools for monitoring Bref applications:
+
+- **Logs and metrics**: CloudWatch (built-in), [Bref Cloud](/cloud)
+- **Error tracking**: [Sentry](https://sentry.io) and similar services
+- **Performance tracing**: [Bref Cloud](/cloud) with [X-Ray](/xray)
+
+Let's dive into the details of each of them.
+
+## Sentry
+
+[Sentry](https://sentry.io) is a popular error tracking service. It works well out of the box with Bref for HTTP applications: install the [Sentry SDK for PHP](https://docs.sentry.io/platforms/php/) (or the [Laravel](https://docs.sentry.io/platforms/php/guides/laravel/) or [Symfony](https://docs.sentry.io/platforms/php/guides/symfony/) integrations) and errors will be tracked automatically.
+
+For more advanced use cases, such as tracking Lambda errors outside of PHP-FPM (timeouts, oversized responses…), monitoring event-driven handlers (SQS, EventBridge, S3…), or tracking cold starts and AWS SDK calls, the [Bref Sentry package](/sentry) extends Sentry's capabilities for AWS Lambda. It is available as a [separate license](/sentry).
+
+## Bref Cloud
+
+[Bref Cloud](/cloud) provides an all-in-one monitoring experience for serverless PHP applications:
+
+<Image className="mt-3 rounded-lg shadow-md border" src={cloudOverview} alt="Bref Cloud application overview" />
+
+- **Logs**: view and search CloudWatch logs in a simplified UI.
+
+<Image className="mt-3 rounded-lg shadow-md border" src={cloudLogs} alt="Log viewer in Bref Cloud" />
+
+- **Metrics**: monitor Lambda invocations, duration, errors, and more.
+- **Traces**: visualize X-Ray traces to understand the performance of your application, including database queries, HTTP calls, and AWS SDK calls.
+
+<Image className="mt-3 rounded-lg shadow-md border" src={cloudXrayTrace} alt="X-Ray trace in Bref Cloud" />
+
+With the [Bref X-Ray](/xray) package, traces are enriched with annotations that you can use to filter and search. For example, you can filter traces by specific controller, route, CLI command, or job class:
+
+<div className="flex gap-4 mt-3 items-start">
+    <Image className="rounded-lg shadow-md border h-auto" style={{maxHeight: 350, width: 'auto'}} src={cloudXrayFiltersGeneral} alt="X-Ray trace filters in Bref Cloud" />
+    <Image className="rounded-lg shadow-md border h-auto" style={{maxHeight: 350, width: 'auto'}} src={cloudXrayFiltersAnnotations} alt="X-Ray trace annotation filters in Bref Cloud" />
+</div>
+
+Bref Cloud users get a **free [Bref X-Ray](/xray) license** included in their plan to enable performance tracing. To activate it, contact support via [bref.cloud/support](https://bref.cloud/support) or [Slack](https://bref.sh/slack).
+
+[Learn more about Bref Cloud](/cloud).
+
+## X-Ray
+
+[AWS X-Ray](https://aws.amazon.com/xray/) provides distributed tracing for Lambda applications. The [Bref X-Ray package](/xray) integrates X-Ray with PHP, tracking cold starts, database queries, HTTP calls, AWS SDK calls, and more. It supports both Laravel and Symfony.
+
+The package can be used with or without Bref Cloud. Bref Cloud users get a free license (see above), while others can [purchase a standalone license](/xray).
+
+## Sentry Lambda package
+
+As mentioned above, the standard Sentry SDK works great for HTTP applications. The [Bref Sentry package](/sentry) goes further by adding Lambda-specific capabilities: tracking errors outside of PHP-FPM, monitoring event-driven handlers, and tracking cold starts.
+
+The package can be used with or without Bref Cloud. It is available as a [standalone license](/sentry).
+
+## Bref Dashboard
+
+The [Bref Dashboard](https://dashboard.bref.sh/?ref=bref) is an alternative for projects that do not use Bref Cloud. It fetches data from AWS CloudWatch and provides a simple UI for logs and metrics. It requires no setup in AWS and can be used straight away.
+
+[![Bref Dashboard](./monitoring/bref-dashboard.png)](https://dashboard.bref.sh/?ref=bref)
+
+## Tideways
+
+[Tideways](https://tideways.com/?ref=bref) is a PHP-specific monitoring and profiling tool that can be used with Bref. It requires setting up a daemon on an EC2 instance in a VPC.
+
+[Learn more about using Tideways with Bref](./monitoring/tideways.md).

docs/monitoring/_meta.json

@@ -0,0 +1,5 @@
+{
+  "tideways": {
+    "display": "hidden"
+  }
+}

docs/monitoring/cloud-logs.png

@@ -1,33 +1,4 @@
-# Monitoring
-
-By default, AWS Lambda publishes all logs and general metrics (HTTP response time, code execution duration, etc.) to AWS CloudWatch.
-
-It is possible to view these logs and metrics directly in the [AWS console](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1). However, the CloudWatch UI can be complex and overwhelming.
-
-As an alternative, we can use [Bref Cloud](/cloud) or the [Bref Dashboard](https://dashboard.bref.sh/?ref=bref) to view these logs and metrics. It provides a simpler UI designed for serverless PHP applications.
-
-For advanced metrics and profiling, we can use [Tideways](https://tideways.com/?ref=bref), or [Sentry's performance monitoring](/sentry). Note that [Serverless.com's Dashboard](https://www.serverless.com/) is not compatible with PHP.
-
-To summarize:
-
-- **General monitoring**: [Bref Cloud](/cloud), CloudWatch, or [Bref Dashboard](https://dashboard.bref.sh/?ref=bref)
-- **Advanced monitoring and profiling**: [Tideways](https://tideways.com/?ref=bref), [Sentry](/sentry)
-
-## Bref Cloud
-
-[Bref Cloud](/cloud) is an all-in-one platform for serverless PHP applications. It provides a simple UI to view logs, metrics, and errors, and it is designed specifically for PHP applications running on AWS Lambda.
-
-[Learn more about Bref Cloud](/cloud).
-
-## Bref Dashboard
-
-As mentioned above, the [Bref Dashboard](https://dashboard.bref.sh/?ref=bref) fetches data from AWS CloudWatch (which is published by default by all serverless applications). As such, it requires no setup in AWS and can be used straight away.
-
-[![Bref Dashboard](./monitoring/bref-dashboard.png)](https://dashboard.bref.sh/?ref=bref)
-
-## Tideways
-
-> Disclaimer: Tideways is a Bref sponsor ❤️
+# Monitoring with Tideways
 
 To use [Tideways](https://tideways.com/?ref=bref) with Bref, we first need to [create a Tideways account](https://app.tideways.io/register/).
 
@@ -38,17 +9,17 @@ Next, we will need to set up two pieces:
 
 Indeed, the PHP extension runs in the same process as the PHP application and collects traces and advanced metrics. It then sends this data to a Tideways daemon, that will collect it and forward it to tideways.com. That ensures the PHP extension does not add latency to the PHP application.
 
-![](./monitoring/tideways-schema.svg)
+![](./tideways-schema.svg)
 
 The connexion between the PHP extension and the daemon needs to be secured. This is why the PHP lambda and the EC2 instance need to run in a VPC (virtual private network), and the EC2 instance should only be reachable from inside the VPC.
 
-### Complete example
+## Complete example
 
 The sections below describe how to set up the daemon and PHP extension manually.
 
 Alernatively, you can have a look at a complete and deployable example: [github.com/tideways/bref-tideways-example](https://github.com/tideways/bref-tideways-example). In this example, we deploy the PHP application, the VPC and the daemon in one command via `serverless.yml`.
 
-### Setting up the daemon
+## Setting up the daemon
 
 Assuming we already have a VPC set up (the [serverless-vpc-plugin](https://github.com/smoketurner/serverless-vpc-plugin) is a good solution to create one), the daemon must be started in the VPC.
 
@@ -73,7 +44,7 @@ Assuming we already have a VPC set up (the [serverless-vpc-plugin](https://githu
 
 Once the daemon has started, copy its "Private IP DNS name", we will use it to configure the PHP application.
 
-### Setting up the PHP application
+## Setting up the PHP application
 
 First, let's install the Tideways PHP extension (it is distributed via the Bref extra extensions):
 
@@ -125,7 +96,7 @@ provider:
 ```
 
 > **Note**:
-> 
+>
 > The `TIDEWAYS_CONNECTION` variable should contain the "Private IP DNS name" of the Tideways daemon (for example `tcp://ip-172-31-4-74.eu-west-1.compute.internal:9135`). This is the value you retrieved in the previous section.
 
 Don't forget to redeploy the application:

docs/monitoring/cloud-overview.png

@@ -84,6 +84,17 @@ const sections = [
                     cloud: true,
                 }
             },
+            { name: 'X-Ray tracing', tiers: {
+                    bref: {
+                        title: false,
+                        description: 'AWS CloudWatch (advanced) <br> + extra <a class="underline" href="/xray">Bref X-Ray</a> license',
+                    },
+                    cloud: {
+                        title: true,
+                        description: 'Trace explorer optimized for PHP apps. <br> No extra license needed.',
+                    },
+                }
+            },
             { name: 'Queue jobs management', tiers: { bref: false, cloud: true } },
             { name: 'Secrets management', tiers: {
                     bref: {

docs/monitoring/cloud-xray-filters-annotations.png

@@ -12,6 +12,10 @@ This package provides an advanced integration between Bref applications and [AWS
 
 Check out the documentation below for screenshots and more details. View the [changelog](/xray/changelog) for the latest updates and releases.
 
+<Callout type="info">
+    **Bref Cloud users** get a free X-Ray license included in their plan. You can view traces directly in the [Bref Cloud dashboard](/docs/monitoring#bref-cloud). To activate your free license, contact support via [bref.cloud/support](https://bref.cloud/support) or [Slack](https://bref.sh/slack).
+</Callout>
+
 ## Installation
 
 ### 1. Enable Packagist.com