tel

package
v1.26.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 29, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source
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"
)
View Source
const MonitoringWriteScope = "https://www.googleapis.com/auth/monitoring.write"

MonitoringWriteScope is the OAuth scope the metric export needs.

Variables

View Source
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.

View Source
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.

View Source
var (
	NextBackoff = nextBackoff
	Jitter      = jitter
)

NextBackoff and Jitter expose the backoff helpers for tests.

View Source
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.

View Source
var IsPermanentExportError = isPermanentExportError

IsPermanentExportError exposes the export error classifier for tests.

View Source
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

func AuthTypeValue(iamAuthn bool) string

AuthTypeValue returns the auth type string based on whether IAM Authn is enabled.

func ClassifyDialError

func ClassifyDialError(err error) (string, string)

ClassifyDialError classifies an error during a connection attempt into connection_part and status labels.

func ConnectorTypeValue

func ConnectorTypeValue(userAgent string) string

ConnectorTypeValue returns the connector type based on the user agent.

func ConnectorVersionValue

func ConnectorVersionValue(userAgent, connectorVersion string) string

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

func DetectDatabaseEngineType(dbVersion string) (engine string)

DetectDatabaseEngineType detects the database engine type from a Cloud SQL DBVersion string. Any panic or error fails silently and returns UnknownValue.

func IPTypeValue

func IPTypeValue(connectionType string) string

IPTypeValue maps a dial connection type (e.g. cloudsql.PublicIP) to the instance_ip_type label value.

func IsValidComputePlatform

func IsValidComputePlatform(p string) bool

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

func SetWarnLoggerForTest(l *log.Logger) (restore func())

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.

func (NullMetricRecorder) Shutdown

Shutdown is a no-op.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL