GraphQL: Capture user-provided error extension values (#4325)

* GraphQL: Report multiple query errors

* Update sig/datadog/tracing/contrib/graphql/ext.rbs

Co-authored-by: Ivo Anjo <ivo.anjo@datadoghq.com>

* Misc code reviews

* Revert gemfile

* GraphQL: Capture user-provided error extension values

* Update with code review

---------

Co-authored-by: Ivo Anjo <ivo.anjo@datadoghq.com>

Author: marcotc

docs/GettingStarted.md

@@ -883,6 +883,8 @@ The `instrument :graphql` method accepts the following parameters. Additional op
 | `with_unified_tracer`    | `DD_TRACE_GRAPHQL_WITH_UNIFIED_TRACER` | `Bool`   | (Recommended) Enable to instrument with `UnifiedTrace` tracer for `graphql` >= v2.2, **enabling support for Endpoints list** in the Service Catalog. `with_deprecated_tracer` has priority over this. Default is `false`, using `GraphQL::Tracing::DataDogTrace` instead. This option is disabled by default to maintain backwards compatibility, but **will become the default in `datadog` 3.0.0**. | `false` |
 | `with_deprecated_tracer` |                            | `Bool`   | (Not recommended) Enable to instrument with deprecated `GraphQL::Tracing::DataDogTracing`. This has priority over `with_unified_tracer`. Default is `false`, using `GraphQL::Tracing::DataDogTrace` instead | `false` |
 | `service_name`           |                            | `String` | Service name used for graphql instrumentation                                                                                                                                                                   | `'ruby-graphql'` |
+| `error_extensions` | `DD_TRACE_GRAPHQL_ERROR_EXTENSIONS` | `Array` | List of extension keys to include in the span event reported for GraphQL queries with errors. | `[]` |
+
 
 Once an instrumentation strategy is selected (`with_unified_tracer: true`, `with_deprecated_tracer: true`, or *no option set* which defaults to `GraphQL::Tracing::DataDogTrace`), it is not possible to change the instrumentation strategy in the same Ruby process.
 This is especially important for [auto instrumented applications](#rails-or-hanami-applications) because an automatic initial instrumentation is always applied at startup, thus such applications will always instrument GraphQL with the default strategy (`GraphQL::Tracing::DataDogTrace`).

lib/datadog/core/configuration/option_definition.rb

@@ -79,6 +79,8 @@ def deprecated_env(value)
             @deprecated_env = value
           end
 
+          # Invoked when the option is first read, and {#env} is defined.
+          # The block provided is only invoked if the environment variable is present (not-nil).
           def env_parser(&block)
             @env_parser = block
           end

lib/datadog/tracing/contrib/graphql/configuration/error_extension_env_parser.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Tracing
+    module Contrib
+      module GraphQL
+        module Configuration
+          # Parses the environment variable `DD_TRACE_GRAPHQL_ERROR_EXTENSIONS` for error extension names declaration.
+          class ErrorExtensionEnvParser
+            # Parses the environment variable `DD_TRACE_GRAPHQL_ERROR_EXTENSIONS` into an array of error extension names.
+            def self.call(values)
+              # Split by comma, remove leading and trailing whitespaces,
+              # remove empty values, and remove repeated values.
+              values.split(',').each(&:strip!).reject(&:empty?).uniq
+            end
+          end
+        end
+      end
+    end
+  end
+end

lib/datadog/tracing/contrib/graphql/configuration/settings.rb

@@ -2,6 +2,7 @@
 
 require_relative '../../configuration/settings'
 require_relative '../ext'
+require_relative 'error_extension_env_parser'
 
 module Datadog
   module Tracing
@@ -48,6 +49,15 @@ class Settings < Contrib::Configuration::Settings
               o.type :bool
               o.default false
             end
+
+            # Capture error extensions provided by the user in their GraphQL error responses.
+            # The extensions can be anything, so the user is responsible for ensuring they are safe to capture.
+            option :error_extensions do |o|
+              o.env Ext::ENV_ERROR_EXTENSIONS
+              o.type :array, nilable: false
+              o.default []
+              o.env_parser { |v| ErrorExtensionEnvParser.call(v) }
+            end
           end
         end
       end

lib/datadog/tracing/contrib/graphql/ext.rb

@@ -12,6 +12,7 @@ module Ext
           ENV_ANALYTICS_ENABLED = 'DD_TRACE_GRAPHQL_ANALYTICS_ENABLED'
           ENV_ANALYTICS_SAMPLE_RATE = 'DD_TRACE_GRAPHQL_ANALYTICS_SAMPLE_RATE'
           ENV_WITH_UNIFIED_TRACER = 'DD_TRACE_GRAPHQL_WITH_UNIFIED_TRACER'
+          ENV_ERROR_EXTENSIONS = 'DD_TRACE_GRAPHQL_ERROR_EXTENSIONS'
           SERVICE_NAME = 'graphql'
           TAG_COMPONENT = 'graphql'
 

lib/datadog/tracing/contrib/graphql/unified_trace.rb

@@ -199,23 +199,42 @@ def multiplex_resource(multiplex)
           # These are represented in the Datadog App as special GraphQL errors,
           # given their event name `dd.graphql.query.error`.
           def add_query_error_events(span, errors)
+            capture_extensions = Datadog.configuration.tracing[:graphql][:error_extensions]
             errors.each do |error|
-              e = Core::Error.build_from(error)
+              extensions = if !capture_extensions.empty? && (extensions = error.extensions)
+                             # Capture extensions, ensuring all values are primitives
+                             extensions.each_with_object({}) do |(key, value), hash|
+                               next unless capture_extensions.include?(key.to_s)
+
+                               value = case value
+                                       when TrueClass, FalseClass, Integer, Float
+                                         value
+                                       else
+                                         # Stringify anything that is not a boolean or a number
+                                         value.to_s
+                                       end
+
+                               hash["extensions.#{key}"] = value
+                             end
+                           else
+                             {}
+                           end
 
               # {::GraphQL::Error#to_h} returns the error formatted in compliance with the GraphQL spec.
               # This is an unwritten contract in the `graphql` library.
               # See for an example: https://github.com/rmosolgo/graphql-ruby/blob/0afa241775e5a113863766cce126214dee093464/lib/graphql/execution_error.rb#L32
-              err = error.to_h
+              graphql_error = error.to_h
+              error = Core::Error.build_from(error)
 
               span.span_events << Datadog::Tracing::SpanEvent.new(
                 Ext::EVENT_QUERY_ERROR,
-                attributes: {
-                  message: err['message'],
-                  type: e.type,
-                  stacktrace: e.backtrace,
-                  locations: serialize_error_locations(err['locations']),
-                  path: err['path'],
-                }
+                attributes: extensions.merge!(
+                  message: graphql_error['message'],
+                  type: error.type,
+                  stacktrace: error.backtrace,
+                  locations: serialize_error_locations(graphql_error['locations']),
+                  path: graphql_error['path'],
+                )
               )
             end
           end

sig/datadog/tracing/contrib/graphql/configuration/error_extension_env_parser.rbs

@@ -0,0 +1,13 @@
+module Datadog
+  module Tracing
+    module Contrib
+      module GraphQL
+        module Configuration
+          class ErrorExtensionEnvParser
+            def self.call: (string values) -> Array[string]
+          end
+        end
+      end
+    end
+  end
+end

sig/datadog/tracing/contrib/graphql/ext.rbs

@@ -10,6 +10,7 @@ module Datadog
           ENV_ANALYTICS_SAMPLE_RATE: "DD_TRACE_GRAPHQL_ANALYTICS_SAMPLE_RATE"
 
           ENV_WITH_UNIFIED_TRACER: "DD_TRACE_GRAPHQL_WITH_UNIFIED_TRACER"
+          ENV_ERROR_EXTENSIONS: "DD_TRACE_GRAPHQL_ERROR_EXTENSIONS"
           EVENT_QUERY_ERROR: "dd.graphql.query.error"
           SERVICE_NAME: "graphql"
 

spec/datadog/tracing/contrib/graphql/configuration/error_extension_env_parser_spec.rb

@@ -0,0 +1,42 @@
+require 'datadog/tracing/contrib/graphql/configuration/error_extension_env_parser'
+
+RSpec.describe Datadog::Tracing::Contrib::GraphQL::Configuration::ErrorExtensionEnvParser do
+  describe '.call' do
+    subject(:call) { described_class.call(value) }
+
+    context 'when value is an empty string' do
+      let(:value) { '' }
+      it 'returns an empty array' do
+        is_expected.to eq([])
+      end
+    end
+
+    context 'when value contains multiple commas' do
+      let(:value) { 'foo,bar,baz' }
+      it 'returns an array with split values' do
+        is_expected.to eq(['foo', 'bar', 'baz'])
+      end
+    end
+
+    context 'when value contains leading and trailing whitespace' do
+      let(:value) { ' foo  , bar   , baz ' }
+      it 'removes whitespace around values' do
+        is_expected.to eq(['foo', 'bar', 'baz'])
+      end
+    end
+
+    context 'when value contains empty elements' do
+      let(:value) { ',foo,,bar,,baz,' }
+      it 'removes the empty elements' do
+        is_expected.to eq(['foo', 'bar', 'baz'])
+      end
+    end
+
+    context 'when value contains repeated elements' do
+      let(:value) { 'foo,foo' }
+      it 'remove repeated elements' do
+        is_expected.to eq(['foo'])
+      end
+    end
+  end
+end

spec/datadog/tracing/contrib/graphql/configuration/settings_spec.rb

@@ -80,4 +80,36 @@
       end
     end
   end
+
+  describe 'error_extensions' do
+    context 'when default' do
+      it do
+        settings = described_class.new
+
+        expect(settings.error_extensions).to eq([])
+      end
+    end
+
+    context 'when given an array' do
+      it do
+        error_extension = double
+
+        settings = described_class.new(error_extensions: [error_extension])
+
+        expect(settings.error_extensions).to eq([error_extension])
+      end
+
+      context 'via the environment variable' do
+        it do
+          error_extension = 'foo,bar'
+
+          ClimateControl.modify('DD_TRACE_GRAPHQL_ERROR_EXTENSIONS' => error_extension) do
+            settings = described_class.new
+
+            expect(settings.error_extensions).to eq(['foo', 'bar'])
+          end
+        end
+      end
+    end
+  end
 end

spec/datadog/tracing/contrib/graphql/test_schema_examples.rb

@@ -35,11 +35,13 @@ class #{prefix}TestGraphQLSchema < ::GraphQL::Schema
 
       rescue_from(RuntimeError) do |err, obj, args, ctx, field|
         raise GraphQL::ExecutionError.new(err.message, extensions: {
-          'int-1': 1,
-          'str-1': '1',
-          'array-1-2': [1,'2'],
-          '': 'empty string',
-          ',': 'comma',
+          'int': 1,
+          'bool': true,
+          'str': '1',
+          'array-1-2': [1, '2'],
+          'hash-a-b': {a: 'b'},
+          'object': ::Object.new,
+          'extra-int': 2, # This should not be included
         })
       end
     end
@@ -193,5 +195,36 @@ def unload_test_schema(prefix: '')
         )
       )
     end
