docs: address PR opensearch-project#812 review feedback

- guides/metrics.md: fix nonexistent opensearchtransport.WithObserver()
  reference; describe Observer field on opensearch.Config instead
- guides/metrics.md: hoist safeFloat helper out of for-loop body so the
  polling example is parseable Go
- guides/metrics.md: align aggregate tables to Field (Go name) + JSON
  (tag) layout matching ConnectionMetric/PolicySnapshot/RouterSnapshot
- guides/error_handling.md, v5preview/opensearchapi/README.md: drop
  *PartialBulkError and *ShardFailureError from MSearch switch examples
  (MSearch never returns them); fix the duplicate pre-existing example
  in v5preview README
- guides/error_handling.md: qualify "folded into err" claim with the
  v4-vs-v5preview default-mask caveat
- CHANGELOG.md: rewrite "prefer for/switch pattern over Errors(err)"
  bullet to recommend the pattern over per-Resp helpers, not over
  Errors(err)

Signed-off-by: Sean Chittenden <sean.chittenden@crowdstrike.com>

Author: sean-

CHANGELOG.md

@@ -102,7 +102,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
   - `opensearchapi.Errors(err) []error` package-level helper that flattens single- and multi-wrapper errors into a uniform slice; recommended call-site pattern is a `for`/`switch` over the result (not `errors.As` against a specific type)
   - Helper functions: `IsPartialFailure`, `ToleratePartialFailures`, `RequireSuccessRate` for threshold-based error tolerance
   - Operation constants: `OperationIndex`, `OperationCreate`, `OperationUpdate`, `OperationDelete`
-  - Per-Resp helper methods (`BulkItemFailures`, `SearchShardFailures`, `WriteShardFailures`, `MultiSearchItemFailures`, `PartialFailures(mask)`) exist on the response types as engine machinery for the dispatch; new code should prefer the `for`/`switch` pattern over `opensearchapi.Errors(err)` for forward compatibility
+  - Per-Resp helper methods (`BulkItemFailures`, `SearchShardFailures`, `WriteShardFailures`, `MultiSearchItemFailures`, `PartialFailures(mask)`) exist on the response types as engine machinery for the dispatch; new code should prefer a `for`/`switch` over `opensearchapi.Errors(err)` rather than the per-Resp helpers, for forward compatibility
   - `Config.Errors *errmask.ErrorMask` replaces a single boolean: each bit suppresses one wrapper category. v4 defaults to `errmask.All` (mask everything, preserves pre-bitfield behavior); v5+ defaults to `errmask.Empty` (report everything)
   - `OPENSEARCH_GO_ERROR_MASK` environment variable overrides `Config.Errors` at runtime via comma-separated `+`/`-` tokens (lowercase snake_case wrapper names; unknown tokens silently dropped, debug-logged)
   - Both `(resp, error)` are non-nil on partial failure -- response is fully populated

guides/error_handling.md

@@ -219,7 +219,9 @@ resp, err := client.Bulk(ctx, req)
 if err != nil {
     return err
 }
