observability

README

graphql-observability-example

Example code of implementing GraphQL Observability with Go Using Open-source Tools.

Documentation

Index

• Variables
• type AnalyticsTracer
  • func (t AnalyticsTracer) TraceField(ctx context.Context, label, typeName, fieldName string, trivial bool, ...) (context.Context, trace.TraceFieldFinishFunc)
  • func (t AnalyticsTracer) TraceQuery(ctx context.Context, q string, op string, vars map[string]interface{}, ...) (context.Context, trace.TraceQueryFinishFunc)
• type ChainingTracer
  • func (t ChainingTracer) TraceField(ctx context.Context, label, typeName, fieldName string, trivial bool, ...) (context.Context, trace.TraceFieldFinishFunc)
  • func (t ChainingTracer) TraceQuery(ctx context.Context, q string, op string, vars map[string]interface{}, ...) (context.Context, trace.TraceQueryFinishFunc)
• type FieldAnalyzer
• type Logger
  • func (l Logger) Error(msg string)
  • func (l Logger) ErrorCtx(ctx context.Context, msg interface{})
  • func (Logger) Infof(string, ...interface{})
• type LoggingTracer
  • func (t LoggingTracer) TraceField(ctx context.Context, label, typeName, fieldName string, trivial bool, ...) (context.Context, trace.TraceFieldFinishFunc)
  • func (t LoggingTracer) TraceQuery(ctx context.Context, q string, op string, vars map[string]interface{}, ...) (context.Context, trace.TraceQueryFinishFunc)
• type Observer
  • func NewObserver(serviceName string, opts ...Opt) (*Observer, error)
• type Opt
  • func WithAnalytics() Opt
  • func WithLogging() Opt
  • func WithOpenTracing() Opt
  • func (o Opt) ReportSpans() bool
  • func (o Opt) Tracer() trace.Tracer
• type QueryAnalyzer

Variables

var (
	FieldResolveCountView = &view.View{
		Description: "Number of times given GraphQL field was resolved",
		TagKeys:     []tag.Key{TagField},
		Measure:     FieldResolveCount,
		Aggregation: view.Count(),
	}
	FieldResolveDurationView = &view.View{
		Description: "Duration of given GraphQL field's resolvance",
		TagKeys:     []tag.Key{TagField},
		Measure:     FieldResolveDuration,
		Aggregation: ochttp.DefaultLatencyDistribution,
	}
	FieldResolveErrorCountView = &view.View{
		Description: "Number of times given GraphQL field was resolvance returned an error",
		TagKeys:     []tag.Key{TagField},
		Measure:     FieldResolveErrorCount,
		Aggregation: view.Count(),
	}
	QueryResolveCountView = &view.View{
		Description: "Number of times GraphQL queries were resolved",
		Measure:     QueryResolveCount,
		Aggregation: view.Count(),
	}
	QueryResolveDurationView = &view.View{
		Description: "Duration of GraphQL queries resolvance",
		Measure:     QueryResolveDuration,
		Aggregation: ochttp.DefaultLatencyDistribution,
	}
	QueryResolveErrorCountView = &view.View{
		Description: "Number of errors returned by GraphQL queries resolvance",
		Measure:     QueryResolveErrorCount,
		Aggregation: view.Distribution(1, 2, 3, 4, 5, 6, 8, 10, 13, 16, 20, 25, 30, 40, 50, 65, 80, 100, 130, 160, 200),
	}
)

Views of GraphQL fields analytics.

var (
	FieldResolveCount = stats.Int64(
		"graphql/server/field_resolve_count",
		"Number of times given GraphQL field was resolved",
		stats.UnitDimensionless)
	FieldResolveDuration = stats.Float64(
		"graphql/server/field_resolve_duration",
		"Duration of given GraphQL field's resolvance",
		stats.UnitMilliseconds)
	FieldResolveErrorCount = stats.Int64(
		"graphql/server/field_resolve_error_count",
		"Number of times given GraphQL field was resolvance returned an error",
		stats.UnitDimensionless)
	QueryResolveCount = stats.Int64(
		"graphql/server/query_resolve_count",
		"Number of times GraphQL queries were resolved",
		stats.UnitDimensionless)
	QueryResolveDuration = stats.Float64(
		"graphql/server/query_resolve_duration",
		"Duration of GraphQL queries resolvance",
		stats.UnitMilliseconds)
	QueryResolveErrorCount = stats.Int64(
		"graphql/server/query_resolve_error_count",
		"Number of errors returned by GraphQL queries resolvance",
		stats.UnitDimensionless)
)

GraphQL field analytics measures.

var (
	TagField = tag.MustNewKey("graphql.field")
)

Tags for constructing viewes of GraphQL field analytics.

Types

type AnalyticsTracer

type AnalyticsTracer struct{}

AnalyticsTracer implements graph-gophers/graphql-go/trace/Tracer interface. It records GraphQL analytics of queries and fields via QueryAnalyzer and FieldAnalyzer.

func (AnalyticsTracer) TraceField

