otelgqlgen

README

OpenTelemetry-Go gqlgen Instrumentation

It is an OpenTelemetry instrumentation for Golang 99designs/gqlgen, a port from https://github.com/open-telemetry/opentelemetry-go-contrib/pull/761.

It can only instrument traces for the present.

Installation

To install the otelgqlgen package, use the following command:

go get github.com/queasyplayer/otelgqlgen

Usage

Below is a basic example of how to use otelgqlgen:

package main

import (
    "github.com/99designs/gqlgen/graphql/handler"
    "github.com/queasyplayer/otelgqlgen"
    "github.com/myorg/mygqlgenapi/graph"
)

func main() {
    srv := handler.NewDefaultServer(graph.NewExecutableSchema(graph.Config{Resolvers: &graph.Resolver{}}))

    // Add the otelgqlgen middleware to add OpenTelemetry tracing
    srv.Use(otelgqlgen.Middleware())

    // Your usual server setup code...
}

Configuration Options

otelgqlgen provides several options to customize the tracing behavior:

• WithTracerProvider(provider): Specifies a custom tracer provider. By default, the global OpenTelemetry tracer provider is used.
• WithComplexityExtensionName(name): Specifies a name for the complexity extension. By default, a name is automatically generated.
• WithRequestVariablesAttributesBuilder(builder): Specifies a custom function to build the attributes for the request variables.
• WithoutVariables(): Disables the variables attributes.
• WithCreateSpanFromFields(predicate): Specifies a custom function to control whether a span should be created based on the GraphQL context fields.

Example

See ./example.

Compatibility

This project is tested on the following systems.

OS	Go Version	Architecture
Ubuntu	1.21	amd64
Ubuntu	1.22	amd64
Ubuntu	1.21	386
Ubuntu	1.22	386
MacOS	1.21	amd64
MacOS	1.22	amd64
Windows	1.21	amd64
Windows	1.22	amd64
Windows	1.21	386
Windows	1.22	386

While this project should work for other systems, no compatibility guarantees are made for those systems currently.

The project follows the Release Policy to support major Go releases.

References

• GraphQL
• gqlgen

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Documentation

Overview

Package otelgqlgen instruments the github.com/99designs/gqlgen package.

Currently only the routing of a received message can be instrumented. To do it, use the Middleware function.

Index

• func GetOperationName(ctx context.Context) string
• func RequestComplexityLimit(complexityLimit int64) attribute.KeyValue
• func RequestOperationComplexity(complexityLimit int64) attribute.KeyValue
• func RequestQuery(requestQuery string) attribute.KeyValue
• func RequestVariables(requestVariables map[string]interface{}) []attribute.KeyValue
• func ResolverAlias(resolverAlias string) attribute.KeyValue
• func ResolverArgs(argList ast.ArgumentList) []attribute.KeyValue
• func ResolverErrors(errorList gqlerror.List) []attribute.KeyValue
• func ResolverField(resolverField string) attribute.KeyValue
• func ResolverObject(resolverObject string) attribute.KeyValue
• func ResolverPath(resolverPath string) attribute.KeyValue
• func SetOperationName(ctx context.Context, name string) context.Context
• type FieldsPredicateFunc
• type Option
  • func WithComplexityExtensionName(complexityExtensionName string) Option
  • func WithCreateSpanFromFields(predicate FieldsPredicateFunc) Option
  • func WithRequestVariablesAttributesBuilder(builder RequestVariablesBuilderFunc) Option
  • func WithSpanKindSelector(spanKindSelector SpanKindSelectorFunc) Option
  • func WithTracerProvider(provider trace.TracerProvider) Option
  • func WithoutVariables() Option
• type RequestVariablesBuilderFunc
• type SpanKindSelectorFunc
• type Tracer
  • func Middleware(opts ...Option) Tracer
  • func (a Tracer) ExtensionName() string
  • func (a Tracer) InterceptField(ctx context.Context, next graphql.Resolver) (interface{}, error)
  • func (a Tracer) InterceptResponse(ctx context.Context, next graphql.ResponseHandler) *graphql.Response
  • func (a Tracer) Validate(_ graphql.ExecutableSchema) error

Functions

func GetOperationName

func GetOperationName(ctx context.Context) string

