From 9682b689402e271f2041642b0c2e9933c86be717 Mon Sep 17 00:00:00 2001 From: Shadrack Nicholas Date: Fri, 21 Aug 2026 11:41:43 +0200 Subject: [PATCH 1/3] feat: document support for blackfire in paas native --- .../shopware/fundamentals/application-yaml.md | 12 ++++ .../paas/shopware/monitoring/blackfire.md | 70 +++++++++++++++++++ products/paas/shopware/monitoring/index.md | 2 +- 3 files changed, 83 insertions(+), 1 deletion(-) create mode 100644 products/paas/shopware/monitoring/blackfire.md diff --git a/products/paas/shopware/fundamentals/application-yaml.md b/products/paas/shopware/fundamentals/application-yaml.md index 405e71deee..6b1facdc72 100644 --- a/products/paas/shopware/fundamentals/application-yaml.md +++ b/products/paas/shopware/fundamentals/application-yaml.md @@ -152,6 +152,18 @@ services: After enabling OpenSearch, update your application and reindex your data. See [How to set up OpenSearch](../guides/opensearch.md) for the full steps. +### `services.blackfire` + +Enables or disables Blackfire profiling. + +```yaml +services: + blackfire: + enabled: true +``` + +Requires the `BLACKFIRE_SERVER_ID` and `BLACKFIRE_SERVER_TOKEN` secrets to be set. See [Blackfire](../monitoring/blackfire.md) for the full steps. + ### `services.fastly` Configures the Fastly CDN integration. diff --git a/products/paas/shopware/monitoring/blackfire.md b/products/paas/shopware/monitoring/blackfire.md new file mode 100644 index 0000000000..d8b078e802 --- /dev/null +++ b/products/paas/shopware/monitoring/blackfire.md @@ -0,0 +1,70 @@ +--- +nav: + title: Blackfire + position: 50 +--- + +# Blackfire + +[Blackfire](https://www.blackfire.io/) is a PHP profiler that shows where time and memory are spent in a request. Shopware PaaS Native can run a Blackfire agent alongside your application, so profiles collected from your shop are sent to your own Blackfire account. + +You need an existing Blackfire account. The platform does not provide one. + +## Store your Blackfire credentials + +Blackfire identifies your agent with a **Server ID** and a **Server Token**. You find both in your Blackfire account under the settings of the environment you want to profile into. + +Create one secret for each, using the type `env`: + +```sh +sw-paas vault create +``` + +The keys must be named exactly: + +| Key | Value | +|-----|-------| +| `BLACKFIRE_SERVER_ID` | Your Blackfire Server ID | +| `BLACKFIRE_SERVER_TOKEN` | Your Blackfire Server Token | + +See [Secrets](../fundamentals/secrets.md) for more details on managing secrets. + +::: warning +Do not use your Client ID and Client Token here. Those are personal credentials used by the browser extension and the Blackfire CLI, and they are not configured in Shopware PaaS Native. +::: + +## Enable Blackfire + +Set `services.blackfire.enabled` to `true` in your [`application.yaml`](../fundamentals/application-yaml.md): + +```yaml +services: + blackfire: + enabled: true +``` + +Commit this change, push it to your git repository, and [update your application](../fundamentals/applications.md#update-your-application). + +::: warning +Both secrets must exist before you enable Blackfire. If either one is missing, the deployment fails. +::: + +Enabling Blackfire does three things for you: + +- The Blackfire probe is added to your application image during the build. You do not need to list it under `app.php.extensions`. +- A Blackfire agent is deployed next to your application. +- Your application containers are configured to send profiles to that agent. + +## Collect a profile + +Install the [Blackfire browser extension](https://blackfire.io/docs/integrations/browsers/index) or the [Blackfire CLI](https://blackfire.io/docs/up-and-running/installation) and sign in with your personal Client ID and Client Token. Open your storefront and start a profile from the extension. The resulting profiles appear in your Blackfire account. + +::: info +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 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. diff --git a/products/paas/shopware/monitoring/index.md b/products/paas/shopware/monitoring/index.md index 5761b68230..14bfd29ec5 100644 --- a/products/paas/shopware/monitoring/index.md +++ b/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. -Application performance monitoring tools such as Tideways or Blackfire are not currently supported as part of the platform, but we are working on it. +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. Shopware PaaS Native does not currently provide managed load testing as part of the platform. From 01ace0a480a0c198560bf64d478a2b6ad8cb6382 Mon Sep 17 00:00:00 2001 From: Shadrack Nicholas <46599542+shadracnicholas@users.noreply.github.com> Date: Fri, 21 Aug 2026 11:55:55 +0200 Subject: [PATCH 2/3] fix: copilot grammer sentense Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- products/paas/shopware/monitoring/blackfire.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/products/paas/shopware/monitoring/blackfire.md b/products/paas/shopware/monitoring/blackfire.md index d8b078e802..2e2a49f19b 100644 --- a/products/paas/shopware/monitoring/blackfire.md +++ b/products/paas/shopware/monitoring/blackfire.md @@ -20,7 +20,7 @@ Create one secret for each, using the type `env`: sw-paas vault create ``` -The keys must be named exactly: +The following table lists the required secret keys and their values. | Key | Value | |-----|-------| From 07b3d9d0398f7769e99a0f2d9bdc8df66c82db48 Mon Sep 17 00:00:00 2001 From: Micha Hobert Date: Fri, 28 Aug 2026 10:45:26 +0200 Subject: [PATCH 3/3] adjust/grammar-punctuation --- products/paas/shopware/monitoring/blackfire.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/products/paas/shopware/monitoring/blackfire.md b/products/paas/shopware/monitoring/blackfire.md index 2e2a49f19b..3231225c02 100644 --- a/products/paas/shopware/monitoring/blackfire.md +++ b/products/paas/shopware/monitoring/blackfire.md @@ -22,9 +22,9 @@ sw-paas vault create The following table lists the required secret keys and their values. -| Key | Value | -|-----|-------| -| `BLACKFIRE_SERVER_ID` | Your Blackfire Server ID | +| Key | Value | +|--------------------------|-----------------------------| +| `BLACKFIRE_SERVER_ID` | Your Blackfire Server ID | | `BLACKFIRE_SERVER_TOKEN` | Your Blackfire Server Token | See [Secrets](../fundamentals/secrets.md) for more details on managing secrets. @@ -60,7 +60,7 @@ Enabling Blackfire does three things for you: Install the [Blackfire browser extension](https://blackfire.io/docs/integrations/browsers/index) or the [Blackfire CLI](https://blackfire.io/docs/up-and-running/installation) and sign in with your personal Client ID and Client Token. Open your storefront and start a profile from the extension. The resulting profiles appear in your Blackfire account. ::: info -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. +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