func (t AnalyticsTracer) TraceField(
	ctx context.Context, label, typeName, fieldName string, trivial bool,
	args map[string]interface{},
) (context.Context, trace.TraceFieldFinishFunc)

TraceField initializes a FieldAnalyzer at the begginning of field resolvance. At the end of field resolvance FieldAnalyzer.recordMeasurements is called to record measures of given field resolvance.

func (AnalyticsTracer) TraceQuery

func (t AnalyticsTracer) TraceQuery(
	ctx context.Context, q string, op string,
	vars map[string]interface{}, types map[string]*introspection.Type,
) (context.Context, trace.TraceQueryFinishFunc)

TraceQuery initializes a QueryAnalyzer at the begginning of query resolvance. At the end of query resolvance QueryAnalyzer.recordMeasurements is called to record measures of given query resolvance.

type ChainingTracer

type ChainingTracer struct {
	Tracers []trace.Tracer
}

ChainingTracer implements graph-gophers/graphql-go/trace/Tracer interface. It's capable of chaining the tracers provided. Tracers are called in the order provided. context.Context returned by previous tracer is passed to the next one in order.

func (ChainingTracer) TraceField

func (t ChainingTracer) TraceField(
	ctx context.Context, label, typeName, fieldName string, trivial bool,
	args map[string]interface{},
) (context.Context, trace.TraceFieldFinishFunc)

TraceField calls TraceField method of tracers in the order they are provided. context.Context returned by previous TraceField is passed to the next one in order.

func (ChainingTracer) TraceQuery

func (t ChainingTracer) TraceQuery(
	ctx context.Context, q string, op string, vars map[string]interface{},
	types map[string]*introspection.Type,
) (context.Context, trace.TraceQueryFinishFunc)

TraceQuery calls TraceQuery method of tracers in the order they are provided. context.Context returned by previous TraceQuery is passed to the next one in order.

type FieldAnalyzer

type FieldAnalyzer struct {
	Ctx         context.Context
	Type, Field string
	Start       time.Time
}

FieldAnalyzer is capable of recording measures of given GraphQL field for analytic purposes.

type Logger

type Logger struct{}

Logger provides a consistent logging format.

func (Logger) Error

func (l Logger) Error(msg string)

Error is to implement jaeger.Logger interface. It can also be used if trace ID is not available. If trace ID is available ErrorCtx should be used instead.

func (Logger) ErrorCtx

func (l Logger) ErrorCtx(ctx context.Context, msg interface{})

ErrorCtx logs error alongside trace ID of context.

func (Logger) Infof

func (Logger) Infof(string, ...interface{})

Infof is to implement jaeger.Logger interface. It doesn't do anything really, we should implement it if we want to do info level logging. If we do, we should have a configuration flag to turn it off.

type LoggingTracer

type LoggingTracer struct{}

LoggingTracer implements graph-gophers/graphql-go/trace/Tracer interface. It provides error logging of resolvers via Logger.

func (LoggingTracer) TraceField

func (t LoggingTracer) TraceField(
	ctx context.Context, label, typeName, fieldName string, trivial bool,
	args map[string]interface{},
) (context.Context, trace.TraceFieldFinishFunc)

TraceField is a no-op. It's defined to implement graph-gophers/graphql-go/trace/Tracer interface.

func (LoggingTracer) TraceQuery

func (t LoggingTracer) TraceQuery(
	ctx context.Context, q string, op string, vars map[string]interface{},
	types map[string]*introspection.Type,
) (context.Context, trace.TraceQueryFinishFunc)

TraceQuery returns a callback function that will be called at the end of the query. This callback function logs all errors occurred in resolvers (aggregated, with TraceID).

type Observer

type Observer struct {
	Logger          Logger
	Tracer          trace.Tracer
	Closer          io.Closer
	MetricsExporter http.Handler
	TraceHeader     func(http.Handler) http.Handler
}

Observer represents a collection of services that instruments our application to provide runtime insights (metrics, logs, traces).

func NewObserver

func NewObserver(serviceName string, opts ...Opt) (*Observer, error)

NewObserver returns a new Observer for given service, configured using provided options.

type Opt

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

Opt enables an opt-in feature to Observer if provided at NewObserver.

func WithAnalytics

func WithAnalytics() Opt

WithAnalytics returns an Opt that enables GraphQL analytics (exposed via Observer.MetricsExporter).

func WithLogging

func WithLogging() Opt

WithLogging returns an Opt that enables logging of resolver errors (with traceID).

func WithOpenTracing

func WithOpenTracing() Opt

WithOpenTracing returns an Opt that enables OpenTracing.

func (Opt) ReportSpans

func (o Opt) ReportSpans() bool

ReportSpans returns whether or not to enable OpenTracing span reporting according to given span.

func (Opt) Tracer

func (o Opt) Tracer() trace.Tracer

Tracer returns associated tracer with given Opt.

type QueryAnalyzer

type QueryAnalyzer struct {
	Ctx   context.Context
	Start time.Time
}

QueryAnalyzer is capable of recording measures of given GraphQL query for analytic purposes.