|
| 1 | +// Copyright 2026 Google LLC |
| 2 | +// |
| 3 | +// Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 | +// you may not use this file except in compliance with the License. |
| 5 | +// You may obtain a copy of the License at |
| 6 | +// |
| 7 | +// http://www.apache.org/licenses/LICENSE-2.0 |
| 8 | +// |
| 9 | +// Unless required by applicable law or agreed to in writing, software |
| 10 | +// distributed under the License is distributed on an "AS IS" BASIS, |
| 11 | +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 12 | +// See the License for the specific language governing permissions and |
| 13 | +// limitations under the License. |
| 14 | + |
| 15 | +package internal |
| 16 | + |
| 17 | +import ( |
| 18 | + "context" |
| 19 | + "fmt" |
| 20 | + "sync" |
| 21 | + "sync/atomic" |
| 22 | + "time" |
| 23 | + |
| 24 | + spb "cloud.google.com/go/bigtable/apiv2/bigtablepb" |
| 25 | + metricsinternal "cloud.google.com/go/bigtable/internal/metrics" |
| 26 | + "go.opentelemetry.io/otel/attribute" |
| 27 | + "go.opentelemetry.io/otel/metric" |
| 28 | + "google.golang.org/grpc/status" |
| 29 | +) |
| 30 | + |
| 31 | +// Session-scoped histograms. They are registered once at process startup via |
| 32 | +// InitializeSessionMetrics and shared across every session. |
| 33 | +var ( |
| 34 | + sessionDurations metric.Float64Histogram |
| 35 | + sessionOpenLatencies metric.Float64Histogram |
| 36 | + sessionUptime metric.Float64Histogram |
| 37 | + // transportLatencies is per-vRPC (not per-session-lifecycle), but shares |
| 38 | + // the same meter + registration path so all session-adjacent metrics |
| 39 | + // initialize together — matches java-bigtable's MetricRegistry layout. |
| 40 | + transportLatencies metric.Float64Histogram |
| 41 | + |
| 42 | + sessionMetricsOnce sync.Once |
| 43 | + sessionMetricsErr error |
| 44 | +) |
| 45 | + |
| 46 | +// FineGrainLatencyBounds matches java-bigtable's |
| 47 | +// AGGREGATION_WITH_MILLIS_HISTOGRAM: fine sub-ms + coarse tail. Shared |
| 48 | +// by transport_latencies and attempt_latencies2. |
| 49 | +var FineGrainLatencyBounds = []float64{ |
| 50 | + // Linear 0 → 3ms by 0.1ms (31 boundaries): fine-grained sub-ms. |
| 51 | + 0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, |
| 52 | + 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, |
| 53 | + 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 3.0, |
| 54 | + // Coarse 4ms → 80ms. |
| 55 | + 4.0, 5.0, 6.0, 8.0, 10.0, 13.0, 16.0, 20.0, 25.0, 30.0, 40.0, 50.0, 65.0, 80.0, |
| 56 | + // Coarse 100ms → 900ms. |
| 57 | + 100.0, 130.0, 160.0, 200.0, 250.0, 300.0, 400.0, 500.0, 650.0, 800.0, 900.0, |
| 58 | + // Coarse 1s → 50s. |
| 59 | + 1000.0, 2000.0, 3000.0, 4000.0, 5000.0, 6000.0, 10000.0, 20000.0, 50000.0, |
| 60 | + // Long tail: 100s → 5000s (~83 min). |
| 61 | + 100000.0, 200000.0, 500000.0, 1000000.0, 2000000.0, 5000000.0, |
| 62 | +} |
| 63 | + |
| 64 | +// InitializeSessionMetrics registers the session histograms against the given |
| 65 | +// meter provider. It runs at most once for the lifetime of the process; |
| 66 | +// subsequent calls (with any provider, including nil) return the result of |
| 67 | +// the first call. Passing nil on the first call leaves the histograms unset |
| 68 | +// and returns nil. |
| 69 | +func InitializeSessionMetrics(meterProvider metric.MeterProvider) error { |
| 70 | + sessionMetricsOnce.Do(func() { |
| 71 | + if meterProvider == nil { |
| 72 | + return |
| 73 | + } |
| 74 | + meter := meterProvider.Meter(clientMeterName) |
| 75 | + |
| 76 | + var err error |
| 77 | + if sessionDurations, err = meter.Float64Histogram( |
| 78 | + "session.durations", |
| 79 | + metric.WithDescription("Duration a session was alive (startTime → close)"), |
| 80 | + metric.WithUnit("ms"), |
| 81 | + ); err != nil { |
| 82 | + sessionMetricsErr = fmt.Errorf("create session.durations histogram: %w", err) |
| 83 | + return |
| 84 | + } |
| 85 | + if sessionOpenLatencies, err = meter.Float64Histogram( |
| 86 | + "session.open_latencies", |
| 87 | + metric.WithDescription("Latency to open a session"), |
| 88 | + metric.WithUnit("ms"), |
| 89 | + ); err != nil { |
| 90 | + sessionMetricsErr = fmt.Errorf("create session.open_latencies histogram: %w", err) |
| 91 | + return |
| 92 | + } |
| 93 | + if sessionUptime, err = meter.Float64Histogram( |
| 94 | + "session.uptime", |
| 95 | + metric.WithDescription("Age of currently-active sessions, sampled periodically"), |
| 96 | + metric.WithUnit("ms"), |
| 97 | + ); err != nil { |
| 98 | + sessionMetricsErr = fmt.Errorf("create session.uptime histogram: %w", err) |
| 99 | + return |
| 100 | + } |
| 101 | + if transportLatencies, err = meter.Float64Histogram( |
| 102 | + "transport_latencies", |
| 103 | + metric.WithDescription("The latency measured from e2e latencies minus node latencies."), |
| 104 | + metric.WithUnit("ms"), |
| 105 | + metric.WithExplicitBucketBoundaries(FineGrainLatencyBounds...), |
| 106 | + ); err != nil { |
| 107 | + sessionMetricsErr = fmt.Errorf("create transport_latencies histogram: %w", err) |
| 108 | + return |
| 109 | + } |
| 110 | + if err = registerDebugTagCounter(meter); err != nil { |
| 111 | + sessionMetricsErr = err |
| 112 | + return |
| 113 | + } |
| 114 | + }) |
| 115 | + return sessionMetricsErr |
| 116 | +} |
| 117 | + |
| 118 | +// sessionTracer tracks and records metrics for a Session's lifecycle and |
| 119 | +// individual operations. |
| 120 | +// |
| 121 | +// Field lifecycle (all fields are single-writer-at-construction except |
| 122 | +// `opened`; readers are lock-free): |
| 123 | +// |
| 124 | +// - startTime / sessionType — set once in newSessionTracer; immutable. |
| 125 | +// - poolName — set once via setPoolName, called from WithSessionPoolName |
| 126 | +// during NewSession before Session.Start spawns any goroutine. |
| 127 | +// Pool-scoped name matches java-bigtable's SessionPoolInfo name |
| 128 | +// semantics (bounded cardinality, one per pool per process) — NOT |
| 129 | +// the per-session logName (unbounded). |
| 130 | +// - opened — atomic.Bool flipped once by recordOpen; read by |
| 131 | +// recordClose / sampleUptime for the `ready` label. |
| 132 | +// |
| 133 | +// peerInfo is NOT stored on the tracer. It lives on Session as an |
| 134 | +// atomic.Pointer (single source of truth per SESSION_SPEC #3 — set |
| 135 | +// once, synchronously, in handleOpenSession) and is passed in at every |
| 136 | +// record*/sample* call. Duplicating it on the tracer would be shadow |
| 137 | +// state with a separate synchronization mechanism. |
| 138 | +// |
| 139 | +// startTime is the single wall-clock anchor for every emitted metric — |
| 140 | +// mirrors java-bigtable's SessionTracerImpl.uptime stopwatch, started |
| 141 | +// once in onStart() and driving session.open_latencies (start → open), |
| 142 | +// session.durations (start → close), and session.uptime (start → |
| 143 | +// sample). `opened` fills the same role as Java's State enum for the |
| 144 | +// ready label. |
| 145 | +type sessionTracer struct { |
| 146 | + startTime time.Time |
| 147 | + sessionType SessionType |
| 148 | + poolName string |
| 149 | + opened atomic.Bool |
| 150 | +} |
| 151 | + |
| 152 | +// newSessionTracer starts the "open" timer. |
| 153 | +func newSessionTracer(sessionType SessionType) *sessionTracer { |
| 154 | + return &sessionTracer{ |
| 155 | + startTime: time.Now(), |
| 156 | + sessionType: sessionType, |
| 157 | + } |
| 158 | +} |
| 159 | + |
| 160 | +// setPoolName stamps the pool-scoped name used for the session_name label |
| 161 | +// on every emitted metric. Called from WithSessionPoolName during |
| 162 | +// NewSession — before Session.Start spawns any goroutine, so no |
| 163 | +// synchronization is required. |
| 164 | +func (t *sessionTracer) setPoolName(name string) { |
| 165 | + t.poolName = name |
| 166 | +} |
| 167 | + |
| 168 | +// StartedAt returns the wall-clock time the session was constructed — |
| 169 | +// i.e. the anchor for every session-scoped metric. Immutable after |
| 170 | +// newSessionTracer, so read lock-free. |
| 171 | +func (t *sessionTracer) StartedAt() time.Time { |
| 172 | + return t.startTime |
| 173 | +} |
| 174 | + |
| 175 | +// peerInfoLabels derives the (transport_type, afe_location) metric-label |
| 176 | +// pair from a PeerInfo. Nil peerInfo yields ("unknown", "") — matching |
| 177 | +// pre-handshake state. Callers pass Session.PeerInfo() (an |
| 178 | +// atomic.Pointer load — SESSION_SPEC #3 makes the pointer set-once, so |
| 179 | +// the returned strings are stable for the session's lifetime). |
| 180 | +func peerInfoLabels(pi *spb.PeerInfo) (transportType, afeLocation string) { |
| 181 | + if pi == nil { |
| 182 | + return "unknown", "" |
| 183 | + } |
| 184 | + return metricsinternal.TransportTypeName(pi.GetTransportType()), pi.GetApplicationFrontendSubzone() |
| 185 | +} |
| 186 | + |
| 187 | +// recordOpen records the latency to open the session and flips the |
| 188 | +// `opened` flag so subsequent recordClose / sampleUptime label the |
| 189 | +// session as ready. peerInfo is the caller-supplied Session.PeerInfo() |
| 190 | +// at the moment of the OpenSession completion; may be nil if the |
| 191 | +// handshake failed before headers arrived. |
| 192 | +func (t *sessionTracer) recordOpen(ctx context.Context, peerInfo *spb.PeerInfo, err error) { |
| 193 | + t.opened.Store(true) |
| 194 | + |
| 195 | + if sessionOpenLatencies == nil { |
| 196 | + return |
| 197 | + } |
| 198 | + transportType, afeLocation := peerInfoLabels(peerInfo) |
| 199 | + statusStr := "OK" |
| 200 | + if err != nil { |
| 201 | + statusStr = status.Code(err).String() |
| 202 | + } |
| 203 | + sessionOpenLatencies.Record(ctx, msSince(t.startTime), metric.WithAttributes( |
| 204 | + attribute.String("transport_type", transportType), |
| 205 | + attribute.String("status", statusStr), |
| 206 | + attribute.String("session_type", t.sessionType.String()), |
| 207 | + attribute.String("afe_location", afeLocation), |
| 208 | + attribute.String("session_name", t.poolName), |
| 209 | + )) |
| 210 | +} |
| 211 | + |
| 212 | +// recordClose records the session's total elapsed time on close. |
| 213 | +// - peerInfo: Session.PeerInfo() at close time (may be nil if the |
| 214 | +// session died pre-handshake). |
| 215 | +// - closingReason: the terminal Session.CloseReason(), always |
| 216 | +// non-empty — Session synthesizes a fallback if the close path |
| 217 | +// forgot to set one, mirroring Java's SessionImpl.notifyTerminalClose |
| 218 | +// guard (SessionImpl.java:782-793). |
| 219 | +// - streamErr: the terminal stream error; nil means clean close ("OK"). |
| 220 | +// - hadOk / hadErr: whether the session served any OK / error vRPCs. |
| 221 | +// |
| 222 | +// Duration is always startTime→now — matches java-bigtable |
| 223 | +// SessionTracerImpl.onClose (`uptime.elapsed()`, where uptime is anchored |
| 224 | +// at onStart). The `ready` label distinguishes sessions that reached Ready |
| 225 | +// from those that died pre-open. |
| 226 | +func (t *sessionTracer) recordClose(ctx context.Context, peerInfo *spb.PeerInfo, closingReason string, streamErr error, hadOk, hadErr bool) { |
| 227 | + if sessionDurations == nil { |
| 228 | + return |
| 229 | + } |
| 230 | + var elapsed float64 |
| 231 | + if !t.startTime.IsZero() { |
| 232 | + elapsed = msSince(t.startTime) |
| 233 | + } |
| 234 | + transportType, afeLocation := peerInfoLabels(peerInfo) |
| 235 | + |
| 236 | + statusStr := "OK" |
| 237 | + if streamErr != nil { |
| 238 | + statusStr = status.Code(streamErr).String() |
| 239 | + } |
| 240 | + |
| 241 | + sessionDurations.Record(ctx, elapsed, metric.WithAttributes( |
| 242 | + attribute.String("transport_type", transportType), |
| 243 | + attribute.String("status", statusStr), |
| 244 | + attribute.String("session_type", t.sessionType.String()), |
| 245 | + attribute.String("closing_reason", closingReason), |
| 246 | + attribute.String("vrpcs", vrpcCloseState(hadOk, hadErr)), |
| 247 | + attribute.Bool("ready", t.opened.Load()), |
| 248 | + attribute.String("afe_location", afeLocation), |
| 249 | + attribute.String("session_name", t.poolName), |
| 250 | + )) |
| 251 | +} |
| 252 | + |
| 253 | +// vrpcCloseState mirrors java-bigtable's SessionCloseVRpcState.find — |
| 254 | +// (hadOk, hadErr) → {none, all_ok, all_error, some_ok}. The labels match |
| 255 | +// Java exactly so cross-language dashboards work. |
| 256 | +func vrpcCloseState(hadOk, hadErr bool) string { |
| 257 | + switch { |
| 258 | + case hadOk && hadErr: |
| 259 | + return "some_ok" |
| 260 | + case hadOk: |
| 261 | + return "all_ok" |
| 262 | + case hadErr: |
| 263 | + return "all_error" |
| 264 | + default: |
| 265 | + return "none" |
| 266 | + } |
| 267 | +} |
| 268 | + |
| 269 | +// sampleUptime records the current alive time (startTime → now) of a |
| 270 | +// still-active session into sessionUptime, with a `ready` label sourced |
| 271 | +// from the tracer's `opened` flag. Called periodically from the pool |
| 272 | +// heartbeat so the histogram represents the distribution of ages across |
| 273 | +// currently-active sessions. Java parity: SessionTracerImpl.recordAsyncMetrics |
| 274 | +// records uptime.elapsed() with `state == Ready` as the label. |
| 275 | +func (t *sessionTracer) sampleUptime(ctx context.Context, peerInfo *spb.PeerInfo) { |
| 276 | + if sessionUptime == nil { |
| 277 | + return |
| 278 | + } |
| 279 | + if t.startTime.IsZero() { |
| 280 | + return |
| 281 | + } |
| 282 | + transportType, afeLocation := peerInfoLabels(peerInfo) |
| 283 | + sessionUptime.Record(ctx, msSince(t.startTime), metric.WithAttributes( |
| 284 | + attribute.String("transport_type", transportType), |
| 285 | + attribute.String("session_type", t.sessionType.String()), |
| 286 | + attribute.Bool("ready", t.opened.Load()), |
| 287 | + attribute.String("afe_location", afeLocation), |
| 288 | + attribute.String("session_name", t.poolName), |
| 289 | + )) |
| 290 | +} |
| 291 | + |
| 292 | +func msSince(t time.Time) float64 { |
| 293 | + return float64(time.Since(t)) / float64(time.Millisecond) |
| 294 | +} |
| 295 | + |
| 296 | +// recordTransportOverhead emits a per-vRPC (stream − backend) sample into |
| 297 | +// the transport_latencies histogram. Java's ClientTransportLatency defines |
| 298 | +// this metric as "e2e latencies minus node latencies" — the wire + AFE |
| 299 | +// overhead outside server processing. Caller has already validated the |
| 300 | +// delta is positive; this is a no-op if the metric isn't registered. |
| 301 | +// Method is the vRPC method name (e.g. "ExecuteVRpc/Read"). |
| 302 | +func (t *sessionTracer) recordTransportOverhead(ctx context.Context, peerInfo *spb.PeerInfo, method string, overhead time.Duration) { |
| 303 | + if transportLatencies == nil || overhead <= 0 { |
| 304 | + return |
| 305 | + } |
| 306 | + transportType, afeLocation := peerInfoLabels(peerInfo) |
| 307 | + transportLatencies.Record(ctx, float64(overhead)/float64(time.Millisecond), metric.WithAttributes( |
| 308 | + attribute.String("transport_type", transportType), |
| 309 | + attribute.String("session_type", t.sessionType.String()), |
| 310 | + attribute.String("afe_location", afeLocation), |
| 311 | + attribute.String("session_name", t.poolName), |
| 312 | + attribute.String("method", method), |
| 313 | + )) |
| 314 | +} |
0 commit comments