GetOperationName gets the operation name from the context.

func RequestComplexityLimit

func RequestComplexityLimit(complexityLimit int64) attribute.KeyValue

RequestComplexityLimit sets the complexity limit.

func RequestOperationComplexity

func RequestOperationComplexity(complexityLimit int64) attribute.KeyValue

RequestOperationComplexity sets the operation complexity.

func RequestQuery

func RequestQuery(requestQuery string) attribute.KeyValue

RequestQuery sets the request query.

func RequestVariables

func RequestVariables(requestVariables map[string]interface{}) []attribute.KeyValue

RequestVariables sets request variables.

func ResolverAlias

func ResolverAlias(resolverAlias string) attribute.KeyValue

ResolverAlias sets resolver alias.

func ResolverArgs

func ResolverArgs(argList ast.ArgumentList) []attribute.KeyValue

ResolverArgs sets resolver args.

func ResolverErrors

func ResolverErrors(errorList gqlerror.List) []attribute.KeyValue

ResolverErrors sets errors.

func ResolverField

func ResolverField(resolverField string) attribute.KeyValue

ResolverField sets resolver field.

func ResolverObject

func ResolverObject(resolverObject string) attribute.KeyValue

ResolverObject sets resolver object.

func ResolverPath

func ResolverPath(resolverPath string) attribute.KeyValue

ResolverPath sets resolver path.

func SetOperationName

func SetOperationName(ctx context.Context, name string) context.Context

SetOperationName adds the operation name to the context so that the interceptors can use it. It will replace the operation name if it already exists in the context. example:

	ctx = otelgqlgen.SetOperationName(r.Context(), "my-operation")
 	r = r.WithContext(ctx)

Types

type FieldsPredicateFunc

type FieldsPredicateFunc func(ctx *graphql.FieldContext) bool

type Option

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

Option specifies instrumentation configuration options.

func WithComplexityExtensionName

func WithComplexityExtensionName(complexityExtensionName string) Option

WithComplexityExtensionName specifies complexity extension name.

func WithCreateSpanFromFields

func WithCreateSpanFromFields(predicate FieldsPredicateFunc) Option

WithCreateSpanFromFields allows specifying a custom function to handle the creation or not of spans regarding the GraphQL context fields.

func WithRequestVariablesAttributesBuilder

func WithRequestVariablesAttributesBuilder(builder RequestVariablesBuilderFunc) Option

WithRequestVariablesAttributesBuilder allows specifying a custom function to handle the building of the attributes for the variables.

func WithSpanKindSelector

func WithSpanKindSelector(spanKindSelector SpanKindSelectorFunc) Option

WithSpanKindSelector allows specifying a custom function that defines the SpanKind based on the name of the operation.

func WithTracerProvider

func WithTracerProvider(provider trace.TracerProvider) Option

WithTracerProvider specifies a tracer provider to use for creating a tracer. If none is specified, the global provider is used.

func WithoutVariables

func WithoutVariables() Option

WithoutVariables allows disabling the variables attributes.

type RequestVariablesBuilderFunc

type RequestVariablesBuilderFunc func(requestVariables map[string]interface{}) []attribute.KeyValue

RequestVariablesBuilderFunc is the signature of the function used to build the request variables attributes.

type SpanKindSelectorFunc

type SpanKindSelectorFunc func(operationName string) trace.SpanKind

type Tracer

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

Tracer is a GraphQL extension that traces GraphQL requests.

func Middleware

func Middleware(opts ...Option) Tracer

Middleware sets up a handler to start tracing the incoming requests. The service parameter should describe the name of the (virtual) server handling the request. extension parameter may be empty string.

func (Tracer) ExtensionName

func (a Tracer) ExtensionName() string

ExtensionName returns the extension name.

func (Tracer) InterceptField

func (a Tracer) InterceptField(ctx context.Context, next graphql.Resolver) (interface{}, error)

InterceptField intercepts the incoming request.

func (Tracer) InterceptResponse

func (a Tracer) InterceptResponse(ctx context.Context, next graphql.ResponseHandler) *graphql.Response

InterceptResponse intercepts the incoming request.

func (Tracer) Validate

func (a Tracer) Validate(_ graphql.ExecutableSchema) error

Validate checks if the extension is configured properly.