-// resp is fully populated; partial failures (if any) are folded into err.
+// resp is fully populated; partial failures (if any) are folded into err
+// when the wrapper bits are unmasked (the v5preview default, or v4 with
+// Config.Errors: errmask.New()).
 ```
 
 **Inspect categories with a `for`/`switch`** -- when partial error handling is appropriate. Partial error handling lets the client and its application recover from known failure modes they can tolerate (e.g. continue serving a search with a few failed shards, or retry only the bulk items the server rejected) instead of failing the whole operation. The `default` arm catches transport / HTTP / decode errors and any partial-failure category added in a future release:
@@ -228,14 +230,10 @@ if err != nil {
 resp, err := client.MSearch(ctx, req)
 for _, sub := range opensearchapi.Errors(err) {
     switch e := sub.(type) {
-    case *opensearchapi.PartialBulkError:
-        log.Printf("%d items failed", len(e.FailedItems))
     case *opensearchapi.PartialSearchError:
         log.Printf("%d/%d shards failed", e.FailedShards, e.TotalShards)
     case *opensearchapi.MultiSearchItemError:
         log.Printf("%d sub-queries failed", len(e.Items))
-    case *opensearchapi.ShardFailureError:
-        log.Printf("%s: %d/%d shards failed", e.Operation, e.FailedShards, e.TotalShards)
     default:
         return err
     }

guides/metrics.md

@@ -34,39 +34,39 @@ The top-level `Metrics` struct contains aggregate counters, per-connection detai
 
 ### Request Counters
 
-| Field       | Type          | Description                               |
-| ----------- | ------------- | ----------------------------------------- |
-| `requests`  | `int`         | Total requests performed by the transport |
-| `failures`  | `int`         | Total request failures                    |
-| `responses` | `map[int]int` | Response count by HTTP status code        |
+| Field       | JSON        | Type          | Description                               |
+| ----------- | ----------- | ------------- | ----------------------------------------- |
+| `Requests`  | `requests`  | `int`         | Total requests performed by the transport |
+| `Failures`  | `failures`  | `int`         | Total request failures                    |
+| `Responses` | `responses` | `map[int]int` | Response count by HTTP status code        |
 
 ### Connection Pool State
 
-| Field                 | Type  | Description                                 |
-| --------------------- | ----- | ------------------------------------------- |
-| `live_connections`    | `int` | Non-dead connections (active + standby)     |
-| `dead_connections`    | `int` | Connections in the dead list                |
-| `standby_connections` | `int` | Connections in the standby partition        |
-| `overloaded_servers`  | `int` | Connections the client considers overloaded |
+| Field                | JSON                  | Type  | Description                                 |
+| -------------------- | --------------------- | ----- | ------------------------------------------- |
+| `LiveConnections`    | `live_connections`    | `int` | Non-dead connections (active + standby)     |
+| `DeadConnections`    | `dead_connections`    | `int` | Connections in the dead list                |
+| `StandbyConnections` | `standby_connections` | `int` | Connections in the standby partition        |
+| `OverloadedServers`  | `overloaded_servers`  | `int` | Connections the client considers overloaded |
 
 ### Connection Lifecycle Counters
 
-| Field                  | Type  | Description                                          |
-| ---------------------- | ----- | ---------------------------------------------------- |
-| `connections_promoted` | `int` | Dead to ready transitions (successful resurrections) |
-| `connections_demoted`  | `int` | Ready to dead transitions                            |
-| `zombie_connections`   | `int` | Dead connections forcibly retried                    |
-| `standby_promotions`   | `int` | Standby to active transitions                        |
-| `standby_demotions`    | `int` | Active to standby transitions                        |
+| Field                 | JSON                   | Type  | Description                                          |
+| --------------------- | ---------------------- | ----- | ---------------------------------------------------- |
+| `ConnectionsPromoted` | `connections_promoted` | `int` | Dead to ready transitions (successful resurrections) |
+| `ConnectionsDemoted`  | `connections_demoted`  | `int` | Ready to dead transitions                            |
+| `ZombieConnections`   | `zombie_connections`   | `int` | Dead connections forcibly retried                    |
+| `StandbyPromotions`   | `standby_promotions`   | `int` | Standby to active transitions                        |
+| `StandbyDemotions`    | `standby_demotions`    | `int` | Active to standby transitions                        |
 
 ### Health Check Counters
 
-| Field                   | Type  | Description                                        |
-| ----------------------- | ----- | -------------------------------------------------- |
-| `health_checks`         | `int` | Baseline `GET /` health checks performed           |
-| `cluster_health_checks` | `int` | `GET /_cluster/health?local=true` checks performed |
-| `health_checks_success` | `int` | Successful health check outcomes                   |
-| `health_checks_failed`  | `int` | Failed health check outcomes                       |
+| Field                 | JSON                    | Type  | Description                                        |
+| --------------------- | ----------------------- | ----- | -------------------------------------------------- |
+| `HealthChecks`        | `health_checks`         | `int` | Baseline `GET /` health checks performed           |
+| `ClusterHealthChecks` | `cluster_health_checks` | `int` | `GET /_cluster/health?local=true` checks performed |
+| `HealthChecksSuccess` | `health_checks_success` | `int` | Successful health check outcomes                   |
+| `HealthChecksFailed`  | `health_checks_failed`  | `int` | Failed health check outcomes                       |
 
 ---
 
@@ -169,6 +169,13 @@ Each index with an active routing slot produces an entry in `Router.Indexes`.
 Poll metrics on a timer for logging or export to an external monitoring system.
 
 ```go
+func safeFloat(f *float64) float64 {
+    if f == nil {
+        return 0
+    }
+    return *f
+}
+
 ticker := time.NewTicker(30 * time.Second)
 defer ticker.Stop()
 
@@ -207,13 +214,6 @@ for range ticker.C {
         }
     }
 }
-
-func safeFloat(f *float64) float64 {
-    if f == nil {
-        return 0
-    }
-    return *f
-}
 ```
 
 ## JSON Export
@@ -249,6 +249,6 @@ The metrics API is pull-based: call `client.Metrics()` inside your collector's `
 
 ## Observer API
 
-For event-driven observability (as opposed to polling), implement the `ConnectionObserver` interface and pass it via `opensearchtransport.WithObserver()`. The observer receives callbacks for connection lifecycle events (promote, demote, overload), routing decisions, health checks, and shard map invalidations. See the [routing guide](routing.md) for details on observer events.
+For event-driven observability (as opposed to polling), implement the `opensearchtransport.ConnectionObserver` interface and set it on the `Observer` field of `opensearch.Config`. The observer receives callbacks for connection lifecycle events (promote, demote, overload), routing decisions, health checks, and shard map invalidations. See the [routing guide](routing.md) for details on observer events.
 
 The metrics API and observer API are complementary: metrics give you aggregate snapshots for dashboards, while the observer gives you per-event detail for tracing and debugging.

v5preview/opensearchapi/README.md

@@ -238,10 +238,6 @@ for _, sub := range opensearchapi.Errors(err) {
         log.Printf("shard agg: %d/%d shards failed", e.FailedShards, e.TotalShards)
     case *opensearchapi.MultiSearchItemError:
         log.Printf("%d sub-queries failed", len(e.Items))
-    case *opensearchapi.PartialBulkError:
-        log.Printf("%d items failed", len(e.FailedItems))
-    case *opensearchapi.ShardFailureError:
-        log.Printf("%s: %d/%d shards failed", e.Operation, e.FailedShards, e.TotalShards)
     default:
         return err // transport / HTTP / decoding error
     }
@@ -284,14 +280,10 @@ if err != nil {
 resp, err := client.MSearch(ctx, req)
 for _, sub := range opensearchapi.Errors(err) {
     switch e := sub.(type) {
-    case *opensearchapi.PartialBulkError:
-        log.Printf("%d items failed", len(e.FailedItems))
     case *opensearchapi.PartialSearchError:
         log.Printf("%d/%d shards failed", e.FailedShards, e.TotalShards)
     case *opensearchapi.MultiSearchItemError:
         log.Printf("%d sub-queries failed", len(e.Items))
-    case *opensearchapi.ShardFailureError:
-        log.Printf("%s: %d/%d shards failed", e.Operation, e.FailedShards, e.TotalShards)
     default:
         return err
     }