feat: improvements for redis related documentation

guides/hosting/configurations/observability/opentelemetry.md

@@ -18,10 +18,13 @@ To use OpenTelemetry with Shopware, you need to have the following requirements
 
 ## Installation
 
-To install the OpenTelemetry Shopware extension, you need to run the following command:
+To install the OpenTelemetry Shopware extension and required dependencies, run the following commands:
 
-```bash
+```shell
 composer require shopware/opentelemetry
+composer require open-telemetry/sdk
+composer require open-telemetry/exporter-otlp open-telemetry/transport-grpc # of otlp over gRPC transport is used (recommended)
+composer require open-telemetry/opentelemetry-logger-monolog # if logs forwarding is needed
 ```
 
 This will install the OpenTelemetry Shopware bundle and create new configuration file `config/packages/prod/opentelemetry.yaml` with Symfony Flex plugin.
@@ -69,6 +72,8 @@ The OpenTelemetry instrumentation collects following traces:
 
 ![Example Trace in Grafana](../../../../assets/otel-grafana-trace.png)
 
+## Example setups
+
 ## Example Grafana Stack
 
 You can find an example [Stack](https://github.com/shopwareLabs/opentelemetry/tree/main/docker) with:

guides/hosting/infrastructure/redis.md

@@ -18,6 +18,8 @@ The data stored in Redis can be roughly classified into those three categories:
 2. Durable, but "aging" data: This data is important and cannot easily be recreated, but the relevance of the data decreases over time, e.g. sessions.
 3. Durable and critical data: This data is important and cannot easily be recreated, e.g. carts, number ranges.
 
+Please note, that in current Redis versions, it is not possible to use different eviction policies for different databases in the same Redis instance. Therefore, it is recommended to use different Redis instances for different types of data. 
+
 ## Ephemeral data
 
 As ephemeral data can easily be restored and is most often used in cases where high performance matters, this data can be stored with no durable persistence. 
@@ -59,11 +61,37 @@ shopware:
             ephemeral:
                 dsn: 'redis://host1:port/dbindex'
             persistent:
-                dsn: 'redis://host2:port/dbindex?persistent=1'
+                dsn: 'redis://host2:port/dbindex'
 ```
 
 Connection names should reflect the actual connection purpose/type and be unique. Also, the names are used as part of the service names in the container, so they should follow the service naming conventions. After defining connections, you can reference them by name in the configuration of different subsystems.
 
+It's possible to use environment variables in the DSN string, e.g. if REDIS_EPHEMERAL is set to `redis://host1:port`, the configuration could look like this:
+
+```yaml
+shopware:
+    # ...
+    redis:
+        connections:
+            ephemeral_1:
+                dsn: '%env(REDIS_EPHEMERAL)%/1' # using database 1
+            ephemeral_2:
+                dsn: '%env(REDIS_EPHEMERAL)%/2' # using database 2
+```
+
+### Connection pooling
+
+In high-load scenarios, it is recommended to use persistent connections to avoid the overhead of establishing a new connection for each request. This can be achieved by setting the `persistent` flag in DSN to 1:
+```yaml
+shopware:
+    redis:
+        connections:
+            ephemeral:
+                dsn: 'redis://host:port/dbindex?persistent=1'
+```
+Please note that the persistent flag influences connection pooling, not persistent storage of data.
+
+
 <PageRef page="../performance/cart-storage" />
 
 <PageRef page="../performance/number-ranges" />

guides/hosting/performance/cart-storage.md

@@ -42,8 +42,7 @@ shopware:
 ```
 </Tab>
 </Tabs>
-
-It is recommended to use a persistent Redis connection to avoid connection issues in high-load scenarios.
+Note that ?persistent=1 parameter here refers to the connection pooling, not the persistent storage of data. Please refer to the [Redis configuration guide](../infrastructure/redis) for more information.*
 
 ## Migrating between storages
 

guides/hosting/performance/increment.md

@@ -45,7 +45,7 @@ shopware:
     redis:
         connections:
             persistent:
-                dsn: 'redis://host:port/dbindex?persistent=1'
+                dsn: 'redis://host:port/dbindex'
 
     increment:
         user_activity:

guides/hosting/performance/number-ranges.md

@@ -36,7 +36,7 @@ shopware:
     redis:
         connections:
             persistent:
-                dsn: 'redis://host:port/dbindex?persistent=1'
+                dsn: 'redis://host:port/dbindex'
     number_range:
         increment_storage: 'redis'
         config:

guides/plugins/plugins/redis.md

@@ -9,6 +9,8 @@ nav:
 
 Starting with Shopware v6.6.8.0, Redis support has been improved, giving you more flexibility in how you use it in your projects and plugins.
 
+## Accessing Redis connections
+
 Once you've set up your Redis connections as explained in the  [Redis configuration](../../hosting/infrastructure/redis) guide, you can access them in your code using the following methods:
 
 1. Inject `Shopware\Core\Framework\Adapter\Redis\RedisConnectionProvider` and retrieve connections by name:
@@ -55,7 +57,7 @@ Once you've set up your Redis connections as explained in the  [Redis configurat
     class MyCustomService
     { 
         public function __construct (
-            private Redis $redisConnection,
+            private object $redisConnection,
         ) { }
 
         public function doSomething()
@@ -74,4 +76,22 @@ Once you've set up your Redis connections as explained in the  [Redis configurat
     ```
    Be cautious with this approach! If you change the Redis connection names in your configuration, it will cause container build errors.
 
-Keep in mind that Redis is an optional dependency in Shopware and might not be available in all installations.
+## Redis usage tips
+
+### Connection types
+Under the hood connection service objects are created using `\Symfony\Component\Cache\Adapter\RedisAdapter::createConnection` method.
+Depending on the installed extensions/libraries and DSNs provided, this method may return instance of one of the next classes:
+`\Redis|Relay|\RedisArray|\RedisCluster|\Predis\ClientInterface`
+
+### Reusing connections
+Connections are cached in static variable and reused based on the DSN provided. If you provide the same DSN for multiple connections, they will share the same connection object.
+That means you have to be careful with closing or changing connection options, as it will affect all services using the same connection.
+
+### Connection initialization
+The moment actual connection is established depends on the usage model:
+* When `RedisConnectionProvider::getConnection` is called.
+* When redis connection service is requested from container.
+* When service, that depends on Redis connection, is instantiated.
+
+### Redis is optional
+When developing a plugin, please keep in mind that Redis is an optional dependency in Shopware and might not be available in all installations.