GraphQL Integration
Instrument GraphQL APIs with one plugin. Resolver-level tracing, query complexity analysis, field-level latency, and N+1 detection — across every major GraphQL server.
How It Works
Install the npm Package
Run npm install @tigerops/graphql. The package provides plugins for Apollo Server, Yoga Server, Mercurius (Fastify), and envelop. It also supports graphql-ruby, graphql-java, Strawberry (Python), and Ariadne via separate language-specific packages.
Add the Plugin or Middleware
For Apollo Server 4+, pass the TigerOps Apollo plugin to the plugins array. For GraphQL Yoga, add the useTigerOps() envelop plugin. For Mercurius, register the fastify-tigerops-graphql plugin after Mercurius registration.
Set Environment Variables
Set TIGEROPS_API_KEY, TIGEROPS_SERVICE_NAME, and TIGEROPS_ENVIRONMENT. The plugin reads these at server startup. For monorepos with multiple GraphQL schemas, set TIGEROPS_SERVICE_NAME per schema to differentiate traces in TigerOps.
Resolver Traces, Complexity & N+1 Alerts
Within seconds TigerOps receives per-resolver spans with field path, parent type, execution time, and error flag. Query complexity scores and N+1 dataloader batch counts are reported as metrics alongside resolver trace data.
What You Get Out of the Box
Resolver-Level Tracing
Every GraphQL resolver execution becomes a child span named with the full field path (Query.users.orders.items). Resolver type (Query, Mutation, Subscription, or field), parent type name, and return type are recorded as span attributes.
Query Complexity Analysis
Query depth, field count, and computed complexity score are recorded on the root operation span. Queries exceeding configured complexity thresholds are flagged automatically. The parsed query AST is hashed and used as a stable operation ID.
Field-Level Latency Metrics
P50, P95, and P99 resolver latency is tracked per field path across all queries. Field-level latency percentile histograms are surfaced in TigerOps dashboards to pinpoint slow resolvers without examining individual trace waterfall views.
N+1 Query Detection
DataLoader batch counts and individual load calls are tracked per resolver invocation. When a resolver triggers more than one individual load instead of a batched call, TigerOps fires an N+1 alert with the field path and batch ratio.
Persisted Query & Operation Tracking
Automatic persisted queries (APQ) and named operation tracking associate traces with stable operation names. Operation name, variables (redacted by default), and query hash are recorded on root spans for grouping in TigerOps.
Subscription & Streaming Support
GraphQL subscriptions create a long-lived root span that records subscribe, unsubscribe, and event emission events. Deferred fragments (@defer) and incremental delivery (@stream) create separate child spans per delivered payload.
Install & Initialize
One npm install. One plugin entry. Full GraphQL resolver observability.
# Install the TigerOps GraphQL package
npm install @tigerops/graphql
# Set environment variables
export TIGEROPS_API_KEY="your-api-key"
export TIGEROPS_SERVICE_NAME="my-graphql-api"
export TIGEROPS_ENVIRONMENT="production"
// server.ts — Apollo Server 4
import { ApolloServer } from '@apollo/server'
import { tigeropsApolloPlugin } from '@tigerops/graphql'
const server = new ApolloServer({
typeDefs,
resolvers,
plugins: [
tigeropsApolloPlugin({
apiKey: process.env.TIGEROPS_API_KEY,
serviceName: process.env.TIGEROPS_SERVICE_NAME,
complexityThreshold: 500, // alert on queries above this
captureQueryDocument: false, // never capture raw query text
traceIntrospection: false, // skip __schema queries
excludeOperations: ['HealthCheck'],
}),
],
})
// Yoga Server — use envelop plugin
import { createYoga } from 'graphql-yoga'
import { useTigerOps } from '@tigerops/graphql/yoga'
const yoga = createYoga({
schema,
plugins: [
useTigerOps({ apiKey: process.env.TIGEROPS_API_KEY }),
],
})Common Questions
Which GraphQL server libraries are supported?
Apollo Server 4.x, GraphQL Yoga 3.x/4.x, Mercurius (Fastify), Hot Chocolate (.NET), graphql-ruby, graphql-java, Strawberry (Python), and Ariadne (Python) are all supported. The envelop plugin works with any envelop-compatible server.
Does TigerOps capture GraphQL variables or query strings?
By default, TigerOps records the operation name, query hash, and query depth only. Full query document strings and variable values are not captured. You can opt in to recording the normalized query document (with literals replaced by types) using captureQueryDocument: true.
How does TigerOps handle GraphQL errors vs. partial responses?
HTTP-level errors and resolver-level GraphQL errors are handled separately. Resolver errors are recorded as span events on the field span with the error message and path. Partial success responses (data + errors) are marked with a PARTIAL status distinct from full errors.
Can TigerOps trace federated GraphQL schemas (Apollo Federation)?
Yes. The @tigerops/graphql-gateway package instruments the Apollo Router and Apollo Gateway. Subgraph fetch spans are linked to the originating gateway query span so the full federated query trace is visible end-to-end across subgraphs.
How do I exclude introspection queries from traces?
Introspection queries (__schema, __type) are excluded by default. Set traceIntrospection: true in plugin options to include them. Health check queries using a custom operation name can be excluded via the excludeOperations: ["HealthCheck"] option.
Full GraphQL Observability in One Plugin Install
Resolver traces, complexity analysis, field-level latency, N+1 detection, and subscription tracing — across every major GraphQL server.