gocql

package module
v2.6.0 Latest Latest
Warning

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

 Go to latest Published: Feb 9, 2026 License: Apache-2.0, BSD-3-Clause Imports: 12 Imported by: 1

Documentation

Overview

Package gocql provides functions to trace the gocql/gocql package (https://github.com/gocql/gocql).

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func CreateTracedSession 

func CreateTracedSession(cluster *gocql.ClusterConfig, opts ...WrapOption) (*gocql.Session, error)

CreateTracedSession returns a new session augmented with tracing.

Example 
package main

import (
	"context"
	"log"

	"github.com/gocql/gocql"

	gocqltrace "github.com/DataDog/dd-trace-go/contrib/gocql/gocql/v2"
	"github.com/DataDog/dd-trace-go/v2/ddtrace/ext"
	"github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
)

func main() {
	cluster := gocql.NewCluster("127.0.0.1:9042")
	cluster.Keyspace = "my-keyspace"

	// Create a new traced session using any number of options
	session, err := gocqltrace.CreateTracedSession(cluster, gocqltrace.WithService("ServiceName"))
	if err != nil {
		log.Fatal(err)
	}
	query := session.Query("CREATE KEYSPACE if not exists trace WITH REPLICATION = { 'class' : 'SimpleStrategy', 'replication_factor': 1}")

	// Use context to pass information down the call chain
	_, ctx := tracer.StartSpanFromContext(context.Background(), "parent.request",
		tracer.SpanType(ext.SpanTypeCassandra),
		tracer.ServiceName("web"),
		tracer.ResourceName("/home"),
	)
	query.WithContext(ctx)

	// If you don't want a concrete query to be traced, you can do query.Observer(nil)

	// Finally, execute the query
	if err := query.Exec(); err != nil {
		log.Fatal(err)
	}
}

Types

type Batch deprecated 

type Batch struct {
	*gocql.Batch
	// contains filtered or unexported fields
}

Batch inherits from gocql.Batch, it keeps the tracer and the context.

Deprecated: use the Observer based method CreateTracedSession instead, which allows to use native gocql types instead of wrapped types.

func WrapBatch deprecated 

func WrapBatch(b *gocql.Batch, opts ...WrapOption) *Batch

WrapBatch wraps a gocql.Batch into a traced Batch under the given service name. Note that the returned Batch structure embeds the original gocql.Batch structure. This means that any method returning the batch for chaining that is not part of this package's Batch structure should be called before WrapBatch, otherwise the tracing context could be lost.

To be more specific: it is ok (and recommended) to use and chain the return value of `WithContext` and `WithTimestamp` but not that of `SerialConsistency`, `Trace`, `Observer`, etc.

Deprecated: use the Observer based method CreateTracedSession instead, which allows to use native gocql types instead of wrapped types.

func (*Batch) ExecuteBatch 

func (tb *Batch) ExecuteBatch(session *gocql.Session) error

ExecuteBatch calls session.ExecuteBatch on the Batch, tracing the execution.

func (*Batch) WithContext 

func (tb *Batch) WithContext(ctx context.Context) *Batch

WithContext adds the specified context to the traced Batch structure.

func (*Batch) WithTimestamp 

func (tb *Batch) WithTimestamp(timestamp int64) *Batch

WithTimestamp will enable the with default timestamp flag on the query like DefaultTimestamp does. But also allows to define value for timestamp. It works the same way as USING TIMESTAMP in the query itself, but should not break prepared query optimization.

func (*Batch) WithWrapOptions 

func (tb *Batch) WithWrapOptions(opts ...WrapOption) *Batch

WithWrapOptions applies the given set of options to the batch.

type ClusterConfig deprecated 

type ClusterConfig struct {
	*gocql.ClusterConfig
	// contains filtered or unexported fields
}

ClusterConfig embeds gocql.ClusterConfig and keeps information relevant to tracing.

Deprecated: use the Observer based method CreateTracedSession instead, which allows to use native gocql types instead of wrapped types.

func NewCluster deprecated 

func NewCluster(hosts []string, opts ...WrapOption) *ClusterConfig

NewCluster calls gocql.NewCluster and returns a wrapped instrumented version of it.

Deprecated: use the Observer based method CreateTracedSession instead, which allows to use native gocql types instead of wrapped types.

Example 
package main

import (
	"context"

	gocqltrace "github.com/DataDog/dd-trace-go/contrib/gocql/gocql/v2"
	"github.com/DataDog/dd-trace-go/v2/ddtrace/ext"
	"github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
)

func main() {
	// Initialise a wrapped Cassandra session and create a query.
	cluster := gocqltrace.NewCluster([]string{"127.0.0.1:9043"}, gocqltrace.WithService("ServiceName"))
	session, _ := cluster.CreateSession()
	query := session.Query("CREATE KEYSPACE if not exists trace WITH REPLICATION = { 'class' : 'SimpleStrategy', 'replication_factor': 1}")

	// Use context to pass information down the call chain
	_, ctx := tracer.StartSpanFromContext(context.Background(), "parent.request",
		tracer.SpanType(ext.SpanTypeCassandra),
		tracer.ServiceName("web"),
		tracer.ResourceName("/home"),
	)

	// Wrap the query to trace it and pass the context for inheritance
	query.WithContext(ctx)
	// Provide any options for the specific query.
	query.WithWrapOptions(gocqltrace.WithResourceName("CREATE KEYSPACE"))

	// Execute your query as usual
	query.Exec()
}

func (*ClusterConfig) CreateSession 

func (c *ClusterConfig) CreateSession() (*Session, error)

CreateSession calls the underlying gocql.ClusterConfig's CreateSession method and returns a new Session augmented with tracing.

type Iter deprecated 

type Iter struct {
	*gocql.Iter
	// contains filtered or unexported fields
}

Iter inherits from gocql.Iter and contains a span.

Deprecated: use the Observer based method CreateTracedSession instead, which allows to use native gocql types instead of wrapped types.

func (*Iter) Close 

func (tIter *Iter) Close() error

Close closes the Iter and finish the span created on Iter call.

func (*Iter) Scanner 

func (tIter *Iter) Scanner() gocql.Scanner

Scanner returns a row Scanner which provides an interface to scan rows in a manner which is similar to database/sql. The Iter should NOT be used again after calling this method.

type Observer 

type Observer struct {
	// contains filtered or unexported fields
}

Observer implements gocql observer interfaces to support tracing.

func NewObserver 

func NewObserver(cluster *gocql.ClusterConfig, opts ...WrapOption) *Observer

NewObserver creates a new Observer to trace gocql. This method is useful in case you want to attach the observer to individual traces / batches instead of instrumenting the whole client.

Example 
package main

import (
	"context"
	"log"

	"github.com/gocql/gocql"

	gocqltrace "github.com/DataDog/dd-trace-go/contrib/gocql/gocql/v2"
	"github.com/DataDog/dd-trace-go/v2/ddtrace/ext"
	"github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
)

func main() {
	cluster := gocql.NewCluster("127.0.0.1:9042")
	cluster.Keyspace = "my-keyspace"

	// Create a new regular gocql session
	session, err := cluster.CreateSession()
	if err != nil {
		log.Fatal(err)
	}
	// Create a new observer using same set of options as gocqltrace.CreateTracedSession.
	obs := gocqltrace.NewObserver(cluster, gocqltrace.WithService("ServiceName"))

	// Attach the observer to queries / batches individually.
	tracedQuery := session.Query("SELECT something FROM somewhere").Observer(obs)
	untracedQuery := session.Query("SELECT something FROM somewhere")

	// Use context to pass information down the call chain
	_, ctx := tracer.StartSpanFromContext(context.Background(), "parent.request",
		tracer.SpanType(ext.SpanTypeCassandra),
		tracer.ServiceName("web"),
		tracer.ResourceName("/home"),
	)
	tracedQuery.WithContext(ctx)

	// Finally, execute the query
	if err := tracedQuery.Exec(); err != nil {
		log.Fatal(err)
	}
	if err := untracedQuery.Exec(); err != nil {
		log.Fatal(err)
	}
}

func (*Observer) ObserveBatch 

func (o *Observer) ObserveBatch(ctx context.Context, batch gocql.ObservedBatch)

ObserveBatch implements gocql.BatchObserver.

func (*Observer) ObserveConnect 

func (o *Observer) ObserveConnect(connect gocql.ObservedConnect)

ObserveConnect implements gocql.ConnectObserver.

func (*Observer) ObserveQuery 

func (o *Observer) ObserveQuery(ctx context.Context, query gocql.ObservedQuery)

ObserveQuery implements gocql.QueryObserver.

type Query deprecated 

type Query struct {
	*gocql.Query
	// contains filtered or unexported fields
}

Query inherits from gocql.Query, it keeps the tracer and the context.

Deprecated: use the Observer based method CreateTracedSession instead, which allows to use native gocql types instead of wrapped types.

func WrapQuery deprecated 

func WrapQuery(q *gocql.Query, opts ...WrapOption) *Query

WrapQuery wraps a gocql.Query into a traced Query under the given service name. Note that the returned Query structure embeds the original gocql.Query structure. This means that any method returning the query for chaining that is not part of this package's Query structure should be called before WrapQuery, otherwise the tracing context could be lost.

To be more specific: it is ok (and recommended) to use and chain the return value of `WithContext` and `PageState` but not that of `Consistency`, `Trace`, `Observer`, etc.

Deprecated: use the Observer based method CreateTracedSession instead, which allows to use native gocql types instead of wrapped types.

func (*Query) Exec 

func (tq *Query) Exec() error

Exec is rewritten so that it passes by our custom Iter

func (*Query) Iter 

func (tq *Query) Iter() *Iter

Iter starts a new span at query.Iter call.

func (*Query) MapScan 

func (tq *Query) MapScan(m map[string]interface{}) error

MapScan wraps in a span query.MapScan call.

func (*Query) MapScanCAS 

func (tq *Query) MapScanCAS(m map[string]interface{}) (applied bool, err error)

MapScanCAS wraps in a span query.MapScanCAS call.

func (*Query) PageState 

func (tq *Query) PageState(state []byte) *Query

PageState rewrites the original function so that spans are aware of the change.

func (*Query) Scan 

func (tq *Query) Scan(dest ...interface{}) error

Scan wraps in a span query.Scan call.

func (*Query) ScanCAS 

func (tq *Query) ScanCAS(dest ...interface{}) (applied bool, err error)

ScanCAS wraps in a span query.ScanCAS call.

func (*Query) WithContext 

func (tq *Query) WithContext(ctx context.Context) *Query

WithContext adds the specified context to the traced Query structure.

func (*Query) WithWrapOptions 

func (tq *Query) WithWrapOptions(opts ...WrapOption) *Query

WithWrapOptions applies the given set of options to the query.

type Scanner deprecated 

type Scanner struct {
	gocql.Scanner
	// contains filtered or unexported fields
}

Scanner inherits from a gocql.Scanner derived from an Iter.

Deprecated: use the Observer based method CreateTracedSession instead, which allows to use native gocql types instead of wrapped types.

func (*Scanner) Err 

func (s *Scanner) Err() error

Err calls the wrapped Scanner.Err, releasing the Scanner resources and closing the span.

type Session deprecated 

type Session struct {
	*gocql.Session
	// contains filtered or unexported fields
}

Session embeds gocql.Session and keeps information relevant to tracing.

Deprecated: use the Observer based method CreateTracedSession instead, which allows to use native gocql types instead of wrapped types.

func (*Session) NewBatch deprecated 

func (s *Session) NewBatch(typ gocql.BatchType) *Batch

NewBatch calls the underlying gocql.Session's NewBatch method and returns a new Batch augmented with tracing.

Deprecated: use the Observer based method CreateTracedSession instead, which allows to use native gocql types instead of wrapped types.

func (*Session) Query 

func (s *Session) Query(stmt string, values ...interface{}) *Query

Query calls the underlying gocql.Session's Query method and returns a new Query augmented with tracing.

type WrapOption 

type WrapOption interface {
	// contains filtered or unexported methods
}

WrapOption describes options for the Cassandra integration.

type WrapOptionFn 

type WrapOptionFn func(config *config)

WrapOptionFn represents options applicable to NewCluster, Query.WithWrapOptions and Batch.WithWrapOptions.

func NoDebugStack 

func NoDebugStack() WrapOptionFn

NoDebugStack prevents stack traces from being attached to spans finishing with an error. This is useful in situations where errors are frequent and performance is critical.

func WithAnalytics 

func WithAnalytics(on bool) WrapOptionFn

WithAnalytics enables Trace Analytics for all started spans.

func WithAnalyticsRate 

func WithAnalyticsRate(rate float64) WrapOptionFn

WithAnalyticsRate sets the sampling rate for Trace Analytics events correlated to started spans.

func WithCustomTag 

func WithCustomTag(key string, value interface{}) WrapOptionFn

WithCustomTag will attach the value to the span tagged by the key.

func WithErrorCheck 

func WithErrorCheck(fn func(err error) bool) WrapOptionFn

WithErrorCheck specifies a function fn which determines whether the passed error should be marked as an error. The fn is called whenever a CQL request finishes with an error.

func WithResourceName 

func WithResourceName(name string) WrapOptionFn

WithResourceName sets a custom resource name to be used with the traced query. By default, the query statement is extracted automatically. This method should be used when a different resource name is desired or in performance critical environments. The gocql library returns the query statement using an fmt.Sprintf call, which can be costly when called repeatedly. Using WithResourceName will avoid that call. Under normal circumstances, it is safe to rely on the default.

func WithService 

func WithService(name string) WrapOptionFn

WithService sets the given service name for the returned query.

func WithTraceBatch 

func WithTraceBatch(enabled bool) WrapOptionFn

WithTraceBatch will enable tracing for batches (default is true). This option only takes effect in CreateTracedSession and NewObserver.

func WithTraceConnect 

func WithTraceConnect(enabled bool) WrapOptionFn

WithTraceConnect will enable tracing for connections (default is true). This option only takes effect in CreateTracedSession and NewObserver.

func WithTraceQuery 

func WithTraceQuery(enabled bool) WrapOptionFn

WithTraceQuery will enable tracing for queries (default is true). This option only takes effect in CreateTracedSession and NewObserver.

Source Files

View all Source files

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.