[panavenue]

Summary

Upgrades cloud.google.com/go/cloudsqlconn to v1.26.0, which exports built-in client metrics to Cloud Monitoring by default (BETA) under cloudsql.googleapis.com/client/connector/* using the cloudsql.googleapis.com/InstanceClient monitored resource, and exposes the CLI flags and environment variables to configure or disable them.

New Flags & Environment Variables

• --enable-builtin-metrics (CSQL_PROXY_ENABLE_BUILTIN_METRICS, default true):
  • Pass --enable-builtin-metrics=false (or CSQL_PROXY_ENABLE_BUILTIN_METRICS=false) to disable built-in client metrics.
  • When unset, the connector's own default applies (enabled in googleapis.com, disabled in non-default Cloud universes unless --enable-builtin-metrics=true is explicitly passed).
  • Independent of --telemetry-project / --disable-metrics, which control the Proxy's OpenCensus metrics and traces.
• --compute-platform (CSQL_PROXY_COMPUTE_PLATFORM):
  • Overrides the auto-detected compute_platform label (e.g. ai_studio). Validated at startup with cloudsqlconn.ParseComputePlatform; help text is populated from cloudsqlconn.ComputePlatforms().
• --application-name (CSQL_PROXY_APPLICATION_NAME):
  • Sets the optional application_name label to identify an application across its instances (empty by default).

Service Account Impersonation Scope & Shutdown Ordering

• Impersonation scope: When --impersonate-service-account is used and built-in metrics are enabled, the Proxy automatically requests https://www.googleapis.com/auth/monitoring.write alongside sqlservice.admin on the impersonated token source so that metric exports succeed.
• Graceful shutdown order (Client.Close()): Moved c.dialer.Close() to run after --max-sigterm-delay connection draining (WaitOnClose) and after closing instance socket listeners (m.Close() / FUSE unmount). This ensures local TCP/Unix sockets release immediately without waiting on the final Cloud Monitoring flush RPC, and ensures in-flight connections draining during SIGTERM remain open and are included in the final metrics flush.

⚠️ Built-in Client Metrics Enabled by Default (BETA)

• Fail-open & non-blocking: Metrics collection never blocks or breaks database connectivity.
• IAM Permissions: Metrics are written to the Cloud SQL instance's project using the Proxy's existing credentials, which need roles/monitoring.metricWriter on that project. If missing, the Proxy logs one warning per process explaining what to grant (or how to disable) and backs off exponentially.
• How to disable:

  ./cloud-sql-proxy --enable-builtin-metrics=false <INSTANCE_CONNECTION_NAME>

Performance & E2E Verification

Benchmarked a Go pgx/v5 client application connecting through cloud-sql-proxy --auto-iam-authn to a live Cloud SQL for PostgreSQL 18 instance (us-west1) across 2 interleaved rounds comparing main (v2.26.3), PR (--enable-builtin-metrics=false), and PR (metrics enabled, --compute-platform=ai_studio --application-name=proxy-perf-app):

1. Warmup: 3 unpooled connects + SELECT 1 + close (caches ephemeral TLS cert and IAM DB authn token).
2. Unpooled Connect + Query: 30 sequential fresh connects + SELECT 1 + close per round (exercises Proxy accept, cloudsqlconn dial + metric recording, TLS handshake, Postgres startup, query, and close).
3. Pooled Concurrent 4 KB Queries: 8 concurrent workers × 50 queries = 400 SELECT repeat('x', 4096) queries over an 8-connection database/sql pool per round (exercises steady-state Proxy bidirectional io.Copy throughput).
4. Live Footprint & Lifecycle: /debug/pprof/goroutine, /debug/pprof/heap?gc=1 (Alloc), OS VmRSS, startup-to-ready time, and SIGTERM-to-exit time.

Variant	Binary (stripped / full)	Unpooled Connect + SELECT 1 (p50 / p90 / p99)	Pooled 4 KB QPS (p50 / p99)	Proxy Goroutines	Go Heap after GC / OS RSS	Startup / SIGTERM Exit
main (v2.26.3)	25 MB / 35 MB	70.8–75.6 ms / 80.2–87.5 ms / 82.1–101.3 ms	5,988–8,167 qps (0.9–1.0 ms / 4.1–7.7 ms)	14	3.08–3.09 MB / 39.0–41.3 MB	175–343 ms / 5 ms
PR (--enable-builtin-metrics=false)	26 MB / 37 MB	73.7–74.3 ms / 79.2–82.1 ms / 82.2–92.3 ms	7,582–7,747 qps (0.9 ms / 4.3–5.0 ms)	14 (+0)	3.07–3.11 MB / 40.8–42.3 MB	231–286 ms / 4–5 ms
PR (metrics ON, default)	26 MB / 37 MB	71.0–73.3 ms / 78.2–78.5 ms / 85.1–85.5 ms	7,000–8,026 qps (0.9–1.0 ms / 4.3–5.1 ms)	24 (+10)	3.22–3.23 MB / 41.2–42.8 MB	174–231 ms / 118–119 ms

• Zero latency or throughput regression: Unpooled connect latency (~71–75 ms p50) and pooled 4 KB query throughput (~7,000–8,000 qps, ~0.9 ms p50) are identical within network variance across main, metrics off, and metrics on.
• Minimal footprint overhead: When disabled (--enable-builtin-metrics=false), 0 extra goroutines and 0 heap overhead vs main. When enabled, +10 background OTel/Cloud Monitoring exporter goroutines, +0.14 MB Go heap after GC, and ~118 ms on SIGTERM for the final Cloud Monitoring flush RPC (after local listeners have already closed).
• Cloud Monitoring E2E verified: With metrics enabled, queried cloudsql.googleapis.com/client/connector/* by client_uid and confirmed exact counts of 41 (3 warmup + 30 unpooled + 8 pooled) across open_connection_count, connect_latencies, closed_connection_count, and connection_durations, and 0 open_connections after exit, with connector_type=auth_proxy, compute_platform=ai_studio, application_name=proxy-perf-app, database_engine_type=postgresql, instance_auth_type=iam, instance_ip_type=public. With --enable-builtin-metrics=false, confirmed 0 time series exported.