database_observability

package
v1.16.1 Latest Latest
Warning

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

 Go to latest Published: May 5, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

README

Please refer to reference documentation to get started setting up Database Observability with Grafana Cloud.

Documentation

Index

Constants

View Source 
const (
	ProviderNameLabel    = "provider_name"
	ProviderRegionLabel  = "provider_region"
	ProviderAccountLabel = "provider_account"
)
View Source 
const ConnectionCheckInterval = 60 * time.Second

ConnectionCheckInterval is how often the connection_info collector pings the DB to verify connectivity.

View Source 
const ConnectionChecksThreshold = 3

ConnectionChecksThreshold is the number of consecutive failed pings before unregistering the metric, and the number of consecutive successful pings before re-registering it after a disconnect.

View Source 
const JobName = "integrations/db-o11y"

Variables

View Source 
var (
	RdsRegex             = regexp.MustCompile(`(?P<identifier>[^\.]+)\.([^\.]+)\.(?P<region>[^\.]+)\.rds\.amazonaws\.com`)
	AzureMySQLRegex      = regexp.MustCompile(`(?P<identifier>[^\.]+)\.(?:privatelink\.)?mysql\.database\.azure\.com`)
	AzurePostgreSQLRegex = regexp.MustCompile(`(?P<identifier>[^\.]+)\.(?:privatelink\.)?postgres\.database\.azure\.com`)
)
View Source 
var ExplainReservedWordDenyList = map[string]ExplainReservedWordMetadata{

	"INSERT": {},
	"UPDATE": {
		ExemptionPrefixes: &[]string{"FOR"},
	},
	"DELETE":  {},
	"REPLACE": {},
	"MERGE":   {},
	"UPSERT":  {},

	"CREATE":   {},
	"ALTER":    {},
	"DROP":     {},
	"RENAME":   {},
	"TRUNCATE": {},

	"BEGIN":       {},
	"COMMIT":      {},
	"ROLLBACK":    {},
	"SAVEPOINT":   {},
	"TRANSACTION": {},

	"USE":      {},
	"DATABASE": {},
	"SCHEMA":   {},

	"REINDEX":  {},
	"ANALYZE":  {},
	"OPTIMIZE": {},

	"GRANT":  {},
	"REVOKE": {},

	"LOAD":          {},
	"DELAYED":       {},
	"IGNORE":        {},
	"LOW_PRIORITY":  {},
	"HIGH_PRIORITY": {},
	"QUICK":         {},

	"COPY":       {},
	"VACUUM":     {},
	"CLUSTER":    {},
	"LISTEN":     {},
	"NOTIFY":     {},
	"DISCARD":    {},
	"PREPARE":    {},
	"EXECUTE":    {},
	"DEALLOCATE": {},
	"RESET":      {},
	"SET":        {},
	"UNLISTEN":   {},
	"DECLARE":    {},
	"CLOSE":      {},

	"EXPLAIN": {},
}

ExplainReservedWordDenyList contains SQL reserved words that indicate write operations to the database. These are primarily DML (Data Manipulation Language) and DDL (Data Definition Language) commands that modify database state. This was extracted from the MySQL and PostgreSQL documentation by Claude Sonnet 4 on Oct 28, 2025 and audited by @rgeyer and others in the dbo11y team.

Functions

func BuildExclusionClause added in v1.13.0 

func BuildExclusionClause(items []string) string

BuildExclusionClause builds a SQL IN clause from a list of items.

func BuildLokiEntry added in v1.11.0 

func BuildLokiEntry(level logging.Level, op, line string) loki.Entry

func BuildLokiEntryWithTimestamp added in v1.11.0 

func BuildLokiEntryWithTimestamp(level logging.Level, op, line string, timestamp int64) loki.Entry

func ContainsReservedKeywords added in v1.12.0 

func ContainsReservedKeywords(query string, reservedWords map[string]ExplainReservedWordMetadata, dbms sqllexer.DBMSType) (bool, error)

ContainsReservedKeywords checks if the SQL query contains any reserved keywords that indicate write operations, excluding those in string literals or comments

