DOC-6304 DOC-6305 DOC-6306 DOC-6308 Client observability docs

content/develop/clients/error-handling.md

@@ -277,7 +277,10 @@ graph LR
 In production, you may find it useful to log errors when they
 occur and monitor the logs for patterns. This can help you identify
 which errors are most common and whether your retry and fallback
-strategies are effective.
+strategies are effective. Note that some Redis client
+libraries have built-in instrumentation that can provide this
+information for you (see [Observability]({{< relref "/develop/clients/observability" >}})
+for a full description).
 
 ### What to log
 

content/develop/clients/go/_index.md

@@ -100,34 +100,6 @@ func main() {
 }
 ```
 
-## Observability
-
-`go-redis` supports [OpenTelemetry](https://opentelemetry.io/) instrumentation.
-to monitor performance and trace the execution of Redis commands.
-For example, the following code instruments Redis commands to collect traces, logs, and metrics:
-
-```go
-import (
-    "github.com/redis/go-redis/v9"
-    "github.com/redis/go-redis/extra/redisotel/v9"
-)
-
-client := redis.NewClient(&redis.Options{...})
-
-// Enable tracing instrumentation.
-if err := redisotel.InstrumentTracing(client); err != nil {
-	panic(err)
-}
-
-// Enable metrics instrumentation.
-if err := redisotel.InstrumentMetrics(client); err != nil {
-	panic(err)
-}
-```
-
-See the `go-redis` [GitHub repo](https://github.com/redis/go-redis/blob/master/example/otel/README.md).
-for more OpenTelemetry examples.
-
 ## More information
 
 See the other pages in this section for more information and examples.

content/develop/clients/go/observability.md

@@ -0,0 +1,114 @@
+---
+categories:
+- docs
+- develop
+- stack
+- oss
+- rs
+- rc
+- oss
+- kubernetes
+- clients
+description: Monitor your client's activity for optimization and debugging.
+linkTitle: Observability
+title: Observability
+weight: 75
+---
+
+`go-redis` has built-in support for [OpenTelemetry](https://opentelemetry.io/) (OTel)
+instrumentation to collect metrics. This can be very helpful for
+diagnosing problems and improving the performance and connection resiliency of
+your application. See the
+[Observability overview]({{< relref "/develop/clients/observability" >}})
+for an introduction to Redis client observability and a reference guide for the
+available metrics.
+
+This page explains how to enable and use OTel instrumentation
+in `go-redis` using an example configuration for a local [Grafana](https://grafana.com/)
+instance. See our
+[observability demonstration repository](https://github.com/redis-developer/redis-client-observability)
+on GitHub to learn how to set up a suitable Grafana dashboard.
+
+## Installation
+
+Install OTel support for `go-redis` with the following commands:
+
+```bash
+go get github.com/redis/go-redis/extra/redisotel-native/v9
+go get go.opentelemetry.io/otel
+```
+
+## Import
+
+Start by importing the required OTel and Redis modules:
+
+{{< clients-example set="observability" step="import" lang_filter="Go" description="Foundational: Import required libraries for Redis observability, OpenTelemetry metrics, and Redis operations" difficulty="beginner" >}}
+{{< /clients-example >}}
+
+## Configure the meter provider
+
+Otel uses a [Meter provider](https://opentelemetry.io/docs/concepts/signals/metrics/#meter-provider)
+to create the objects that collect the metric information. The example below
+configures a meter provider to export metrics to a local Grafana instance
+every 10 seconds, but see the [OpenTelemetry Go docs](https://opentelemetry.io/docs/languages/go/)
+to learn more about other export options.
+
+{{< clients-example set="observability" step="setup_meter_provider" lang_filter="Go" description="Foundational: Configure a meter provider to export metrics to a local Grafana instance every 10 seconds" difficulty="beginner" >}}
+{{< /clients-example >}}
+
+## Configure the Redis client
+
+You configure the client library for OTel only once per application. This will
+enable OTel for all Redis connections you create. The example below shows the
+options you can pass to the observability instance via the `redisotel.Config` object
+during initialization.
+
+{{< clients-example set="observability" step="client_config" lang_filter="Go" description="Foundational: Configure Redis observability with a list of metric groups and optional command filtering and privacy controls" difficulty="beginner" >}}
+{{< /clients-example >}}
+
+The available option methods for `redisotel.Config` are described in the table below.
+
+| Method | Type | Description |
+| --- | --- | --- |
+| `WithEnabled` | `bool` | Enable or disable OTel instrumentation. Default is `false`, so you must enable it explicitly. |
+| `WithMetricGroups` | `MetricGroupFlag` | Bitmap of metric groups to enable. By default, only `MetricGroupFlagConnectionBasic` and `MetricGroupFlagResiliency` are enabled. See [Redis metric groups]({{< relref "/develop/clients/observability#redis-metric-groups" >}}) for a list of available groups. |
+| `WithIncludeCommands` | `[]string` | List of Redis commands to track. If set, only these commands will be tracked. Note that you should use the Redis command name rather than the Go method name (for example `LPOP` rather than `LPopCount`). |
+| `WithExcludeCommands` | `[]string` | List of Redis commands to exclude from tracking. If set, all commands except these will be tracked. Note that you should use the Redis command name rather than the Go method name (for example `LPOP` rather than `LPopCount`). |
+| `WithHidePubSubChannelNames` | `bool` | If true, channel names in pub/sub metrics will be hidden. |
+| `WithHideStreamNames` | `bool` | If true, stream names in streaming metrics will be hidden. |
+| `WithHistogramBuckets` | `[]float64` | List of bucket boundaries for the histogram metrics. See [Custom histogram buckets](#custom-histogram-buckets) below for more information. |
+
+### Custom histogram buckets
+
+For the histogram metrics, a reasonable default set of buckets is defined, but
+you can customize the bucket boundaries to suit your needs (the buckets are the
+ranges of data values counted for each bar of the histogram). Pass an increasing
+list of float values to the `WithHistogramBuckets` option when you create the `redisotel.Config`
+object. The first and last values in the list are the lower and upper bounds of the
+histogram, respectively, and the values in between define the bucket boundaries.
+
+## Use Redis
+
+Once you have configured the client, all Redis connections you create will be
+automatically instrumented and the collected metrics will be exported to your
+configured destination.
+
+The example below shows the simplest Redis connection and a few commands,
+but see the
+[observability demonstration repository](https://github.com/redis-developer/redis-client-observability)
+for an example that calls a variety of commands in a more realistic way.
+
+{{< clients-example set="observability" step="use_redis" lang_filter="Go" description="Foundational: Use Redis with automatic instrumentation" difficulty="beginner" >}}
+{{< /clients-example >}}
+
+## Shutdown
+
+When your application exits, you should close the Redis connection and then
+you should call the `Shutdown()` method on the
+`ObservabilityInstance` and `MeterProvider` instances to ensure that all pending
+metrics are exported. You may find it useful to put the shutdown code in a
+`defer` statement to ensure that it is called even if the main function
+exits early due to an error.
+
+{{< clients-example set="observability" step="shutdown" lang_filter="Go" description="Foundational: Shutdown Redis observability" difficulty="beginner" >}}
+{{< /clients-example >}}

content/develop/clients/go/produsage.md

@@ -72,7 +72,7 @@ more detailed discussion of error handling approaches in `go-redis`.
 `go-redis` supports [OpenTelemetry](https://opentelemetry.io/). This lets
 you trace command execution and monitor your server's performance.
 You can use this information to detect problems before they are reported
-by users. See [Observability]({{< relref "/develop/clients/go#observability" >}})
+by users. See [Observability]({{< relref "/develop/clients/go/observability" >}})
 for more information.
 
 ### Retries

content/develop/clients/observability.md

@@ -0,0 +1,165 @@
+---
+categories:
+- docs
+- develop
+- stack
+- oss
+- rs
+- rc
+- oss
+- kubernetes
+- clients
+description: Monitor your client's activity for optimization and debugging.
+linkTitle: Observability
+title: Observability
+scope: overview
+relatedPages:
+- /develop/clients/redis-py/produsage
+- /develop/clients/nodejs/produsage
+- /develop/clients/go/produsage
+topics:
+- observability
+- monitoring
+- performance
+- metrics
+- logging
+- tracing
+weight: 60
+---
+
+Some Redis client libraries implement the [OpenTelemetry](https://opentelemetry.io/) (OTel)
+observability framework to let you gather performance metrics
+for your application. This can help you optimize performance and pinpoint problems
+quickly. Currently, the following clients support OTel:
+
+- [redis-py]({{< relref "/develop/clients/redis-py/observability" >}})
+- [go-redis]({{< relref "/develop/clients/go/observability" >}})
+
+<!--
+## Tracing overview
+
+An execution trace is a record of the sequence of steps that the Redis
+client takes as it executes commands. Each step or *span* (in OTel terminology)
+represents a specific operation. In the trace, each span is recorded using an identifier
+to represent the type of operation along with its start and finish time, its
+completion or error status, and other relevant information.
+
+For example, a simple trace might look like this:
+
+```hierarchy
+"Trace":
+    "Span 1":
+        _meta:
+            description: "(Start time: 10000, End time: 10005, Status: OK)"
+    "Span 2":
+        _meta:
+            description: "(Start time: 10005, End time: 10010, Status: OK)"
+```
+
+This contains two child spans, each representing a specific operation
+such as executing a command or connecting to a Redis server.
+Each span is recorded with its start time, end time, and status information.
+
+A span can sometimes be broken down into sub-tasks (such as steps taken
+while calling an external service), each of which is a span in its own right.
+The full trace is therefore best understood as a tree of nested spans.
+
+For example, a more complex trace might look like this:
+
+```hierarchy
+"Trace":
+    "Span 1":
+        _meta:
+            description: "(Start time: 10000, End time: 10005, Status: OK)"
+    "Span 2":
+        "Span 2.1":
+            _meta:
+                description: "(Start time: 10005, End time: 10010, Status: OK)"
+        "Span 2.2":
+            _meta:
+                description: "(Start time: 10010, End time: 10015, Status: OK)"
+    "Span 3":
+        "Span 3.1":
+            _meta:
+                description: "(Start time: 10015, End time: 10020, Status: OK)"
+        "Span 3.2":
+            _meta:
+                description: "(Start time: 10020, End time: 10025, Status: OK)"
+        "Span 3.3":
+            _meta:
+                description: "(Start time: 10025, End time: 10030, Status: OK)"
+```
+
+This trace shows how the second and third spans are themselves broken down into more
+granular operations.
+
+By examining the sequence of spans in a trace, you can determine where an error
+(if any) occurred and how long each step took to execute. Since the information
+in each trace is recorded, you can use monitoring tools such as
+[Grafana](https://grafana.com/) to aggregate the data from many traces over time.
+This can help you find operations that are slow on average compared to others
+(suggesting a performance bottleneck that could be optimized) or that have a high
+error rate (suggesting a deeper problem that could be fixed to improve reliability).
+-->
+
+## Metrics overview
+
+Metrics are quantitative measurements of the behavior of your application. They
+provide information such as how often a certain operation occurs, how long it
+takes to complete, or how many errors have occurred. By analyzing these metrics,
+you can identify performance bottlenecks, errors, and other issues that need to
+be addressed.
+
+## Redis metric groups
+
+In Redis clients, the metrics collected by OTel are organized into the following
+metric groups:
+
+- [`resiliency`](#group-resiliency): data related to the availability and health of the Redis connection.
+- [`connection-basic`](#group-connection-basic): minimal metrics about Redis connections made by the client.
+- [`connection-advanced`](#group-connection-advanced): more detailed metrics about Redis connections.
+- [`command`](#group-command): metrics about Redis commands executed by the client.
+- [`client-side-caching`](#group-client-side-caching): metrics about
+  [client-side caching]({{< relref "/develop/clients/client-side-caching" >}}) operations.
+- [`streaming`](#group-streaming): metrics about
+  [stream]({{< relref "/develop/data-types/streams" >}}) operations.
+- [`pubsub`](#group-pubsub): metrics about
+  [pub/sub]({{< relref "/develop/pubsub" >}}) operations.
+
+When you configure the client to activate OTel, you can select which metric groups
+you are interested in, although all metrics in the group will be collected even
+if you don't use them. The metrics in each group are described in the
+[Metrics reference](#metrics-reference) below.
+
+## Record and visualize metrics
+
+You can use a monitoring tool (such as [Grafana](https://grafana.com/)) to record and
+visualize the metrics collected by OTel. This provides a target endpoint
+that you specify when you configure the client in your application. The tool then
+collects the metrics from your application transparently as it runs. When you
+have collected the data, you can visualize it using the tool's dashboarding
+and graphing features.
+
+The [Redis client observability demonstration](https://github.com/redis-developer/redis-client-observability)
+on GitHub contains examples showing how to set up a local Grafana instance, then
+connect it to a Redis client and visualize the metric data as it arrives.
+
+## Metrics reference
+
+The metric groups and the metrics they contain are described below. The
+name in parentheses after each group name is the group's identifier, which you
+use when you configure the client to select which metrics to collect.
+
+The metrics contain *attributes* that provide extra information (such as
+the client library and server details) that you can use to filter and
+aggregate the data. The attributes are described in the Attributes
+section following the metric groups. The badge shown after the attribute
+name can be any of the following:
+
+- `required`: This attribute will always be present in the metrics.
+- `optional`: This attribute may be present in the metrics.
+- `conditionally required`: This attribute will be present in the metrics only if a certain condition is met,
+  such as when a specific error occurs. The condition is described in the attribute description.
+- `recommended`: Specific client libraries may not support this attribute in some situations.
+
+{{< otel-metric-groups >}}

content/develop/clients/patterns/_index.md

@@ -13,7 +13,7 @@ description: Novel patterns for working with Redis data structures
 linkTitle: Coding patterns
 title: Coding patterns
 aliases: /develop/use/patterns
-weight: 60
+weight: 100
 ---
 
 The following documents describe some novel development patterns you can use with Redis.