feat(graphql): add graphql-core integration

[mabdinur]

Graphql-core Integration

Overview

This integration supports graphql-core 3 and graphql-core 2. By transitive dependencies executing graphql schemas in graphene>2.0 is also supported. This integration provides instrumentation for executing graphql queries using graphql.graphql(), graphql.graphql_sync(), graphql.execute(), and graphql.execution.execute(), graphql.execution.executor.execute(), graphql.execute_sync(), and graphql.execution.execute_sync().

Resolves #925.

Implementation Details

graphql-core this integration provides support for parsing, building, validating, and executing graphql schemas. It also provides additional insight into resolving GraphQLFields.

The methods listed below are the main parts of the public api which are fully supported by the ddtrace library. All other methods listed in graphql.init will not produce any instrumentation.

graphql.graphql() and graphql.graphql_sync()

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 a large number of spans.

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.

graphql.execute() and graphql.execution.execute()

When execute() is called the following trace is produced:

• span name: graphql.execute, resource: graphql source string
  • 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)

Note: graphql-core>=3.1 introduced execute_sync. Using graphql.execute_sync() and graphql.execution.execute_sync() should produce the same trace as graphql.execute().

Future Work

• add graphql.source, graphql.operation.type and graphql.operation.name span tags to maintain feature parity with the .NET tracer.
• instrument the execution of graphql subscriptions in graphql-core 3. Due to how we patch graphql.execution.executor.execute() in graphql-core 2 this version of the library generates graphql.execute and graphql.resolver spans when subscriptions are executed. For consistency we should extend this functionality to graphql-core 3 and offically support graphql subscriptions.
  • sample patching:

     # patch execute function used in subscribe
     if graphql_version < (3,0):
         # graphql.execution.executor.execute() is used in graphql.execution.executor.subscribe()
         # this method is patched above.
         pass
     elif graphql_version < (3,2):
         _w("graphql.subscription.subscribe", "execute", _traced_operation("graphql.execute"))
     else:
         _w("graphql.execution.subscribe", "execute", _traced_operation("graphql.execute"))
    

• write tests for executing graphql subscriptions (graphql-core 2 and graphql-core 3)

Checklist

• Added to the correct milestone.
• Tests provided or description of manual testing performed is included in the code or PR.
• Library documentation is updated.
• Corp site documentation is updated (link to the PR).

[mabdinur]

I plan to increase test coverage if this general approach looks good. I'll also add a sample django-graphene app with snapshot tests

[EtienneLamoureux]

I'm very excited for this change. Will instrumentation of all GraphQL APIs come free with using ddtrace-run or will we have to annotate the resolvers in some fashion?

[mabdinur]

I'm very excited for this change. Will instrumentation of all GraphQL APIs come free with using ddtrace-run or will we have to annotate the resolvers in some fashion?

Hi @EtienneLamoureux, thanks for reaching out. The current plan is to instrument all resolvers using ddtrace-run but this approach could be noisy for some customers. If we decide not to auto instrument all resolvers in the initial release of this integration you could use @tracer.wrap() to instrument individual resolvers.

Would you like to test out a POC of this integration and let us know what you think? We'd greatly appreciate any feedback.

[EtienneLamoureux]

Hi @mabdinur,

Manually tagging my resolvers is perfectly acceptable for my use-case, no problem.

And I'd gladly test a POC of this feature! What's the best way to get a hold of a build with it in it?

[mabdinur]

Hi @mabdinur,

Manually tagging my resolvers is perfectly acceptable for my use-case, no problem.

And I'd gladly test a POC of this feature! What's the best way to get a hold of a build with it in it?

Hey @EtienneLamoureux, sorry about the delay. Here's a link to our public slack channel: https://chat.datadoghq.com/. Feel free to join and we can continue our conversation there. Thanks again helping us test the graphql integration 😊

[mabdinur]

Instead of monkey patching resolve_field I could instead pass a trace middleware to graphql.execute(). This middleware would wrap resolvers in a span when ExecutionContext.resolve_field is called. Both approaches produce equivalent instrumentation. Although using a trace middleware could provide more accurate span durations it comes with some performance costs. We will need to iterated over existing middleware and apply the TracedResolverMiddleware everytime graphql.execute is called. I think the current monkey patching approach is easier to follow.

ex:

import graphql

class TracedResolverMiddleware(object):
    def resolve(self, next, root, info, **args):
        pin = Pin.get_from(graphql)
        if not pin or not pin.enabled():
            return next(root, info, **args)

        with pin.tracer.trace(
            name="graphql.resolve", 
            resource=info.field_name,
            service=trace_utils.int_service(pin, config.graphql),
            span_type=SpanTypes.WEB,
        ) as span:
            _init_span(span)
            return next(root, info, **args)

# wraps all resolvers in the schema
result = graphql.execute(schema, source, middleware=[TracedResolverMiddleware()])

[mabdinur]

The graphql integration will be introduced in the following PR: #3878