feat: add opentelemetry docs (#1246)

* feat: add opentelemetry docs

* create observability area

* Update guides/hosting/configurations/observability/opentelemetry.md

* Update guides/hosting/configurations/observability/opentelemetry.md

* Update guides/hosting/configurations/observability/opentelemetry.md

* Update guides/hosting/configurations/observability/opentelemetry.md

* Update guides/hosting/configurations/observability/opentelemetry.md

Co-authored-by: Su <[email protected]>

* Update guides/hosting/configurations/observability/opentelemetry.md

Co-authored-by: Su <[email protected]>

* Update guides/hosting/configurations/observability/opentelemetry.md

Co-authored-by: Su <[email protected]>

* Update guides/hosting/configurations/observability/opentelemetry.md

* Update guides/hosting/configurations/observability/opentelemetry.md

* Update guides/hosting/configurations/observability/opentelemetry.md

* Update guides/hosting/configurations/observability/opentelemetry.md

* Update guides/hosting/configurations/observability/opentelemetry.md

* Update guides/hosting/configurations/observability/opentelemetry.md

* Update .wordlist.txt

---------

Co-authored-by: Su <[email protected]>

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

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

.wordlist.txt

@@ -1598,3 +1598,13 @@ YYYY
 zlib
 zsh
 ZSH
+Grafana
+OpenTelemetry
+OTLP
+gRPC
+Datadog
+NewRelic
+OTEL
+otel
+otlp
+grpc

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/observability/opentelemetry.md

@@ -0,0 +1,96 @@
+---
+nav:
+  title: OpenTelemetry
+  position: 30
+
+---
+
+# OpenTelemetry
+
+OpenTelemetry is a standard to collect distributed traces, metrics and logs from the application. It is similar to tools like NewRelic, Datadog, Blackfire Monitoring and Tideways, but it is 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 earlier, 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
+
+To use OpenTelemetry with Shopware, you need to have the following requirements met:
+
+- `ext-opentelemetry` [PHP extension](https://github.com/open-telemetry/opentelemetry-php-instrumentation)
+- `ext-grpc` (optional, required when the transport method is gRPC)
+
+## Installation
+
+To install the OpenTelemetry Shopware extension, you need to run the following command:
+
+```bash
+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 configuration file enables the Shopware Profiler integration with OpenTelemetry in a production environment. Additionally, it specifies that the Monolog output will be directed to OpenTelemetry.
+
+## Configuration
+
+After the installation, you will need to set some environment variables to configure both, the OpenTelemetry and its exporter.
+
+### Basic configuration
+
+The following configuration enables the OpenTelemetry auto-instrumentation and sets the service name.
+
+```text
+OTEL_PHP_AUTOLOAD_ENABLED=true
+OTEL_SERVICE_NAME=shopware
+
+Refer to all possible [environment variables](https://opentelemetry.io/docs/instrumentation/php/sdk/#configuration) for better understanding.
+
+### Exporter configuration
+
+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:
+
+```text
+OTEL_TRACES_EXPORTER=otlp
+OTEL_LOGS_EXPORTER=otlp
+OTEL_METRICS_EXPORTER=otlp
+OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+
+If you use gRPC with OpenTelemetry Protocol (OTLP) , you will need to install `open-telemetry/transport-grpc open-telemetry/exporter-otlp` as composer packages.
+
+Refer to this doc for more information about the [exporters](https://opentelemetry.io/docs/instrumentation/php/exporters/).
+
+## Available instrumentation
+
+The OpenTelemetry instrumentation collects following traces:
+
+- Controller
+- Symfony HTTP Client
+- MySQL Queries
+
+![Example Trace in Grafana](../../../../assets/otel-grafana-trace.png)
+
+## Example Grafana Stack
+
+You can find an example [Stack](https://github.com/shopwareLabs/opentelemetry/tree/main/docker) with:
+
+- Grafana (Dashboard)
+- Loki (Log storage)
+- Prometheus (Metrics storage)
+- Tempo (Trace storage)
+- OpenTelemetry Collector (Collector for all data and batches it to the storage)
+
+You will need to have the following environment variables in Shopware:
+
+```text
+OTEL_PHP_AUTOLOAD_ENABLED=true
+OTEL_SERVICE_NAME=shopware
+OTEL_TRACES_EXPORTER=otlp
+OTEL_LOGS_EXPORTER=otlp
+OTEL_METRICS_EXPORTER=otlp
+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`.
+
+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)
+![Trace](../../../../assets/otel-grafana-trace.png)

guides/hosting/configurations/observability/profiling.md

@@ -0,0 +1,79 @@
+---
+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
+            # Requires the dd-trace PHP extension
+            - Datadog
+            # Requires the tideways PHP extension
+            - Tideways
+            # Requires the opentelemetry PHP extension
+            - 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.