Documentation
¶
Index ¶
- Constants
- Variables
- func AuthTypeValue(iamAuthn bool) string
- func ClassifyDialError(err error) (string, string)
- func ConnectorTypeValue(userAgent string) string
- func ConnectorVersionValue(userAgent, connectorVersion string) string
- func DetectClientRegion() (region string)
- func DetectComputePlatform() (platform string)
- func DetectDatabaseEngineType(dbVersion string) (engine string)
- func IPTypeValue(connectionType string) string
- func IsValidComputePlatform(p string) bool
- func ResetPanicWarnOnceForTest()
- func SetWarnLoggerForTest(l *log.Logger) (restore func())
- func ValidComputePlatformsForTest() []string
- type Attributes
- type Config
- type MetricRecorder
- type NullMetricRecorder
- func (n NullMetricRecorder) DatabaseEngine() string
- func (n NullMetricRecorder) RecordClosedConnection(context.Context, Attributes)
- func (n NullMetricRecorder) RecordClosedConnectionCount(context.Context, Attributes)
- func (n NullMetricRecorder) RecordConnectLatencies(context.Context, Attributes, int64)
- func (n NullMetricRecorder) RecordConnectionDuration(context.Context, Attributes, float64)
- func (n NullMetricRecorder) RecordOpenConnection(context.Context, Attributes)
- func (n NullMetricRecorder) RecordOpenConnectionCount(context.Context, Attributes)
- func (n NullMetricRecorder) Shutdown(context.Context) error
Constants ¶
const ( // ResourceContainer is the identifier of the GCP project associated with this CSQL resource. ResourceContainer = "resource_container" // ResourceID is the Cloud SQL instance identifier in the format of [project_name:instance_name]. ResourceID = "resource_id" // ClientUID is a unique identifier generated for each Dialer instance. ClientUID = "client_uid" // ApplicationName is the application name provided by the user; empty when not set. ApplicationName = "application_name" // Region is the Cloud SQL Instance's location e.g. us-central1. Region = "region" // ClientRegion is the region from which the client is connecting, unknown if not on GCP ClientRegion = "client_region" // ComputePlatform is the platform on which the client is running, e.g. GCE, GKE, etc. ComputePlatform = "compute_platform" // ConnectorType is the Cloud SQL Connector type. "go" in this case. ConnectorType = "connector_type" // ConnectorVersion is the Cloud SQL Connector version. ConnectorVersion = "connector_version" // DatabaseEngineType is the database engine type [MySQL, PostgreSQL, SQL Server]. DatabaseEngineType = "database_engine_type" // ConnectSuccess indicates the dial attempt succeeded. ConnectSuccess = "success" // ConnectError indicates the dial attempt errors out. ConnectError = "error" // UnknownValue is used for any label whose value could not be determined. // All enum-like label values are lowercase snake_case, matching the // published metric descriptors and the AlloyDB connector. UnknownValue = "unknown" // ConnectorTypeGo is the connector_type value for the Go connector. ConnectorTypeGo = "go" // ConnectorTypeAuthProxy is the connector_type value for the Cloud SQL // Auth Proxy, which embeds the Go connector. ConnectorTypeAuthProxy = "auth_proxy" // PlatformGKE is the compute_platform value for Google Kubernetes Engine. PlatformGKE = "gke" // PlatformCloudRun is the compute_platform value for Cloud Run. PlatformCloudRun = "cloud_run" // PlatformAppEngine is the compute_platform value for App Engine. PlatformAppEngine = "app_engine" // PlatformCloudFunctions is the compute_platform value for Cloud Functions. PlatformCloudFunctions = "cloud_functions" // PlatformGCE is the compute_platform value for Compute Engine. PlatformGCE = "gce" // PlatformAIStudio is the compute_platform value for applications // deployed by Google AI Studio. It cannot be auto-detected and must be // set explicitly by the embedding client (e.g. the Auth Proxy). PlatformAIStudio = "ai_studio" // EngineMySQL is the database_engine_type value for MySQL. EngineMySQL = "mysql" // EnginePostgreSQL is the database_engine_type value for PostgreSQL. EnginePostgreSQL = "postgresql" // EngineSQLServer is the database_engine_type value for SQL Server. EngineSQLServer = "sqlserver" // IPTypePublic is the instance_ip_type value for public IP connections. IPTypePublic = "public" // IPTypePrivate is the instance_ip_type value for private IP (PSA) // connections. IPTypePrivate = "private" // IPTypePSC is the instance_ip_type value for Private Service Connect // connections. IPTypePSC = "psc" // IPTypeAuto is the instance_ip_type value when the connection type was // requested as AutoIP (public if available, otherwise private). IPTypeAuto = "auto" // IPTypeSQLData is the instance_ip_type value for connections through the // SQL Data endpoint. IPTypeSQLData = "sql_data" )
const MonitoringWriteScope = "https://www.googleapis.com/auth/monitoring.write"
MonitoringWriteScope is the OAuth scope the metric export needs.
Variables ¶
var ( // ConnectLatencyBucketsMs: 20 buckets from 1 ms to 5 minutes (each ~1.94x // the previous one), covering local dials through slow refreshes and // long driver timeouts. ConnectLatencyBucketsMs = exponentialBuckets(1, 300_000, 20) // ConnectionDurationBucketsS: 50 buckets from 0.1 s to 24 h (each ~1.32x // the previous one). Observed mean connection time is ~23 s, which this // spacing resolves to within a ~6 s wide bucket, while still separating // pooled connections held for hours. ConnectionDurationBucketsS = exponentialBuckets(0.1, 86_400, 50) )
Histogram bucket boundaries. The OpenTelemetry defaults (0, 5, 10, 25, ..., 10000) are tuned for request latencies in milliseconds; for connection durations in seconds they put everything under 5 s in one bucket and overflow at ~2.8 h, which pooled connections routinely exceed.
Boundaries are exponentially spaced: each is a constant multiple of the previous one, so percentile estimates have the same relative error across the whole range.
var ( PermanentExportErrorInitialBackoff = 10 * time.Minute PermanentExportErrorMaxBackoff = time.Hour TransientExportErrorInitialBackoff = 2 * time.Minute TransientExportErrorMaxBackoff = 16 * time.Minute )
Backoff applied after a failed export. Export is suspended after a failure and the suspension doubles on each consecutive failure up to a cap; a successful export resets it. There are two tiers:
- Permanent errors (missing IAM permission, invalid credentials, disabled API, deleted project) will not resolve on their own, so they back off from PermanentExportErrorInitialBackoff up to PermanentExportErrorMaxBackoff. A client missing roles/monitoring.metricWriter settles at one attempt per hour while an IAM fix is still picked up within an hour without a restart.
- Transient errors (Monitoring API unavailable, timeouts, quota) usually clear on their own, so they back off from TransientExportErrorInitialBackoff up to TransientExportErrorMaxBackoff. This sheds load from the Monitoring API during an outage (a fleet of connectors retrying at full rate would otherwise hold it at 100% of normal load while it recovers) while bounding the gap in a customer's dashboard after recovery to roughly the max backoff.
A small jitter is applied to every suspension so that clients that failed together do not all retry on the same tick. Exposed as vars to facilitate testing.
var ( NextBackoff = nextBackoff Jitter = jitter )
NextBackoff and Jitter expose the backoff helpers for tests.
var DefaultExportInterval = 60 * time.Second
DefaultExportInterval is the interval that the metric exporter runs. It should always be 60s. This value is exposed as a var to faciliate testing.
var IsPermanentExportError = isPermanentExportError
IsPermanentExportError exposes the export error classifier for tests.
var RecoveredPanics atomic.Int64
RecoveredPanics counts panics recovered on the metrics record path across the process. It is exported for tests and diagnostics; a non-zero value indicates a bug in the metrics pipeline that should be reported.
Functions ¶
func AuthTypeValue ¶
AuthTypeValue returns the auth type string based on whether IAM Authn is enabled.
func ClassifyDialError ¶
ClassifyDialError classifies an error during a connection attempt into connection_part and status labels.
func ConnectorTypeValue ¶
ConnectorTypeValue returns the connector type based on the user agent.
func ConnectorVersionValue ¶
ConnectorVersionValue returns the connector_version label: the version of the product the user runs. For the Auth Proxy that is the proxy's own version, taken from its "cloud-sql-proxy/<version>" user-agent token, so that a proxy fleet can be broken down by proxy release; otherwise it is the Go connector's version.
func DetectClientRegion ¶
func DetectClientRegion() (region string)
DetectClientRegion returns the client region from GCP metadata if running on GCE/GKE/Cloud Run. Any panic or error fails silently and returns UnknownValue.
func DetectComputePlatform ¶
func DetectComputePlatform() (platform string)
DetectComputePlatform detects the GCP compute platform environment. Any panic or error fails silently and returns UnknownValue.
func DetectDatabaseEngineType ¶
DetectDatabaseEngineType detects the database engine type from a Cloud SQL DBVersion string. Any panic or error fails silently and returns UnknownValue.
func IPTypeValue ¶
IPTypeValue maps a dial connection type (e.g. cloudsql.PublicIP) to the instance_ip_type label value.
func IsValidComputePlatform ¶
IsValidComputePlatform reports whether p is an allowed compute_platform label value.
func ResetPanicWarnOnceForTest ¶
func ResetPanicWarnOnceForTest()
ResetPanicWarnOnceForTest re-arms the process-wide panic warning.
func SetWarnLoggerForTest ¶
SetWarnLoggerForTest redirects the once-per-process permanent-error warning to l and resets the once guard. It returns a function that restores the previous state.
func ValidComputePlatformsForTest ¶
func ValidComputePlatformsForTest() []string
ValidComputePlatformsForTest returns the allowed compute_platform values, excluding UnknownValue (which only auto-detection produces), so the root package can check that its public list stays in sync.
Types ¶
type Attributes ¶
type Attributes struct {
// IAMAuthN specifies whether IAM authentication is enabled (auth_type).
IAMAuthN bool
// DialStatus specifies the result of the dial attempt (status on
// closed_connection_count), one of [success, error].
DialStatus string
// IPType is the connection type requested or, once known, the IP type
// actually used (instance_ip_type), one of [public, private, psc,
// sql_data, auto, unknown].
IPType string
// ConnectionPart specifies which part of the connection errors out, one of [client_to_proxy, proxy_to_server].
ConnectionPart string
// AttemptStatus specifies the detailed status of the dial attempt.
AttemptStatus string
}
Attributes holds the per-attempt metadata attached to a metric. Every field here is emitted as a metric label by at least one Record method.
type Config ¶
type Config struct {
// Enabled specifies whether the metrics should be enabled.
Enabled bool
// Version is the version of the cloudsqlconn.Dialer.
Version string
// Project id
ResourceContainer string
// The Cloud SQL instance identifier in the format of [project_name:instance_name]
ResourceID string
// A unique identifier generated for each Dialer instance
ClientUID string
// The application name provided by the user or defaulted by the connector
ApplicationName string
// Cloud SQL Instance's location e.g. us-central1
Region string
// ClientRegion is the region from which the client is connecting, unknown if not on GCP
ClientRegion string
// ComputePlatform is the platform on which the client is running, e.g. GCE, GKE, etc.
ComputePlatform string
// Cloud SQL Connector type. "go" in this case.
ConnectorType string
// Cloud SQL Connector version
ConnectorVersion string
// Database engine type [MySQL, PostgreSQL, SQL Server].
DatabaseEngineType string
// Principal is the identity (e.g. service account email) the connector
// authenticates with, when it can be determined. Used only to make
// permission errors actionable. May be empty.
Principal string
// DisableHint tells the user how to turn built-in metrics off in the
// client that embeds this connector (Go API vs. Auth Proxy flag). Used
// only in error messages. May be empty.
DisableHint string
}
Config holds all the necessary information to configure a MetricRecorder.
type MetricRecorder ¶
type MetricRecorder interface {
RecordOpenConnection(context.Context, Attributes)
RecordClosedConnection(context.Context, Attributes)
RecordClosedConnectionCount(context.Context, Attributes)
RecordConnectLatencies(context.Context, Attributes, int64)
RecordConnectionDuration(context.Context, Attributes, float64)
RecordOpenConnectionCount(context.Context, Attributes)
DatabaseEngine() string
// Shutdown flushes any buffered metrics and stops the periodic export.
// It must be called when the recorder is no longer needed, otherwise
// metrics recorded since the last export are lost.
Shutdown(context.Context) error
}
MetricRecorder defines the interface for recording metrics related to the internal operations of cloudsqlconn.Dialer.
func NewMetricRecorder ¶
func NewMetricRecorder(ctx context.Context, l debug.ContextLogger, cl *monitoring.MetricClient, cfg Config) MetricRecorder
NewMetricRecorder creates a MetricRecorder. When the configuration is not enabled, a null recorder is returned instead.
func NewPanickingRecorderForTest ¶
func NewPanickingRecorderForTest(l debug.ContextLogger) MetricRecorder
NewPanickingRecorderForTest returns a metricRecorder whose instruments are nil, so every Record* call would panic without the recoverPanic guard.
type NullMetricRecorder ¶
type NullMetricRecorder struct{}
NullMetricRecorder implements the MetricRecorder interface with no-ops. It is useful for disabling the built-in metrics.
func (NullMetricRecorder) DatabaseEngine ¶
func (n NullMetricRecorder) DatabaseEngine() string
DatabaseEngine returns an empty string for the null recorder.
func (NullMetricRecorder) RecordClosedConnection ¶
func (n NullMetricRecorder) RecordClosedConnection(context.Context, Attributes)
RecordClosedConnection is a no-op.
func (NullMetricRecorder) RecordClosedConnectionCount ¶
func (n NullMetricRecorder) RecordClosedConnectionCount(context.Context, Attributes)
RecordClosedConnectionCount is a no-op.
func (NullMetricRecorder) RecordConnectLatencies ¶
func (n NullMetricRecorder) RecordConnectLatencies(context.Context, Attributes, int64)
RecordConnectLatencies is a no-op.
func (NullMetricRecorder) RecordConnectionDuration ¶
func (n NullMetricRecorder) RecordConnectionDuration(context.Context, Attributes, float64)
RecordConnectionDuration is a no-op.
func (NullMetricRecorder) RecordOpenConnection ¶
func (n NullMetricRecorder) RecordOpenConnection(context.Context, Attributes)
RecordOpenConnection is a no-op.
func (NullMetricRecorder) RecordOpenConnectionCount ¶
func (n NullMetricRecorder) RecordOpenConnectionCount(context.Context, Attributes)
RecordOpenConnectionCount is a no-op.