graphql

Documentation

Overview

Package graphql provides GraphQL-over-HTTP telemetry helpers for cf_http.

This package works with any GraphQL server that implements http.Handler (gqlgen, graph-gophers, etc.). It does not depend on any specific GraphQL library.

Index

• Constants
• func Metrics(server *cf_http.Server, opts ...Option) func(http.Handler) http.Handler
• func Middleware() func(http.Handler) http.Handler
• func OperationNameFrom(ctx context.Context) string
• func RecordResolver(server *cf_http.Server, operation, resolver string, status int, ...)
• func WithOperationName(ctx context.Context, operationName string) context.Context
• type OperationMetrics
  • func StartOperation(server *cf_http.Server, operation string) *OperationMetrics
  • func (m *OperationMetrics) End(status int)
• type Option
  • func AllOperations() Option
  • func OnlyOperations(ops ...string) Option
  • func WithMaxBodySize(size int64) Option
  • func WithOtherBucket() Option
  • func WithPeekWindow(size int64) Option

Constants

const (
	// DefaultPeekWindow is how many leading POST body bytes Metrics inspects
	// for operationName when WithPeekWindow is not set (8 KiB).
	DefaultPeekWindow int64 = 8 << 10
)

Functions

func Metrics

func Metrics(server *cf_http.Server, opts ...Option) func(http.Handler) http.Handler

Metrics records GraphQL operation metrics. By default, it does NOT track any operations. Use OnlyOperations to specify which operations should be tracked. Operations not in the allowlist are not recorded unless WithOtherBucket (bounded "other" label) or AllOperations (every name — DANGEROUS, see its doc) is used.

When tracking is enabled, POST operationName extraction uses a bounded peek window (see WithPeekWindow) — see package docs / README.

func Middleware

func Middleware() func(http.Handler) http.Handler

Middleware provides a way to extract operation names from GraphQL libraries that don't automatically expose them. Use this in your GraphQL handler to ensure operation names are available for metrics.

func OperationNameFrom

func OperationNameFrom(ctx context.Context) string

OperationNameFrom extracts the operation name from the request context.

func RecordResolver

func RecordResolver(server *cf_http.Server, operation, resolver string, status int, duration time.Duration)

RecordResolver records a GraphQL resolver metric. This is a hook for GraphQL libraries to report resolver-level metrics.

func WithOperationName

func WithOperationName(ctx context.Context, operationName string) context.Context

WithOperationName stores the operation name in the request context.

Types

type OperationMetrics

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

OperationMetrics provides a simple way to track operation metrics from within a GraphQL resolver or handler.

func StartOperation

func StartOperation(server *cf_http.Server, operation string) *OperationMetrics

StartOperation begins tracking a GraphQL operation.

func (*OperationMetrics) End

func (m *OperationMetrics) End(status int)

End records the operation metric with the given status.

type Option

type Option func(*config)

Option configures GraphQL metrics.

func AllOperations

func AllOperations() Option

AllOperations tracks every detected operation name. DANGEROUS: operation names are client-controlled, so this is a public cardinality-abuse vector and a self-inflicted DoS. Prefer OnlyOperations, optionally with WithOtherBucket. Documented as an escape hatch only — do not enable on public endpoints.

func OnlyOperations

func OnlyOperations(ops ...string) Option

OnlyOperations restricts metrics to the specified operation names. Only these operations will be tracked. This is the primary way to enable GraphQL metrics.

func WithMaxBodySize

func WithMaxBodySize(size int64) Option

WithMaxBodySize is an alias for WithPeekWindow (historical name).

func WithOtherBucket

func WithOtherBucket() Option

WithOtherBucket enables tracking of operations not in the allowlist under the "other" label. Use with caution as this can still lead to unbounded cardinality if there are many unique operation names.

func WithPeekWindow

func WithPeekWindow(size int64) Option

WithPeekWindow sets how many leading POST body bytes Metrics may inspect when extracting operationName after the Content-Type preflight.

• omit (default): DefaultPeekWindow (8 KiB) — safe for public endpoints
• n > 0: peek at most n bytes, then stop
• 0: read the entire body for extraction (explicit opt-in; costly on large uploads — prefer keeping operationName near the start of the JSON)

The peeked/read prefix is always restored for the downstream handler.