create observability area

.vscode/ltex.dictionary.en-US.txt

@@ -1,2 +1,7 @@
 Symfony
 Fastly
+Monolog
+OpenTelemetry
+Blackfire
+gRPC
+OTLP

.wordlist.txt

@@ -1598,3 +1598,9 @@ YYYY
 zlib
 zsh
 ZSH
+Grafana
+OpenTelemetry
+OTLP
+gRPC
+Datadog
+NewRelic

guides/hosting/configurations/framework/monolog.md → guides/hosting/configurations/observability/logging.md

@@ -1,15 +1,15 @@
 ---
 nav:
-  title: Monolog
-  position: 20
+  title: Logging
+  position: 10
 
 ---
 
-# Monolog
+# Logging
 
 ## Overview
 
-Monolog is a logging library for PHP. It is used by Shopware to log errors and debug information. The log files are located in the `var/log` directory of your Shopware installation.
+Monolog is the logging library for PHP. It is used by Shopware to log errors and debug information. The log files are located in the `var/log` directory of your Shopware installation.
 
 ## Configuration
 

guides/hosting/configurations/opentelemetry.md → guides/hosting/configurations/observability/opentelemetry.md

@@ -1,13 +1,13 @@
 ---
 nav:
   title: OpenTelemetry
-  position: 20
+  position: 30
 
 ---
 
 # OpenTelemetry
 
-OpenTelemetry is a standard to collect distributed traces, metrics and logs from the application. It's similar to tools like NewRelic, DataDog, Blackfire Monitoring and Tideways, but it's completely open source and vendor neutral. That means you can use OpenTelemetry to collect the data and push it to one of the vendors mentioned above, or you can use it to collect the data and push it to your own infrastructure with tools like Grafana Stack (Tempoo, Loki, Prometheus, Grafana) or other tools.
+OpenTelemetry is a standard to collect distributed traces, metrics and logs from the application. It's similar to tools like NewRelic, Datadog, Blackfire Monitoring and Tideways, but it's completely open source and vendor neutral. That means you can use OpenTelemetry to collect the data and push it to one of the vendors mentioned above, or you can use it to collect the data and push it to your own infrastructure with tools like Grafana Stack (Tempo, Loki, Prometheus, Grafana) or other tools.
 
 ## Requirements
 
@@ -26,7 +26,7 @@ composer require shopware/opentelemetry
 
 This will install the OpenTelemetry Shopware bundle and create new configuration file `config/packages/prod/opentelemetry.yaml` with Symfony Flex plugin.
 
-This file configures in production that the Shopware Profiler integration with OpenTelemetry is enabled and also configures that the monolog output will be sent to OpenTelemetry.
+This file configures in production that the Shopware Profiler integration with OpenTelemetry is enabled and also configures that the Monolog output will be sent to OpenTelemetry.
 
 ## Configuration
 
@@ -41,9 +41,11 @@ OTEL_PHP_AUTOLOAD_ENABLED=true
 OTEL_SERVICE_NAME=shopware
 ```
 
+You can find all possible environment variables [here](https://opentelemetry.io/docs/instrumentation/php/sdk/#configuration).
+
 ### Exporter configuration
 
-The OpenTelemetry extension needs to be configured to export the data to your collector. Here is an example todo that with with the OTLP exporter with GRPC:
+The OpenTelemetry extension needs to be configured to export the data to your collector. Here is an example configuration for the OpenTelemetry Collector using gRPC:
 
 ```
 OTEL_TRACES_EXPORTER=otlp
