README
¶
Splunk Instrumentation for the database/sql Package
This package instruments the database/sql
package.
Getting Started
This package is designed to be used in conjunction with existing database drivers that have been instrumented so OpenTelemetry semantic conventions can be discovered. An example of this type of use can be found here.
This package can be used directly as well. It becomes the users responsibility to ensure accurate and complete information about the database system is passed as attributes to ensure OpenTelemetry semantic conventions are satisfied. An example of this can be found here.
Documentation
¶
Overview ¶
Package splunksql provides functions to instrument the database/sql package using the OpenTelemetry API.
It will augment operation such as connections, statements and transactions with tracing.
It will collect the following metrics:
- db.client.connections.usage ({connection}) - The number of connections that are currently in state described by the state attribute
- db.client.connections.max ({connection}) - The maximum number of open connections allowed
- db.client.connections.wait_time (ms) - The time it took to obtain an open connection from the pool
Example ¶
package main
import (
"fmt"
"log"
"go.opentelemetry.io/otel/attribute"
semconv "go.opentelemetry.io/otel/semconv/v1.17.0"
"github.com/signalfx/splunk-otel-go/instrumentation/database/sql/splunksql"
)
const (
dbname = "orders"
user = "frank"
pass = "hotdog"
host = "localhost"
port = 9876
)
var (
connStr = fmt.Sprintf("custom|%s:%s|%s:%d|%s", user, pass, host, port, dbname)
sanitized = fmt.Sprintf("custom|%s|%s:%d|%s", user, host, port, dbname)
// semanticAttrs are the attributes OpenTelemetry requires and recommends.
semanticAttrs = []attribute.KeyValue{
semconv.DBSystemOtherSQL,
semconv.DBNameKey.String(dbname),
// Do not include passwords!
semconv.DBConnectionStringKey.String(sanitized),
semconv.DBUserKey.String(user),
// Use semconv.NetSockPeerAddrKey if connecting via an IP address. If
// connecting via a Unix socket, use this attribute key.
semconv.NetPeerNameKey.String(host),
semconv.NetPeerPortKey.Int(port),
semconv.NetTransportTCP,
}
)
func main() {
// For database drivers that are already registered with the database/sql
// package, you can pass the OpenTelemetry attributes directly to the
// splunksql.Open function. These attributes will be attached to all spans
// the instrumentation creates.
db, err := splunksql.Open(
"already-registered-driver",
connStr,
splunksql.WithAttributes(semanticAttrs),
)
if err != nil {
log.Fatalf("Failed to open database: %#+v", err)
}
defer db.Close()
// Use the traced db...
}
Output:
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
View Source
var ( // DBSystemOtherSQL is some other SQL database. This is used as a fallback // only. DBSystemOtherSQL = DBSystem(semconv.DBSystemOtherSQL) // DBSystemMSSQL is a Microsoft SQL Server database system. DBSystemMSSQL = DBSystem(semconv.DBSystemMSSQL) // DBSystemMySQL is a MySQL database system. DBSystemMySQL = DBSystem(semconv.DBSystemMySQL) // DBSystemOracle is an Oracle Database database system. DBSystemOracle = DBSystem(semconv.DBSystemOracle) // DBSystemDB2 is a IBM DB2 database system. DBSystemDB2 = DBSystem(semconv.DBSystemDB2) // DBSystemPostgreSQL is a PostgreSQL database system. DBSystemPostgreSQL = DBSystem(semconv.DBSystemPostgreSQL) // DBSystemRedshift is an Amazon Redshift database system. DBSystemRedshift = DBSystem(semconv.DBSystemRedshift) // DBSystemHive is an Apache Hive database system. DBSystemHive = DBSystem(semconv.DBSystemHive) // DBSystemCloudscape is a Cloudscape database system. DBSystemCloudscape = DBSystem(semconv.DBSystemCloudscape) // DBSystemHSQLDB is a HyperSQL DataBase database system. DBSystemHSQLDB = DBSystem(semconv.DBSystemHSQLDB) // DBSystemProgress is a Progress Database database system. DBSystemProgress = DBSystem(semconv.DBSystemProgress) // DBSystemMaxDB is an SAP MaxDB database system. DBSystemMaxDB = DBSystem(semconv.DBSystemMaxDB) // DBSystemHanaDB is an SAP HANA database system. DBSystemHanaDB = DBSystem(semconv.DBSystemHanaDB) // DBSystemIngres is an Ingres database system. DBSystemIngres = DBSystem(semconv.DBSystemIngres) // DBSystemFirstSQL is a FirstSQL database system. DBSystemFirstSQL = DBSystem(semconv.DBSystemFirstSQL) // DBSystemEDB is an EnterpriseDB database system. DBSystemEDB = DBSystem(semconv.DBSystemEDB) // DBSystemCache is an InterSystems Caché database system. DBSystemCache = DBSystem(semconv.DBSystemCache) // DBSystemAdabas is an Adabas (Adaptable Database System) database // system. DBSystemAdabas = DBSystem(semconv.DBSystemAdabas) // DBSystemFirebird is a Firebird database system. DBSystemFirebird = DBSystem(semconv.DBSystemFirebird) // DBSystemDerby is an Apache Derby database system. DBSystemDerby = DBSystem(semconv.DBSystemDerby) // DBSystemFilemaker is a FileMaker database system. DBSystemFilemaker = DBSystem(semconv.DBSystemFilemaker) // DBSystemInformix is an Informix database system. DBSystemInformix = DBSystem(semconv.DBSystemInformix) // DBSystemInstantDB is an InstantDB database system. DBSystemInstantDB = DBSystem(semconv.DBSystemInstantDB) // DBSystemInterbase is an InterBase database system. DBSystemInterbase = DBSystem(semconv.DBSystemInterbase) // DBSystemMariaDB is a MariaDB database system. DBSystemMariaDB = DBSystem(semconv.DBSystemMariaDB) // DBSystemNetezza is a Netezza database system. DBSystemNetezza = DBSystem(semconv.DBSystemNetezza) // DBSystemPervasive is a Pervasive PSQL database system. DBSystemPervasive = DBSystem(semconv.DBSystemPervasive) // DBSystemPointbase is a PointBase database system. DBSystemPointbase = DBSystem(semconv.DBSystemPointbase) // DBSystemSqlite is a SQLite database system. DBSystemSqlite = DBSystem(semconv.DBSystemSqlite) // DBSystemSybase is a Sybase database system. DBSystemSybase = DBSystem(semconv.DBSystemSybase) // DBSystemTeradata is a Teradata database system. DBSystemTeradata = DBSystem(semconv.DBSystemTeradata) // DBSystemVertica is a Vertica database system. DBSystemVertica = DBSystem(semconv.DBSystemVertica) // DBSystemH2 is a H2 database system. DBSystemH2 = DBSystem(semconv.DBSystemH2) // DBSystemColdfusion is a ColdFusion IMQ database system. DBSystemColdfusion = DBSystem(semconv.DBSystemColdfusion) // DBSystemCassandra is an Apache Cassandra database system. DBSystemCassandra = DBSystem(semconv.DBSystemCassandra) // DBSystemHBase is an Apache HBase database system. DBSystemHBase = DBSystem(semconv.DBSystemHBase) // DBSystemMongoDB is a MongoDB database system. DBSystemMongoDB = DBSystem(semconv.DBSystemMongoDB) // DBSystemRedis is a Redis database system. DBSystemRedis = DBSystem(semconv.DBSystemRedis) // DBSystemCouchbase is a Couchbase database system. DBSystemCouchbase = DBSystem(semconv.DBSystemCouchbase) // DBSystemCouchDB is a CouchDB database system. DBSystemCouchDB = DBSystem(semconv.DBSystemCouchDB) // DBSystemCosmosDB is a Microsoft Azure Cosmos DB database system. DBSystemCosmosDB = DBSystem(semconv.DBSystemCosmosDB) // DBSystemDynamoDB is an Amazon DynamoDB database system. DBSystemDynamoDB = DBSystem(semconv.DBSystemDynamoDB) // DBSystemNeo4j is a Neo4j database system. DBSystemNeo4j = DBSystem(semconv.DBSystemNeo4j) // DBSystemGeode is an Apache Geode database system. DBSystemGeode = DBSystem(semconv.DBSystemGeode) // DBSystemElasticsearch is an Elasticsearch database system. DBSystemElasticsearch = DBSystem(semconv.DBSystemElasticsearch) // DBSystemMemcached is a Memcached database system. DBSystemMemcached = DBSystem(semconv.DBSystemMemcached) // DBSystemCockroachdb is a CockroachDB database system. DBSystemCockroachdb = DBSystem(semconv.DBSystemCockroachdb) )
View Source
var ( NetTransportTCP = NetTransport(semconv.NetTransportTCP) NetTransportUDP = NetTransport(semconv.NetTransportUDP) NetTransportPipe = NetTransport(semconv.NetTransportPipe) NetTransportInProc = NetTransport(semconv.NetTransportInProc) NetTransportOther = NetTransport(semconv.NetTransportOther) // Deprecated: Use appropriate NetSockFamily* instead. NetTransportIP = NetTransport(semconv.NetTransportKey.String("ip")) // Deprecated: Use appropriate NetSockFamily* instead. NetTransportUnix = NetTransport(semconv.NetTransportKey.String("unix")) )
Valid transport protocols.
View Source
var ( NetSockFamilyInet = NetSockFamily(semconv.NetSockFamilyInet) NetSockFamilyInet6 = NetSockFamily(semconv.NetSockFamilyInet6) NetSockFamilyUnix = NetSockFamily(semconv.NetSockFamilyUnix) )
Valid protocol address families.
Functions ¶
func Open ¶
Open opens a database specified by its database driver name and a driver-specific data source name, usually consisting of at least a database name and connection information. The returned database uses a traced driver for all connections.
func Register ¶
func Register(name string, c InstrumentationConfig)
Register makes the InstrumentationConfig for the setup of a database driverwith the provided name available. If Register is called twice for the same name it panics.
Example ¶
// For database drivers that are already registered with the database/sql
// package, a custom connection string parser and information about the
// driver can be registered with the splunksql package. These will be used
// when the splunksql.Open function is called for the registered driver.
splunksql.Register("my-registered-driver", splunksql.InstrumentationConfig{
DBSystem: splunksql.DBSystemOtherSQL,
DSNParser: func(dsn string) (splunksql.ConnectionConfig, error) {
parts := strings.SplitN(dsn, "|", 3)
name, user, host := parts[0], parts[1], parts[2]
return splunksql.ConnectionConfig{
// Be sure to sanitize passwords from this!
ConnectionString: dsn,
Name: name,
User: user,
Host: host,
Port: 9876,
NetTransport: splunksql.NetTransportTCP,
NetSockFamily: splunksql.NetSockFamilyInet,
}, nil
},
})
// Now when splunksql.Open is called the provided InstrumentationConfig
// will be used to ensure the telemetry produced adheres to OpenTelemetry
// semantic conventions. E.g.
db, err := splunksql.Open("my-registered-driver", connStr)
if err != nil {
log.Fatalf("Failed to open database: %#+v", err)
}
defer db.Close()
Types ¶
type ConnectionConfig ¶
type ConnectionConfig struct {
// Name of the database being accessed.
Name string
// ConnectionString is the sanitized connection string (all credentials
// have been redacted) used to connect to the database.
ConnectionString string
// User is the username used to access the database.
User string
// Host is the IP or hostname of the database.
Host string
// Port is the port the database is lisening on.
Port int
// NetTransport is the transport protocol used to connect to the database.
NetTransport NetTransport
// NetSockFamily is the protocol address family used for communication to
// the database.
NetSockFamily NetSockFamily
}
ConnectionConfig are the relevant settings parsed from a database connection.
func (ConnectionConfig) Attributes ¶
func (c ConnectionConfig) Attributes() ([]attribute.KeyValue, error)
Attributes returns the connection settings as attributes compliant with OpenTelemetry semantic coventions. If the settings do not conform to OpenTelemetry requirements an error is returned with a partial list of attributes that do conform.
type DBSystem ¶
DBSystem is a database system type.
type DSNParser ¶
type DSNParser func(dataSourceName string) (ConnectionConfig, error)
DSNParser processes a driver-specific data source name into connection-level attributes conforming with the OpenTelemetry semantic conventions.
type InstrumentationConfig ¶
type InstrumentationConfig struct {
// DBSystem is the database system being registered.
DBSystem DBSystem
DSNParser DSNParser
}
InstrumentationConfig is the setup configuration for the instrumentation of a database driver.
type NetSockFamily ¶ added in v1.3.0
NetSockFamily is a protocol address family used for communication.
func (NetSockFamily) Attribute ¶ added in v1.3.0
func (s NetSockFamily) Attribute() attribute.KeyValue
Attribute returns t as an attribute KeyValue. If s is empty the returned attribute will also be an empty, undefined, KeyValue.
type NetTransport ¶
NetTransport is a communication transport protocol.
func (NetTransport) Attribute ¶
func (t NetTransport) Attribute() attribute.KeyValue
Attribute returns t as an attribute KeyValue. If t is empty or a deprecated value, the returned attribute will default to a NetTransportOther.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option applies options to a tracing configuration.
func WithAttributes ¶
WithAttributes returns an Option that appends attr to the attributes set for every span created with this instrumentation library.
func WithMeterProvider ¶ added in v1.6.0
func WithMeterProvider(mp metric.MeterProvider) Option
WithMeterProvider returns an Option that sets the MeterProvider used with this instrumentation library.
func WithTracerProvider ¶
func WithTracerProvider(tp trace.TracerProvider) Option
WithTracerProvider returns an Option that sets the TracerProvider used with this instrumentation library.
Source Files
¶
Directories
Click to show internal directories.
Click to hide internal directories.