diff --git a/.vscode/ltex.dictionary.en-US.txt b/.vscode/ltex.dictionary.en-US.txt index 65df97f5f..e7cb8f618 100644 --- a/.vscode/ltex.dictionary.en-US.txt +++ b/.vscode/ltex.dictionary.en-US.txt @@ -1,2 +1,7 @@ Symfony Fastly +Monolog +OpenTelemetry +Blackfire +gRPC +OTLP diff --git a/.wordlist.txt b/.wordlist.txt index 986042184..5f277f8a9 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1598,3 +1598,9 @@ YYYY zlib zsh ZSH +Grafana +OpenTelemetry +OTLP +gRPC +Datadog +NewRelic \ No newline at end of file diff --git a/guides/hosting/configurations/framework/monolog.md b/guides/hosting/configurations/observability/logging.md similarity index 85% rename from guides/hosting/configurations/framework/monolog.md rename to guides/hosting/configurations/observability/logging.md index eed396455..8d1d2d36c 100644 --- a/guides/hosting/configurations/framework/monolog.md +++ b/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 diff --git a/guides/hosting/configurations/opentelemetry.md b/guides/hosting/configurations/observability/opentelemetry.md similarity index 69% rename from guides/hosting/configurations/opentelemetry.md rename to guides/hosting/configurations/observability/opentelemetry.md index 850f02225..5883cd61a 100644 --- a/guides/hosting/configurations/opentelemetry.md +++ b/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('', 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) \ No newline at end of file +![Explore](../../../../assets/otel-grafana-explore.png) +![Trace](../../../../assets/otel-grafana-trace.png) \ No newline at end of file diff --git a/guides/hosting/configurations/observability/profiling.md b/guides/hosting/configurations/observability/profiling.md new file mode 100644 index 000000000..8bbde9ba7 --- /dev/null +++ b/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 + + + +``` + +The attribute `integration` is used to identify the profiler backend in the configuration. \ No newline at end of file