+
+    context 'with error extension capture enabled' do
+      around do |ex|
+        ClimateControl.modify('DD_TRACE_GRAPHQL_ERROR_EXTENSIONS' => 'int,str,bool,array-1-2,hash-a-b,object') { ex.run }
+      end
+
+      it 'creates query span for error with extensions' do
+        expect(result.to_h['errors'][0]['message']).to eq('GraphQL error')
+
+        expect(graphql_execute.events[0]).to match(
+          a_span_event_with(
+            name: 'dd.graphql.query.error',
+            attributes: {
+              'path' => ['err1'],
+              'locations' => ['1:14'],
+              'message' => 'GraphQL error',
+              'type' => 'GraphQL::ExecutionError',
+              'stacktrace' => include(__FILE__),
+              'extensions.int' => 1,
+              'extensions.bool' => true,
+              'extensions.str' => '1',
+              'extensions.array-1-2' => '[1, "2"]',
+              'extensions.hash-a-b' => { a: 'b' }.to_s, # Hash#to_s changes per Ruby version: 3.3: '{:a=>1}', 3.4: '{a: 1}'
+              'extensions.object' => start_with('#<Object:'),
+            }
+          )
+        )
+
+        expect(graphql_execute.events[0].attributes).to_not include('extensions.extra-int')
+      end
+    end
   end
 end