@@ -53,35 +55,23 @@ OTEL_EXPORTER_OTLP_PROTOCOL=grpc
 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
 ```
 
-If you use GRPC with OTLP, you will need to install also `open-telemetry/transport-grpc open-telemetry/exporter-otlp` as composer packages.
+If you use gRPC with OTLP, you will need to install also `open-telemetry/transport-grpc open-telemetry/exporter-otlp` as composer packages.
 
 You can find more about the exporters [here](https://opentelemetry.io/docs/instrumentation/php/exporters/).
 
 ## Available instrumentation
 
-The OpenTelemetry instrucmentation collects following traces:
+The OpenTelemetry instrumentation collects following traces:
 
 - Controller
 - Symfony HTTP Client
 - MySQL Queries
 
-![Example Trace in Grafana](assets/otel-grafana-trace.png)
-
-### Adding custom spans
-
-This spans are working with all profilers (Symfony Profiler bar, Tideways, ...) and are not exclusive to OpenTelemetry.
-
-```php
-use Shopware\Core\Profiling\Profiler;
-
-$value = Profiler::trace('<name>', function () {
-    return $myFunction();
-});
-```
+![Example Trace in Grafana](../../../../assets/otel-grafana-trace.png)
 
 ## Example Grafana Stack
 
-You can find a example Stack [here](https://github.com/shopwareLabs/opentelemetry/tree/main/docker) with:
+You can find an example Stack [here](https://github.com/shopwareLabs/opentelemetry/tree/main/docker) with:
 
 - Grafana (Dashboard)
 - Loki (Log storage)
@@ -101,9 +91,9 @@ OTEL_EXPORTER_OTLP_PROTOCOL=grpc
 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
 ```
 
-and following two composer packages installed: `open-telemetry/transport-grpc open-telemetry/exporter-otlp`.
+And following two composer packages installed: `open-telemetry/transport-grpc open-telemetry/exporter-otlp`.
 
-The example Grafana is pre-configured to use the data sources and it is enabled to go from logs to traces and from traces to the logs.
+The example Grafana is pre-configured to use the data sources, and it is enabled to go from logs to traces and from traces to the logs.
 
-![Explore](assets/otel-grafana-explore.png)
-![Explore](assets/otel-grafana-trace.png)
+![Explore](../../../../assets/otel-grafana-explore.png)
+![Trace](../../../../assets/otel-grafana-trace.png)

guides/hosting/configurations/observability/profiling.md

@@ -0,0 +1,76 @@
+---
+nav:
+  title: Profiling / Tracing
+  position: 20
+
+---
+
+# Profiling
+
+Shopware provides a built-in profiler abstraction to measure the performance of code parts and publish this data to a profiler backend.
+
+## Enabling the profiler backends
+
+By default, only the Stopwatch profiler (Symfony Profiler Bar) is enabled. To enable the other profiler backends, you have to add the following configuration to your `config/packages/shopware.yaml` file:
+
+```yaml
+shopware:
+    profiler:
+        integrations:
+            - Symfony
+            - Datadog
+            - Tideways
+            - OpenTelemetry
+```
+
+::: info
+The OpenTelemetry profiler is not installed by default. Checkout the [OpenTelemetry Integration](./opentelemetry.md) to learn how to install it. 
+:::
+
+## Adding custom spans
+
+To add custom spans to the profiler, you can use the `Shopware\Core\Profiling\Profiler::trace` method:
+
+```php
+use Shopware\Core\Profiling\Profiler;
+
+$value = Profiler::trace('my-example-trace', function () {
+    return $myFunction();
+});
+```
+
+And then you can see the trace in the configured profiler backends.
+
+## Adding a custom profiler backend
+
+To add a custom profiler backend, you need to implement the `Shopware\Core\Profiling\Integration\ProfilerInterface` interface and register it as a service with the tag `shopware.profiler`.
+
+The following example shows a custom profiler backend that logs the traces to the console:
+
+```php
+
+namespace App\Profiler;
+
+use Shopware\Core\Profiling\Integration\ProfilerInterface;
+
+class ConsoleProfiler implements ProfilerInterface
+{
+    public function start(string $title, string $category, array $tags): void
+    {
+        echo "Start $name\n";
+    }
+
+    public function stop(string $title): void
+    {
+        echo "Stop $name\n";
+    }
+}
+```
+
+```xml
+<service id="App\Profiler">
+    <tag name="shopware.profiler" integration="Console"/>
+</service>
+```
+
+The attribute `integration` is used to identify the profiler backend in the configuration.