@opentelemetry/instrumentation-graphql

What is @opentelemetry/instrumentation-graphql?

@opentelemetry/instrumentation-graphql is an npm package that provides automatic tracing and monitoring for GraphQL operations using OpenTelemetry. It helps in capturing performance metrics, tracing GraphQL queries, mutations, and resolvers, and integrating these metrics with various observability backends.

What are @opentelemetry/instrumentation-graphql's main functionalities?

Automatic Tracing of GraphQL Operations

This feature allows you to automatically trace GraphQL operations such as queries and mutations. The code sample demonstrates how to set up the GraphQL instrumentation with OpenTelemetry's NodeTracerProvider.

const { GraphQLInstrumentation } = require('@opentelemetry/instrumentation-graphql');
const { NodeTracerProvider } = require('@opentelemetry/node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');

const provider = new NodeTracerProvider();
provider.register();

registerInstrumentations({
  instrumentations: [
    new GraphQLInstrumentation({
      // Configuration options
    })
  ],
  tracerProvider: provider,
});

Custom Span Naming

This feature allows you to customize the names of the spans created for GraphQL operations. The code sample shows how to rename the root span based on the operation name.

const { GraphQLInstrumentation } = require('@opentelemetry/instrumentation-graphql');

const graphqlInstrumentation = new GraphQLInstrumentation({
  mergeItems: true,
  renameRootSpan: (operation) => `graphql-${operation.operationName}`,
});

Capture Resolver Spans

This feature enables capturing spans for individual resolvers within a GraphQL operation. The code sample demonstrates how to configure the instrumentation to capture resolver spans up to a certain depth.

const { GraphQLInstrumentation } = require('@opentelemetry/instrumentation-graphql');

const graphqlInstrumentation = new GraphQLInstrumentation({
  allowValues: true,
  depth: 2,
});

Other packages similar to @opentelemetry/instrumentation-graphql

apollo-opentracing

apollo-opentracing is a package that integrates OpenTracing with Apollo Server to provide tracing for GraphQL operations. It is similar to @opentelemetry/instrumentation-graphql but uses the OpenTracing API instead of OpenTelemetry.

graphql-metrics

graphql-metrics is a package that provides performance monitoring and metrics for GraphQL servers. It focuses on capturing and reporting metrics such as response times and error rates, similar to @opentelemetry/instrumentation-graphql but without the full tracing capabilities.

graphql-extensions

graphql-extensions is a package that allows you to extend the functionality of your GraphQL server with custom extensions, including performance monitoring and tracing. It provides a more flexible but less integrated approach compared to @opentelemetry/instrumentation-graphql.

README

OpenTelemetry Instrumentation GraphQL

This module provides automated instrumentation and tracing for GraphQL in Node.js applications.

Note: graphql plugin instruments graphql directly. it should work with any package that wraps the graphql package (e.g apollo).

Compatible with OpenTelemetry JS API and SDK 1.0+.

Installation

npm install @opentelemetry/instrumentation-graphql

Supported Versions

>=14 <16

Usage

'use strict';

const { GraphQLInstrumentation } = require('@opentelemetry/instrumentation-graphql');
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');

const provider = new NodeTracerProvider();
provider.register();

registerInstrumentations({
  instrumentations: [
    new GraphQLInstrumentation({
    // optional params
      // allowValues: true,
      // depth: 2,
      // mergeItems: true,
    }),
  ],
});

Optional Parameters

Param	type	Default Value	Description
mergeItems	boolean	false	Whether to merge list items into a single element. example: users.*.name instead of users.0.name, users.1.name
depth	number	-1	The maximum depth of fields/resolvers to instrument. When set to 0 it will not instrument fields and resolvers. When set to -1 it will instrument all fields and resolvers.
allowValues	boolean	false	When set to true it will not remove attributes values from schema source. By default all values that can be sensitive are removed and replaced with "*"
responseHook	GraphQLInstrumentationExecutionResponseHook	undefined	Hook that allows adding custom span attributes based on the data returned from "execute" GraphQL action.

Examples

Can be found here

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.