Skip to content

Commit a466345

Browse files
authored
feat(bigtable): add sessionTracer for per-Session lifecycle + vRPC metrics (#20190)
## Summary Adds `sessionTracer`, the OTel metric-emitting companion to each Session. Standalone (no callers on `main` yet) so the tracer + tests can land ahead of the upcoming Session struct consumers. - **`InitializeSessionMetrics`** — `sync.Once`-guarded registration of four `Float64Histogram`s + the debug-tag counter. Safe to call multiple times with any provider (or `nil`); subsequent calls return the first-call error state. - **`sessionTracer`** — one instance per Session; holds only per-Session state (`startTime`, `opened` flag, `peerInfo`, `poolName`, `sessionType`). - **Four metrics registered:** | Metric | What it captures | |---|---| | `session.durations` | start → close latency | | `session.open_latencies` | start → OpenSession completion | | `session.uptime` | periodically-sampled age of active sessions | | `transport_latencies` | per-vRPC (e2e − backend) with fine-grain buckets | - `vrpcCloseState` label on `session.durations` mirrors Java's `SessionCloseVRpcState.find`: `{none, all_ok, all_error, some_ok}`. - `session_name` label is **pool-scoped (bounded cardinality)** — NOT the per-Session `logName` (unbounded). Documented in-file. - `recordTransportOverhead` gates on positive delta so a negative (e2e < backend) sample cannot corrupt the histogram. - Mutex discipline: `snapshot()` copies fields under lock; all allocating work (attribute builds, histogram `Record`) runs lock-free — debug/metrics MUST NOT block the hot path. ## Test plan - [x] `go build ./bigtable/...` - [x] `go test ./bigtable/internal/transport/ -run '^(TestSessionTracer|TestNewSessionTracer|TestVRpcCloseState|TestMsSince)' -count=1 -race` — 17 tests pass - [x] `gofmt -l bigtable/internal/transport/session_tracer*.go` — clean - [x] `go vet ./bigtable/internal/transport/` — clean Test coverage: - `InitializeSessionMetrics` idempotent + nil-provider safe. - `recordOpen` populates `session.open_latencies` with correct status label on OK vs error. - `recordClose` `vrpcs` label table (all four values). - `sampleUptime` emits for active session; skips zero startTime. - `recordTransportOverhead` positive-delta gate — zero and −3ms dropped, +5ms recorded, exact count == 1. - Nil-histograms no-op path (all recorders early-return without panic when Init was never called). - `newSessionTracer` defaults, `snapshot()` on nil vs set `peerInfo`, `vrpcCloseState` table, `msSince` sanity.
1 parent a9990b4 commit a466345

2 files changed

Lines changed: 695 additions & 0 deletions

File tree

Lines changed: 314 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,314 @@
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

Comments
 (0)