func DefaultExcludedDatabases added in v1.16.0 

func DefaultExcludedDatabases() []string

func DefaultExcludedSchemas added in v1.16.0 

func DefaultExcludedSchemas() []string

func DefaultExcludedUsers added in v1.16.0 

func DefaultExcludedUsers() []string

func EscapeSQLString added in v1.13.0 

func EscapeSQLString(s string) string

EscapeSQLString escapes single quotes by doubling them to prevent SQL injection.

func GetRelabelingRules added in v1.11.0 

func GetRelabelingRules(serverID string, cp *CloudProvider) []*relabel.Config

func RedactSql added in v1.12.0 

func RedactSql(sql string) string

RedactSql obfuscates a SQL query by replacing literals with ? placeholders

func RunConnectionInfoMonitor added in v1.15.0 

func RunConnectionInfoMonitor(ctx context.Context, db *sql.DB, registry *prometheus.Registry, infoMetric *prometheus.GaugeVec, labelValues []string, onStopped func(), config *ConnectionInfoMonitorConfig) (stop func())

RunConnectionInfoMonitor starts a goroutine that pings db every ConnectionCheckInterval. After ConnectionChecksThreshold consecutive ping failures it unregisters infoMetric from registry. After ConnectionChecksThreshold consecutive ping successes (when the metric is unregistered) it re-registers infoMetric and sets it to 1 with the given labelValues. The goroutine runs until the returned stop function is called. onStopped is called when the goroutine exits. The returned stop function cancels the internal context and waits for the goroutine to exit before returning. labelValues must contain exactly 6 values in order: provider_name, provider_region, provider_account, db_instance_identifier, engine, engine_version. If config is non-nil, its CheckInterval and ChecksThreshold override the default constants (used for testing).

Types

type AWSCloudProviderInfo added in v1.11.0 

type AWSCloudProviderInfo struct {
	ARN arn.ARN
}

type AzureCloudProviderInfo added in v1.13.0 

type AzureCloudProviderInfo struct {
	SubscriptionID string
	ResourceGroup  string
	ServerName     string
}

type CloudProvider added in v1.11.0 

type CloudProvider struct {
	AWS   *AWSCloudProviderInfo
	Azure *AzureCloudProviderInfo
	GCP   *GCPCloudProviderInfo
}

type ConnectionInfoMonitorConfig added in v1.15.0 

type ConnectionInfoMonitorConfig struct {
	CheckInterval   time.Duration
	ChecksThreshold int
}

ConnectionInfoMonitorConfig optionally overrides the default check interval and threshold. Used by tests to run the monitor with shorter intervals. If nil, defaults are used.

type ExplainPlanAccessType added in v1.11.0 

type ExplainPlanAccessType string
const (
	ExplainPlanAccessTypeAll   ExplainPlanAccessType = "all"
	ExplainPlanAccessTypeIndex ExplainPlanAccessType = "index"
	ExplainPlanAccessTypeRange ExplainPlanAccessType = "range"
	ExplainPlanAccessTypeRef   ExplainPlanAccessType = "ref"
	ExplainPlanAccessTypeEqRef ExplainPlanAccessType = "eq_ref"
)

type ExplainPlanJoinAlgorithm added in v1.11.0 

type ExplainPlanJoinAlgorithm string
const (
	ExplainPlanJoinAlgorithmHash       ExplainPlanJoinAlgorithm = "hash"
	ExplainPlanJoinAlgorithmMerge      ExplainPlanJoinAlgorithm = "merge"
	ExplainPlanJoinAlgorithmNestedLoop ExplainPlanJoinAlgorithm = "nested_loop"
)

type ExplainPlanMetadataInfo added in v1.11.0 

type ExplainPlanMetadataInfo struct {
	DatabaseEngine  string `json:"databaseEngine"`
	DatabaseVersion string `json:"databaseVersion"`
	QueryIdentifier string `json:"queryIdentifier"`
	GeneratedAt     string `json:"generatedAt"`

	ProcessingResult       ExplainProcessingResult `json:"processingResult"`
	ProcessingResultReason string                  `json:"processingResultReason"`
}

