gqlhive

README

gqlhive

Usage reporting to GraphQL Hive for gqlgen.

Getting started

Install

go get github.com/enisdenjo/go-gqlhive@latest

Use

After getting started with gqlgen add the tracer to the server.

package main

import (
	"log"
	"net/http"
	"os"

	"github.com/enisdenjo/go-gqlhive/graphql/handler"
	"github.com/enisdenjo/go-gqlhive/graphql/playground"
	"github.com/enisdenjo/go-gqlhive"
	"github.com/enisdenjo/go-gqlhive/internal/fixtures/todos/graph"
)

const defaultPort = "8080"

func main() {
	port := os.Getenv("PORT")
	if port == "" {
		port = defaultPort
	}

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

  // 👇 use the gqlhive tracer with your token
	srv.Use(gqlhive.NewTracer("<your-graphql-hive-token>"))

	http.Handle("/", playground.Handler("GraphQL playground", "/query"))
	http.Handle("/query", srv)

	log.Printf("connect to http://localhost:%s/ for GraphQL playground", port)
	log.Fatal(http.ListenAndServe(":"+port, nil))
}

Configure

See traceroptions.go for configuring the tracer.

For example:

package main

import (
	"context"
	"log"
	"net/http"
	"os"
	"time"

	"github.com/enisdenjo/go-gqlhive/graphql/handler"
	"github.com/enisdenjo/go-gqlhive/graphql/playground"
	"github.com/domonda/go-types/nullable"
	"github.com/enisdenjo/go-gqlhive"
	"github.com/enisdenjo/go-gqlhive/internal/fixtures/todos/graph"
)

const defaultPort = "8080"

func main() {
	port := os.Getenv("PORT")
	if port == "" {
		port = defaultPort
	}

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

  // 👇 use the gqlhive tracer with your token and custom options
	srv.Use(gqlhive.NewTracer("<your-graphql-hive-token>",
		gqlhive.WithEndpoint("http://localhost"),
		gqlhive.WithGenerateID(func(operation string, operationName nullable.TrimmedString) string {
			// custom unique ID generation for operations
		}),
		gqlhive.WithSendReportTimeout(5*time.Second),
		gqlhive.WithSendReport(func(ctx context.Context, endpoint, token string, report *gqlhive.Report) error {
			// custom report sender for queued reports
		}),
	))

	http.Handle("/", playground.Handler("GraphQL playground", "/query"))
	http.Handle("/query", srv)

	log.Printf("connect to http://localhost:%s/ for GraphQL playground", port)
	log.Fatal(http.ListenAndServe(":"+port, nil))
}

Documentation

Index

• Constants
• func ContextWithOperation(ctx context.Context, operation *OperationWithInfo) context.Context
• type Client
• type Execution
• type GenerateID
• type Metadata
• type Operation
• type OperationInfo
• type OperationWithInfo
  • func OperationFromContext(ctx context.Context) (operation *OperationWithInfo, exists bool)
• type Report
• type SendReport
• type Tracer
  • func NewTracer(token string, opts ...TracerOption) *Tracer
  • func (tracer Tracer) ExtensionName() string
  • func (tracer Tracer) InterceptField(ctx context.Context, next graphql.Resolver) (interface{}, error)
  • func (tracer Tracer) InterceptResponse(ctx context.Context, next graphql.ResponseHandler) *graphql.Response
  • func (tracer Tracer) Validate(schema graphql.ExecutableSchema) error
• type TracerOption
  • func WithEndpoint(endpoint string) TracerOption
  • func WithGenerateID(fn GenerateID) TracerOption
  • func WithSendReport(fn SendReport) TracerOption
  • func WithSendReportTimeout(timeout time.Duration) TracerOption

Constants

const (
	CLIENT_NAME    = "go-gqlhive"
	CLIENT_VERSION = "1.0.3"
)

Functions

func ContextWithOperation

func ContextWithOperation(ctx context.Context, operation *OperationWithInfo) context.Context

Types

type Client

type Client struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

type Execution

type Execution struct {
	// Was the execution successful?
	Ok bool `json:"ok"`
	// Duration of the entire operation in nanoseconds
	Duration int64 `json:"duration"`
	// Total number of occurred GraphQL errors
	ErrorsTotal int `json:"errorsTotal"`
}

type GenerateID

type GenerateID func(operation string, operationName nullable.TrimmedString) string

GenerateID creates unique operation IDs for the report.

type Metadata

type Metadata struct {
	Client Client `json:"client"`
}

type Operation

type Operation struct {
	// Operation's body
	// e.g. "query me { me { id name } }"
	Operation string `json:"operation"`
	// Name of the operation
	// e.g. "me"
	OperationName nullable.TrimmedString `json:"operationName,omitempty"`
	// Schema coordinates
	// e.g. ["Query", "Query.me", "User", "User.id", "User.name"]
	Fields []string `json:"fields"`
}

type OperationInfo

type OperationInfo struct {
	// The ID of the operation in the operations map
	ID string `json:"operationMapKey"`
	// UNIX time in miliseconds of the operation's execution start
	Timestamp int64     `json:"timestamp"`
	Execution Execution `json:"execution"`
	Metadata  Metadata  `json:"metadata"`
}

type OperationWithInfo

type OperationWithInfo struct {
	Operation
	OperationInfo
}

func OperationFromContext

func OperationFromContext(ctx context.Context) (operation *OperationWithInfo, exists bool)

type Report

type Report struct {
	// Number of operations being reported
	Size uint `json:"size"`
	// The executed operations
	Operations map[string]*Operation `json:"map"`
	// Info about each operation's execution
	OperationInfos []*OperationInfo `json:"operations"`
}

type SendReport

type SendReport func(ctx context.Context, endpoint, token string, report *Report) error

SendReport performs the actual report sending to GraphQL Hive.

type Tracer

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

func NewTracer

func NewTracer(token string, opts ...TracerOption) *Tracer

func (Tracer) ExtensionName

func (tracer Tracer) ExtensionName() string

func (Tracer) InterceptField

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

func (Tracer) InterceptResponse

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

InterceptResponse intercepts the incoming request.

func (Tracer) Validate

func (tracer Tracer) Validate(schema graphql.ExecutableSchema) error

type TracerOption

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

func WithEndpoint

func WithEndpoint(endpoint string) TracerOption

WithEndpoint sets the endpoint to where the reports are sent. Defaults to "https://app.graphql-hive.com/usage".

func WithGenerateID

func WithGenerateID(fn GenerateID) TracerOption

WithGenerateID sets the unique operation ID generator for the reports. Defaults to generating v4 UUIDs.

func WithSendReport

func WithSendReport(fn SendReport) TracerOption

WithSendReport sets the report sender to GraphQL Hive.

func WithSendReportTimeout

func WithSendReportTimeout(timeout time.Duration) TracerOption

WithSendReportTimeout sets the report sending debounce timeout. Executed operations will queue up and then be flushed/sent to GraphQL Hive after the timeout expires.