GraphQL: Capture user-provided error extension values

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 | `false` |
 | `with_deprecated_tracer` |                            | `Bool`   | 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 extensions 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/tracing/contrib/graphql/configuration/error_extension_env_parser.rb

@@ -0,0 +1,23 @@
+# 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)
+              return unless 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(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

@@ -196,10 +196,30 @@ 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)
               err = error.to_h
 
+              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
+
               span.span_events << Datadog::Tracing::SpanEvent.new(
                 Ext::EVENT_QUERY_ERROR,
                 attributes: {
@@ -208,6 +228,7 @@ def add_query_error_events(span, errors)
                   stacktrace: e.backtrace,
                   locations: serialize_error_locations(err['locations']),
                   path: err['path'],
+                  **extensions
                 }
               )
             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: string
+          ENV_ERROR_EXTENSIONS: string
           EVENT_QUERY_ERROR: String
           SERVICE_NAME: "graphql"
 

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

@@ -0,0 +1,49 @@
+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 nil' do
+      let(:value) { nil }
+      it 'returns nil' do
+        is_expected.to be_nil
+      end
+    end
+
+    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,24 @@
       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
+    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
@@ -183,5 +185,40 @@ def unload_test_schema(prefix: '')
         )
       )
     end
+
+    context 'with error extension capture enabled' do
+      before do
+        Datadog.configure do |c|
+          c.tracing.instrument :graphql, error_extensions: ['int', 'str', 'bool', 'array-1-2', 'hash-a-b', 'object']
+        end
+      end
+
+      after { Datadog.configuration.tracing[:graphql].reset! }
+
+      it 'creates query span for error with extensions' do
+        expect(result.to_h['errors'][0]['message']).to eq('GraphQL error')
+
+        expect(graphql_execute.events).to contain_exactly(
+          a_span_event_with(
+            name: 'dd.graphql.query.error',
+            attributes: {
+              'message' => 'GraphQL error',
+              'type' => 'GraphQL::ExecutionError',
+              'stacktrace' => include(__FILE__),
+              'locations' => ['1:14'],
+              'path' => ['graphqlError'],
+              'extensions.int' => 1,
+              'extensions.bool' => true,
+              'extensions.str' => '1',
+              'extensions.array-1-2' => '[1, "2"]',
+              'extensions.hash-a-b' => '{:a=>"b"}',
+              'extensions.object' => start_with('#<Object:'),
+            }
+          )
+        )
+
+        expect(graphql_execute.events[0].attributes).to_not include('extensions.extra-int')
+      end
+    end
   end
 end