type ExplainPlanNode added in v1.11.0 

type ExplainPlanNode struct {
	Operation ExplainPlanOutputOperation `json:"operation"`
	Details   ExplainPlanNodeDetails     `json:"details"`
	Children  []ExplainPlanNode          `json:"children,omitempty"`
}

type ExplainPlanNodeDetails added in v1.11.0 

type ExplainPlanNodeDetails struct {
	EstimatedRows int64                     `json:"estimatedRows"`
	EstimatedCost *float64                  `json:"estimatedCost,omitempty"`
	TableName     *string                   `json:"tableName,omitempty"`
	Alias         *string                   `json:"alias,omitempty"`
	AccessType    *ExplainPlanAccessType    `json:"accessType,omitempty"`
	KeyUsed       *string                   `json:"keyUsed,omitempty"`
	JoinType      *string                   `json:"joinType,omitempty"`
	JoinAlgorithm *ExplainPlanJoinAlgorithm `json:"joinAlgorithm,omitempty"`
	Condition     *string                   `json:"condition,omitempty"`
	GroupByKeys   []string                  `json:"groupByKeys,omitempty"`
	SortKeys      []string                  `json:"sortKeys,omitempty"`
	Warning       *string                   `json:"warning,omitempty"`
}

type ExplainPlanOutput added in v1.11.0 

type ExplainPlanOutput struct {
	Metadata ExplainPlanMetadataInfo `json:"metadata"`
	Plan     ExplainPlanNode         `json:"plan"`
}

func ExtractExplainPlanOutputFromLogMsg added in v1.13.0 

func ExtractExplainPlanOutputFromLogMsg(lokiEntry loki.Entry) (ExplainPlanOutput, error)

ExtractExplainPlanOutputFromLogMsg extracts the explain plan output from a log message. It is only used for testing by both mysql and postgres explain plan collectors.

type ExplainPlanOutputOperation added in v1.11.0 

type ExplainPlanOutputOperation string
const (
	ExplainPlanOutputOperationTableScan            ExplainPlanOutputOperation = "Table Scan"
	ExplainPlanOutputOperationIndexScan            ExplainPlanOutputOperation = "Index Scan"
	ExplainPlanOutputOperationNestedLoopJoin       ExplainPlanOutputOperation = "Nested Loop Join"
	ExplainPlanOutputOperationHashJoin             ExplainPlanOutputOperation = "Hash Join"
	ExplainPlanOutputOperationMergeJoin            ExplainPlanOutputOperation = "Merge Join"
	ExplainPlanOutputOperationGroupingOperation    ExplainPlanOutputOperation = "Grouping Operation"
	ExplainPlanOutputOperationOrderingOperation    ExplainPlanOutputOperation = "Ordering Operation"
	ExplainPlanOutputOperationDuplicatesRemoval    ExplainPlanOutputOperation = "Duplicates Removal"
	ExplainPlanOutputOperationMaterializedSubquery ExplainPlanOutputOperation = "Materialized Subquery"
	ExplainPlanOutputOperationAttachedSubquery     ExplainPlanOutputOperation = "Attached Subquery"
	ExplainPlanOutputOperationUnion                ExplainPlanOutputOperation = "Union"
	ExplainPlanOutputOperationUnknown              ExplainPlanOutputOperation = "Unknown"
)

type ExplainProcessingResult added in v1.13.0 

type ExplainProcessingResult string
const (
	ExplainProcessingResultSuccess ExplainProcessingResult = "success"
	ExplainProcessingResultError   ExplainProcessingResult = "error"
	ExplainProcessingResultSkipped ExplainProcessingResult = "skipped"
)

type ExplainReservedWordMetadata added in v1.12.0 

type ExplainReservedWordMetadata struct {
	ExemptionPrefixes *[]string
}

type GCPCloudProviderInfo added in v1.16.0 

type GCPCloudProviderInfo struct {
	ProjectID  string
	Region     string
	InstanceID string
}

Source Files

View all Source files

Directories

Path Synopsis
collector
collector/parser
collector

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.