You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- guides/metrics.md: replace nonexistent opensearchtransport.WithObserver()
with the Observer field on opensearch.Config
- guides/metrics.md: hoist safeFloat above the for loop so the polling
example is parseable Go
- guides/metrics.md: align aggregate tables (Request Counters, Pool State,
Lifecycle, Health Checks) to Field (Go name) + JSON (tag) layout
- guides/metrics.md: soften mechanism claims on IsOverloaded, RTTBucket,
EstLoad to describe field meaning rather than how they get set
- guides/error_handling.md, v5preview/opensearchapi/README.md: drop
*PartialBulkError and *ShardFailureError from MSearch switch examples;
fix the duplicate pre-existing example in the v5preview README
- guides/error_handling.md: qualify "folded into err" with the v4-vs-
v5preview default-mask caveat
- guides/error_handling.md: nil-check ErrorCause.Reason deref in v5preview
bulk example; switch the version-agnostic MSearch helper to log
item.Status (portable across v4 and v5preview)
- v5preview/opensearchapi/README.md: fix NewMuxRouter() to single-value
assignment (returns Router, not (Router, error))
- v5preview/opensearchapi/MIGRATING.md: drop the forward-compatible
`replace` section -- the cited path has no go.mod and the directive
cannot resolve
- UPGRADING.md: reword the partial-failure intro so the recommended
type-switch pattern is the only advertised entry point (drops the
in-tension `errors.As` mention)
- CHANGELOG.md: add (opensearch-project#812) backlink to the metrics-guide bullet
Signed-off-by: Sean Chittenden <sean.chittenden@crowdstrike.com>
Copy file name to clipboardExpand all lines: CHANGELOG.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,7 +16,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
16
16
- Add `OPENSEARCH_GO_SHARD_COST` environment variable and `WithShardCosts()` router option with `r:base`/`r:amplify`/`r:exponent` curve keys and static cost overrides
17
17
- Add `ShardCostConfig` field to `Config` struct for programmatic shard cost override passthrough
18
18
- Add `OPENSEARCH_GO_ROUTER` environment variable to enable the DefaultRouter without code changes; set to `true` to opt in (off by default in v4, on by default in v5, removed in v6) ([#815](https://github.com/opensearch-project/opensearch-go/pull/815))
- Add `InsecureSkipVerify` config option to disable TLS certificate verification without constructing a custom `http.Transport`, preserving `DefaultTransport` connection pooling, HTTP/2, and timeout defaults ([#786](https://github.com/opensearch-project/opensearch-go/issues/786))
21
21
- Add `DisableResponseBuffering` config option to skip eager `io.ReadAll` buffering of response bodies in `Perform()`, reducing per-request allocations and TTFB for proxy and streaming use cases ([#786](https://github.com/opensearch-project/opensearch-go/issues/786))
22
22
- Add per-attempt `RequestTimeout` to bound individual HTTP round-trips, preventing indefinite hangs on stalled connections ([#786](https://github.com/opensearch-project/opensearch-go/issues/786))
@@ -102,7 +102,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
102
102
-`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)
103
103
- Helper functions: `IsPartialFailure`, `ToleratePartialFailures`, `RequireSuccessRate` for threshold-based error tolerance
- 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
105
+
- 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
106
106
-`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)
107
107
-`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)
108
108
- Both `(resp, error)` are non-nil on partial failure -- response is fully populated
Copy file name to clipboardExpand all lines: UPGRADING.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -34,7 +34,7 @@
34
34
35
35
### Partial Failure Errors (Config.Errors)
36
36
37
-
Version 5.0.0 introduces typed partial-failure errors and a per-category bitmask that controls which categories surface as Go errors. OpenSearch returns HTTP 200 for many operations that partially succeed (bulk item failures, shard failures on search, replica failures on writes). The new model turns those partial failures into typed errors callers can match on with `errors.As`.
37
+
Version 5.0.0 introduces typed partial-failure errors and a per-category bitmask that controls which categories surface as Go errors. OpenSearch returns HTTP 200 for many operations that partially succeed (bulk item failures, shard failures on search, replica failures on writes). The new model turns those partial failures into typed errors that callers can dispatch on; idiomatic partial error handling is shown below.
// resp is fully populated; partial failures (if any) are folded into err.
226
+
// resp is fully populated; partial failures (if any) are folded into err
227
+
// when the wrapper bits are unmasked (the v5preview default, or v4 with
228
+
// Config.Errors: errmask.New()).
223
229
```
224
230
225
231
**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:
|`MCSR`|`mcsr`|`*int`| Adaptive `max_concurrent_shard_requests` value (nil when disabled) |
104
104
105
105
### Node Metadata
@@ -169,6 +169,13 @@ Each index with an active routing slot produces an entry in `Router.Indexes`.
169
169
Poll metrics on a timer for logging or export to an external monitoring system.
170
170
171
171
```go
172
+
funcsafeFloat(f *float64) float64 {
173
+
if f == nil {
174
+
return0
175
+
}
176
+
return *f
177
+
}
178
+
172
179
ticker:= time.NewTicker(30 * time.Second)
173
180
defer ticker.Stop()
174
181
@@ -207,13 +214,6 @@ for range ticker.C {
207
214
}
208
215
}
209
216
}
210
-
211
-
funcsafeFloat(f *float64) float64 {
212
-
if f == nil {
213
-
return0
214
-
}
215
-
return *f
216
-
}
217
217
```
218
218
219
219
## JSON Export
@@ -249,6 +249,6 @@ The metrics API is pull-based: call `client.Metrics()` inside your collector's `
249
249
250
250
## Observer API
251
251
252
-
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.
252
+
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.
253
253
254
254
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.
The package qualifier (`opensearchapi.X`) does not change. When v5 ships, the only edit per file is dropping `/v4/v5preview` from the import path and replacing `v4` with `v5`.
0 commit comments