gocql

Documentation

Overview

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

Index

• func CreateTracedSession(cluster *gocql.ClusterConfig, opts ...WrapOption) (*gocql.Session, error)
• type Batch
  • func WrapBatch(b *gocql.Batch, opts ...WrapOption) *Batch
• type ClusterConfig
  • func NewCluster(hosts []string, opts ...WrapOption) *ClusterConfig
• type Iter
• type Observer
  • func NewObserver(cluster *gocql.ClusterConfig, opts ...WrapOption) *Observer
• type Query
  • func WrapQuery(q *gocql.Query, opts ...WrapOption) *Query
• type Scanner
• type Session
• type WrapOption
  • func NoDebugStack() WrapOption
  • func WithAnalytics(on bool) WrapOption
  • func WithAnalyticsRate(rate float64) WrapOption
  • func WithCustomTag(key string, value interface{}) WrapOption
  • func WithErrorCheck(fn func(err error) bool) WrapOption
  • func WithResourceName(name string) WrapOption
  • func WithServiceName(name string) WrapOption
  • func WithTraceBatch(enabled bool) WrapOption
  • func WithTraceConnect(enabled bool) WrapOption
  • func WithTraceQuery(enabled bool) WrapOption

Examples

• CreateTracedSession
• NewCluster
• NewObserver

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 "gopkg.in/DataDog/dd-trace-go.v1/contrib/gocql/gocql"
	"gopkg.in/DataDog/dd-trace-go.v1/ddtrace/ext"
	"gopkg.in/DataDog/dd-trace-go.v1/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.WithServiceName("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

type Batch = v2.Batch

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

func WrapBatch

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.

type ClusterConfig

type ClusterConfig = v2.ClusterConfig

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

func NewCluster

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 "gopkg.in/DataDog/dd-trace-go.v1/contrib/gocql/gocql"
	"gopkg.in/DataDog/dd-trace-go.v1/ddtrace/ext"
	"gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer"
)

func main() {
	// Initialise a wrapped Cassandra session and create a query.
	cluster := gocqltrace.NewCluster([]string{"127.0.0.1:9043"}, gocqltrace.WithServiceName("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()
}

type Iter

type Iter = v2.Iter

Iter inherits from gocql.Iter and contains a span.

type Observer

type Observer = v2.Observer

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 "gopkg.in/DataDog/dd-trace-go.v1/contrib/gocql/gocql"
	"gopkg.in/DataDog/dd-trace-go.v1/ddtrace/ext"
	"gopkg.in/DataDog/dd-trace-go.v1/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.WithServiceName("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)
	}
}

type Query

type Query = v2.Query

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

func WrapQuery

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.

type Scanner

type Scanner = v2.Scanner

Scanner inherits from a gocql.Scanner derived from an Iter

type Session

type Session = v2.Session

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

type WrapOption

type WrapOption = v2.WrapOption

WrapOption represents an option that can be passed to WrapQuery.

func NoDebugStack

func NoDebugStack() WrapOption

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) WrapOption

WithAnalytics enables Trace Analytics for all started spans.

func WithAnalyticsRate

func WithAnalyticsRate(rate float64) WrapOption

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

func WithCustomTag

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

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

func WithErrorCheck

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

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) WrapOption

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 WithServiceName

func WithServiceName(name string) WrapOption

WithServiceName sets the given service name for the returned query.

func WithTraceBatch

func WithTraceBatch(enabled bool) WrapOption

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

func WithTraceConnect

func WithTraceConnect(enabled bool) WrapOption

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

func WithTraceQuery

func WithTraceQuery(enabled bool) WrapOption

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