feat(graphql): add graphql-core integration #3878

mabdinur · 2022-06-28T18:31:40Z

Graphql Integration

Overview

This integration supports graphql-core 3 and graphql-core 2. It provides instrumentation for executing graphql queries using graphql.graphql(), graphql.graphql_sync(), graphql.execute(), and graphql.subscribe(). This integration also wraps the execution of graphql.parse() and graphql.validate() in a span.

Supports

All libraries which use graphql-core>=2.0 to execute queries are supported:

graphene>=2.0
strawberry>=0.16.0
ariadne>=0.9.0

Implementation Details

The graphql-core integration provides support for parsing, building, validating, and executing graphql schemas. It also provides additional insight into resolving GraphQLFields. This integration uses bytecode instrumentation to add tracing to graphql operations listed below.

When graphql.graphql() or graphql.graphql_sync (in graphql-core>=3) is called the following trace is produced:

span name: graphql.query, resource: graphql source string
- span name: graphql.parse, resource: graphql.parse
  converts the body of an incoming graphql request into a graphql document
- span name: graphql.validate, resource: graphql.validate
  ensures a graphql schema is syntactically correct and can be executed in a given context
- span name: graphql.execute, resource: graphql source string
  executes a valid graphql schema and returns a response
  - span name: graphql.resolve, resource: name of graphql field
  - span name: graphql.resolve, resource: name of graphql field
  - ........ (a span is produced for every resolved field)
    Graphql queries can be complex and often resolve multiple Graphql fields in single request. Instrumenting resolvers provides insight on the execution of individual graphql fields and can highlight bottlenecks in fetching specific types of data. However for some applications this can produce large traces.

Note: If a GraphqlError is raised while parsing or validating a graphql query then graphql.execute will not be called and instrumented. For this reason we add the graphql source string to the graphql.query span AND the graphql.execute span.

Disabling `graphql.resolve`

Graphql queries can be complex and can resolve a large number of graphql fields in one request. Many of the resolvers could provide little to no insight into the execution of the request (ex. if the default resolver is called). To simplify the flamegraph produced by the graphql integration users can set DD_TRACE_GRAPHQL_PATCH_RESOLVERS=False to disable resolver instrumentation.

Future Work

Add Span Tags

Add span tags to maintain feature parity with the .NET and javascript tracer.

ddtrace-js graphql integration: https://github.com/DataDog/dd-trace-js/tree/c9f82be2b256b2894d894e2eb49c331852b1262b/packages/datadog-plugin-graphql/src

Instrument Promises

In graphql-core>=2,<3, graphql.execute() can return a promise if the graphql.execute() is called with return_promise=True. This promise will execute the graphql query asynchronously. To fix this we need to start the graphql.execute span when the promise is fulfilled and NOT when the promise is created.
POC: 52ebd46

Refactor patching

#3878 (comment)

Testing strategy

Validate that the traces in the graphql snapshot tests produce meaningful data.
Ensure patch, execute, validate, and query operation are patched everywhere they are imported. Ex. graphql.execute(), graphql.execution.execute(), graphql.execution.execute.execute() or graphql.graphql.execute() should produce the same instrumentation.