docs: document Tideways support for PaaS Native

.wordlist.txt

@@ -1065,6 +1065,7 @@ TestCase
 TestDataService
 TestSecret
 TestStockUpdateFilter
+Tideways
 TimeRangeRule
 TimeZoneField
 Timezones
@@ -2100,6 +2101,7 @@ textarea
 th
 theming
 themself
+tideways
 timeframe
 timeframes
 tinyint

products/paas/shopware/faq.md

@@ -127,7 +127,7 @@ No. Single sign-on for tools such as Grafana and OpenSearch is not available at
 
 ## Are Blackfire or Tideways included?
 
-No. Tideways and Blackfire are not currently supported as part of the platform.
+Both are supported, but you need to bring your own account. The platform runs the agent for you once you store the credentials as secrets and enable the service in your `application.yaml`. Only one of them can be enabled at a time. See [Blackfire](./monitoring/blackfire.md) and [Tideways](./monitoring/tideways.md).
 
 ## Are load tests provided by Shopware PaaS Native?
 

products/paas/shopware/fundamentals/application-yaml.md

@@ -164,6 +164,20 @@ services:
 
 Requires the `BLACKFIRE_SERVER_ID` and `BLACKFIRE_SERVER_TOKEN` secrets to be set. See [Blackfire](../monitoring/blackfire.md) for the full steps.
 
+### `services.tideways`
+
+Enables or disables Tideways monitoring.
+
+```yaml
+services:
+  tideways:
+    enabled: true
+```
+
+Requires the `TIDEWAYS_API_KEY` secret to be set. See [Tideways](../monitoring/tideways.md) for the full steps.
+
+Blackfire and Tideways cannot be enabled at the same time.
+
 ### `services.fastly`
 
 Configures the Fastly CDN integration.

products/paas/shopware/monitoring/blackfire.md

@@ -63,8 +63,11 @@ Install the [Blackfire browser extension](https://blackfire.io/docs/integrations
 Pages served from the CDN cache never reach PHP, so they cannot be profiled. If a profile does not appear, request the page in a way that bypasses the cache, for example, by profiling a page that is not cacheable.
 :::
 
-## Blackfire and tracing
+## Blackfire, Tideways, and tracing
 
-Blackfire and OpenTelemetry tracing cannot be used at the same time. While Blackfire is enabled, your application does not send traces, and the Tempo data source in Grafana stays empty for the affected time range. See [Traces](./traces.md) for details on tracing.
+Only one profiler can be active at a time:
+
+- Blackfire and [Tideways](./tideways.md) cannot be enabled together. If both are set to `true`, the configuration is rejected with the error `blackfire and tideways cannot be enabled at the same time`.
+- Blackfire and OpenTelemetry tracing cannot be used at the same time. While Blackfire is enabled, your application does not send traces, and the Tempo data source in Grafana stays empty for the affected time range. See [Traces](./traces.md) for details on tracing.
 
 To go back to tracing, set `services.blackfire.enabled` to `false` and update your application again.

products/paas/shopware/monitoring/index.md

@@ -10,6 +10,6 @@ Shopware PaaS Native provides comprehensive monitoring capabilities to help you
 
 Grafana access is currently provided through credentials returned by the CLI via the `sw-paas open grafana` command. Single sign-on for Grafana and similar tools is not available at this stage.
 
-Blackfire is supported for profiling PHP requests, see [Blackfire](./blackfire.md). Other application performance monitoring tools such as Tideways are not currently supported as part of the platform, but we are working on it.
+Two profilers are supported for PHP requests: [Blackfire](./blackfire.md) and [Tideways](./tideways.md). Only one of them can be enabled at a time, and each requires your own account with the respective vendor. Other application performance monitoring tools are not currently supported as part of the platform.
 
 Shopware PaaS Native does not currently provide managed load testing as part of the platform.

products/paas/shopware/monitoring/tideways.md

@@ -0,0 +1,66 @@
+---
+nav:
+  title: Tideways
+  position: 60
+---
+
+# Tideways
+
+[Tideways](https://tideways.com/) is a PHP monitoring and profiling tool that continuously collects performance data from your application. Shopware PaaS Native can run a Tideways daemon alongside your application, so the traces and profiles collected from your shop are sent to your own Tideways organization.
+
+You need an existing Tideways account. The platform does not provide one.
+
+## Store your Tideways API key
+
+Tideways authenticates the daemon with the API key of the project you want to monitor. You find it in your Tideways account under the settings of that project.
+
+Create a secret with the type `env` and the key `TIDEWAYS_API_KEY`, holding your Tideways API key as the value:
+
+```sh
+sw-paas vault create
+```
+
+See [Secrets](../fundamentals/secrets.md) for more details on managing secrets.
+
+## Enable Tideways
+
+Set `services.tideways.enabled` to `true` in your [`application.yaml`](../fundamentals/application-yaml.md):
+
+```yaml
+services:
+  tideways:
+    enabled: true
+```
+
+Commit this change, push it to your git repository, and [update your application](../fundamentals/applications.md#update-your-application).
+
+::: warning
+The secret must exist before you enable Tideways. If it is missing, the deployment fails.
+:::
+
+Enabling Tideways does three things for you:
+
+- The Tideways PHP extension is added to your application image during the build. You do not need to list it under `app.php.extensions`.
+- A Tideways daemon is deployed next to your application.
+- Your application containers are configured to send data to that daemon.
+
+Tideways is only available for shop applications. Enabling it on Composable Frontends application is rejected when the configuration is validated.
+
+## View your data
+
+Open your Tideways account and select the project that belongs to the API key you stored. Your shop reports under the service name `shopware`, and the environment matches the environment your application is deployed to.
+
+Monitoring data arrives continuously once the deployment is finished. No browser extension or CLI is needed.
+
+::: info
+Pages served from the CDN cache never reach PHP, so they do not show up in Tideways. If a request is missing, request the page in a way that bypasses the cache, for example, by looking at a page that is not cacheable.
+:::
+
+## Tideways, Blackfire, and tracing
+
+Only one profiler can be active at a time:
+
+- Tideways and [Blackfire](./blackfire.md) cannot be enabled together. If both are set to `true`, the configuration is rejected with the error `blackfire and tideways cannot be enabled at the same time`.
+- Tideways and OpenTelemetry tracing cannot be used at the same time. While Tideways is enabled, your application does not send traces, and the Tempo data source in Grafana stays empty for the affected time range. See [Traces](./traces.md) for details on tracing.
+
+To go back to tracing, set `services.tideways.enabled` to `false` and update your application again.