graphql 2.4.9 → 2.4.11

data/lib/graphql/schema/member/has_dataloader.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module GraphQL
+  class Schema
+    class Member
+      module HasDataloader
+        # @return [GraphQL::Dataloader] The dataloader for the currently-running query
+        def dataloader
+          context.dataloader
+        end
+
+        # A shortcut method for loading a key from a source.
+        # Identical to `dataloader.with(source_class, *source_args).load(load_key)`
+        # @param source_class [Class<GraphQL::Dataloader::Source>]
+        # @param source_args [Array<Object>] Any extra parameters defined in `source_class`'s `initialize` method
+        # @param load_key [Object] The key to look up using `def fetch`
+        def dataload(source_class, *source_args, load_key)
+          dataloader.with(source_class, *source_args).load(load_key)
+        end
+
+        # Find an object with ActiveRecord via {Dataloader::ActiveRecordSource}.
+        # @param model [Class<ActiveRecord::Base>]
+        # @param find_by_value [Object] Usually an `id`, might be another value if `find_by:` is also provided
+        # @param find_by [Symbol, String] A column name to look the record up by. (Defaults to the model's primary key.)
+        # @return [ActiveRecord::Base, nil]
+        # @example Finding a record by ID
+        #   dataload_record(Post, 5) # Like `Post.find(5)`, but dataloaded
+        # @example Finding a record by another attribute
+        #   dataload_record(User, "matz", find_by: :handle) # Like `User.find_by(handle: "matz")`, but dataloaded
+        def dataload_record(model, find_by_value, find_by: nil)
+          source = if find_by
+            dataloader.with(Dataloader::ActiveRecordSource, model, find_by: find_by)
+          else
+            dataloader.with(Dataloader::ActiveRecordSource, model)
+          end
+
+          source.load(find_by_value)
+        end
+
+        # Look up an associated record using a Rails association.
+        # @param association_name [Symbol] A `belongs_to` or `has_one` association. (If a `has_many` association is named here, it will be selected without pagination.)
+        # @param record [ActiveRecord::Base] The object that the association belongs to.
+        # @param scope [ActiveRecord::Relation] A scope to look up the associated record in
+        # @return [ActiveRecord::Base, nil] The associated record, if there is one
+        # @example Looking up a belongs_to on the current object
+        #    dataload_association(:parent) # Equivalent to `object.parent`, but dataloaded
+        # @example Looking up an associated record on some other object
+        #    dataload_association(:post, comment) # Equivalent to `comment.post`, but dataloaded
+        def dataload_association(record = object, association_name, scope: nil)
+          source = if scope
+            dataloader.with(Dataloader::ActiveRecordAssociationSource, association_name, scope)
+          else
+            dataloader.with(Dataloader::ActiveRecordAssociationSource, association_name)
+          end
+          source.load(record)
+        end
+      end
+    end
+  end
+end

data/lib/graphql/schema/member.rb

@@ -2,6 +2,7 @@
 require 'graphql/schema/member/base_dsl_methods'
 require 'graphql/schema/member/graphql_type_names'
 require 'graphql/schema/member/has_ast_node'
+require 'graphql/schema/member/has_dataloader'
 require 'graphql/schema/member/has_directives'
 require 'graphql/schema/member/has_deprecation_reason'
 require 'graphql/schema/member/has_interfaces'

data/lib/graphql/schema/object.rb

@@ -7,6 +7,7 @@ module GraphQL
     class Object < GraphQL::Schema::Member
       extend GraphQL::Schema::Member::HasFields
       extend GraphQL::Schema::Member::HasInterfaces
+      include Member::HasDataloader
 
       # Raised when an Object doesn't have any field defined and hasn't explicitly opted out of this requirement
       class FieldsAreRequiredError < GraphQL::Error
@@ -65,20 +66,28 @@ module GraphQL
         # @return [GraphQL::Schema::Object, GraphQL::Execution::Lazy]
         # @raise [GraphQL::UnauthorizedError] if the user-provided hook returns `false`
         def authorized_new(object, context)
-          maybe_lazy_auth_val = context.query.current_trace.authorized(query: context.query, type: self, object: object) do
-            begin
-              authorized?(object, context)
-            rescue GraphQL::UnauthorizedError => err
-              context.schema.unauthorized_object(err)
-            rescue StandardError => err
-              context.query.handle_or_reraise(err)
+          context.query.current_trace.begin_authorized(self, object, context)
+          begin
+            maybe_lazy_auth_val = context.query.current_trace.authorized(query: context.query, type: self, object: object) do
+              begin
+                authorized?(object, context)
+              rescue GraphQL::UnauthorizedError => err
+                context.schema.unauthorized_object(err)
+              rescue StandardError => err
+                context.query.handle_or_reraise(err)
+              end
             end
+          ensure
+            context.query.current_trace.end_authorized(self, object, context, maybe_lazy_auth_val)
           end
 
           auth_val = if context.schema.lazy?(maybe_lazy_auth_val)
             GraphQL::Execution::Lazy.new do
+              context.query.current_trace.begin_authorized(self, object, context)
               context.query.current_trace.authorized_lazy(query: context.query, type: self, object: object) do
-                context.schema.sync_lazy(maybe_lazy_auth_val)
+                res = context.schema.sync_lazy(maybe_lazy_auth_val)
+                context.query.current_trace.end_authorized(self, object, context, res)
+                res
               end
             end
           else

data/lib/graphql/schema/resolver.rb

@@ -28,6 +28,7 @@ module GraphQL
       include Schema::Member::HasPath
       extend Schema::Member::HasPath
       extend Schema::Member::HasDirectives
+      include Schema::Member::HasDataloader
 
       # @param object [Object] The application object that this field is being resolved on
       # @param context [GraphQL::Query::Context]
@@ -50,11 +51,6 @@ module GraphQL
       # @return [GraphQL::Query::Context]
       attr_reader :context
 
-      # @return [GraphQL::Dataloader]
-      def dataloader
-        context.dataloader
-      end
-
       # @return [GraphQL::Schema::Field]
       attr_reader :field
 

data/lib/graphql/schema/visibility/profile.rb

@@ -18,7 +18,7 @@ module GraphQL
           if ctx.respond_to?(:types) && (types = ctx.types).is_a?(self)
             types
           else
-            schema.visibility.profile_for(ctx, nil)
+            schema.visibility.profile_for(ctx)
           end
         end
 
@@ -319,9 +319,9 @@ module GraphQL
           case type.kind.name
           when "INTERFACE"
             pts = []
-            @schema.visibility.all_interface_type_memberships[type].each do |itm|
-              if @cached_visible[itm] && (ot = itm.object_type) && @cached_visible[ot] && referenced?(ot)
-                pts << ot
+            @schema.visibility.all_interface_type_memberships[type].each do |(itm, impl_type)|
+              if @cached_visible[itm] && @cached_visible[impl_type] && referenced?(impl_type)
+                pts << impl_type
               end
             end
             pts

data/lib/graphql/schema/visibility.rb

@@ -13,6 +13,10 @@ module GraphQL
       # @param preload [Boolean] if `true`, load the default schema profile and all named profiles immediately (defaults to `true` for `Rails.env.production?`)
       # @param migration_errors [Boolean] if `true`, raise an error when `Visibility` and `Warden` return different results
       def self.use(schema, dynamic: false, profiles: EmptyObjects::EMPTY_HASH, preload: (defined?(Rails) ? Rails.env.production? : nil), migration_errors: false)
+        profiles&.each { |name, ctx|
+          ctx[:visibility_profile] = name
+          ctx.freeze
+        }
         schema.visibility = self.new(schema, dynamic: dynamic, preload: preload, profiles: profiles, migration_errors: migration_errors)
         if preload
           schema.visibility.preload
@@ -81,8 +85,7 @@ module GraphQL
         types_to_visit.compact!
         ensure_all_loaded(types_to_visit)
         @profiles.each do |profile_name, example_ctx|
-          example_ctx[:visibility_profile] = profile_name
-          prof = profile_for(example_ctx, profile_name)
+          prof = profile_for(example_ctx)
           prof.all_types # force loading
         end
       end
@@ -145,7 +148,7 @@ module GraphQL
 
       attr_reader :cached_profiles
 
-      def profile_for(context, visibility_profile)
+      def profile_for(context, visibility_profile = context[:visibility_profile])
         if !@profiles.empty?
           if visibility_profile.nil?
             if @dynamic
@@ -160,7 +163,8 @@ module GraphQL
           elsif !@profiles.include?(visibility_profile)
             raise ArgumentError, "`#{visibility_profile.inspect}` isn't allowed for `visibility_profile:` (must be one of #{@profiles.keys.map(&:inspect).join(", ")}). Or, add `#{visibility_profile.inspect}` to the list of profiles in the schema definition."
           else
-            @cached_profiles[visibility_profile] ||= @schema.visibility_profile_class.new(name: visibility_profile, context: context, schema: @schema)
+            profile_ctx = @profiles[visibility_profile]
+            @cached_profiles[visibility_profile] ||= @schema.visibility_profile_class.new(name: visibility_profile, context: profile_ctx, schema: @schema)
           end
         elsif context.is_a?(Query::NullContext)
           top_level_profile
@@ -222,7 +226,9 @@ module GraphQL
               elsif member.respond_to?(:interface_type_memberships)
                 member.interface_type_memberships.each do |itm|
                   @all_references[itm.abstract_type] << member
-                  @interface_type_memberships[itm.abstract_type] << itm
+                  # `itm.object_type` may not actually be `member` if this implementation
+                  # is inherited from a superclass
+                  @interface_type_memberships[itm.abstract_type] << [itm, member]
                 end
               elsif member < GraphQL::Schema::Union
                 @unions_for_references << member
@@ -271,13 +277,12 @@ module GraphQL
 
         # TODO: somehow don't iterate over all these,
         # only the ones that may have been modified
-        @interface_type_memberships.each do |int_type, type_memberships|
+        @interface_type_memberships.each do |int_type, type_membership_pairs|
           referers = @all_references[int_type].select { |r| r.is_a?(GraphQL::Schema::Field) }
           if !referers.empty?
-            type_memberships.each do |type_membership|
-              implementor_type = type_membership.object_type
+            type_membership_pairs.each do |(type_membership, impl_type)|
               # Add new items only:
-              @all_references[implementor_type] |= referers
+              @all_references[impl_type] |= referers
             end
           end
         end

data/lib/graphql/schema.rb

@@ -7,7 +7,6 @@ require "graphql/schema/find_inherited_value"
 require "graphql/schema/finder"
 require "graphql/schema/introspection_system"
 require "graphql/schema/late_bound_type"
-require "graphql/schema/null_mask"
 require "graphql/schema/timeout"
 require "graphql/schema/type_expression"
 require "graphql/schema/unique_within_type"
@@ -1115,9 +1114,6 @@ module GraphQL
 
       # @api private
       def handle_or_reraise(context, err)
-        if context[:backtrace] || using_backtrace
-          err = GraphQL::Backtrace::TracedError.new(err, context)
-        end
         handler = Execution::Errors.find_handler_for(self, err.class)
         if handler
           obj = context[:current_object]
@@ -1129,6 +1125,10 @@ module GraphQL
           end
           handler[:handler].call(err, obj, args, context, field)
         else
+          if (context[:backtrace] || using_backtrace) && !err.is_a?(GraphQL::ExecutionError)
+            err = GraphQL::Backtrace::TracedError.new(err, context)
+          end
+
           raise err
         end
       end
@@ -1298,7 +1298,10 @@ module GraphQL
       def type_error(type_error, ctx)
         case type_error
         when GraphQL::InvalidNullError
-          ctx.errors << type_error
+          execution_error = GraphQL::ExecutionError.new(type_error.message, ast_node: type_error.ast_node)
+          execution_error.path = ctx[:current_path]
+
+          ctx.errors << execution_error
         when GraphQL::UnresolvedTypeError, GraphQL::StringEncodingError, GraphQL::IntegerEncodingError
           raise type_error
         when GraphQL::IntegerDecodingError
@@ -1366,6 +1369,16 @@ module GraphQL
         }.freeze
       end
 
+      # @return [GraphQL::Tracing::DetailedTrace] if it has been configured for this schema
+      attr_accessor :detailed_trace
+
+      # @param query [GraphQL::Query, GraphQL::Execution::Multiplex] Called with a multiplex when multiple queries are executed at once (with {.multiplex})
+      # @return [Boolean] When `true`, save a detailed trace for this query.
+      # @see Tracing::DetailedTrace DetailedTrace saves traces when this method returns true
+      def detailed_trace?(query)
+        raise "#{self} must implement `def.detailed_trace?(query)` to use DetailedTrace. Implement this method in your schema definition."
+      end
+
       def tracer(new_tracer, silence_deprecation_warning: false)
         if !silence_deprecation_warning
           warn("`Schema.tracer(#{new_tracer.inspect})` is deprecated; use module-based `trace_with` instead. See: https://graphql-ruby.org/queries/tracing.html")
@@ -1383,14 +1396,22 @@ module GraphQL
         find_inherited_value(:tracers, EMPTY_ARRAY) + own_tracers
       end
 
-      # Mix `trace_mod` into this schema's `Trace` class so that its methods
-      # will be called at runtime.
+      # Mix `trace_mod` into this schema's `Trace` class so that its methods will be called at runtime.
+      #
+      # You can attach a module to run in only _some_ circumstances by using `mode:`. When a module is added with `mode:`,
+      # it will only run for queries with a matching `context[:trace_mode]`.
+      #
+      # Any custom trace modes _also_ include the default `trace_with ...` modules (that is, those added _without_ any particular `mode: ...` configuration).
+      #
+      # @example Adding a trace in a special mode
+      #   # only runs when `query.context[:trace_mode]` is `:special`
+      #   trace_with SpecialTrace, mode: :special
       #
       # @param trace_mod [Module] A module that implements tracing methods
       # @param mode [Symbol] Trace module will only be used for this trade mode
       # @param options [Hash] Keywords that will be passed to the tracing class during `#initialize`
       # @return [void]
-      # @see GraphQL::Tracing::Trace for available tracing methods
+      # @see GraphQL::Tracing::Trace Tracing::Trace for available tracing methods
       def trace_with(trace_mod, mode: :default, **options)
         if mode.is_a?(Array)
           mode.each { |m| trace_with(trace_mod, mode: m, **options) }
@@ -1440,12 +1461,33 @@ module GraphQL
       #
       # If no `mode:` is given, then {default_trace_mode} will be used.
       #
+      # If this schema is using {Tracing::DetailedTrace} and {.detailed_trace?} returns `true`, then
+      # DetailedTrace's mode will override the passed-in `mode`.
+      #
       # @param mode [Symbol] Trace modules for this trade mode will be included
       # @param options [Hash] Keywords that will be passed to the tracing class during `#initialize`
       # @return [Tracing::Trace]
       def new_trace(mode: nil, **options)
-        target = options[:query] || options[:multiplex]
-        mode ||= target && target.context[:trace_mode]
+        should_sample = if detailed_trace
+          if (query = options[:query])
+            detailed_trace?(query)
+          elsif (multiplex = options[:multiplex])
+            if multiplex.queries.length == 1
+              detailed_trace?(multiplex.queries.first)
+            else
+              detailed_trace?(multiplex)
+            end
+          end
+        else
+          false
+        end
+
+        if should_sample
+          mode = detailed_trace.trace_mode
+        else
+          target = options[:query] || options[:multiplex]
+          mode ||= target && target.context[:trace_mode]
+        end
 
         trace_mode = mode || default_trace_mode
         base_trace_options = trace_options_for(trace_mode)

data/lib/graphql/static_validation/validator.rb

@@ -27,6 +27,8 @@ module GraphQL
       # @param max_errors [Integer] Maximum number of errors before aborting validation. Any positive number will limit the number of errors. Defaults to nil for no limit.
       # @return [Array<Hash>]
       def validate(query, validate: true, timeout: nil, max_errors: nil)
+        errors = nil
+        query.current_trace.begin_validate(query, validate)
         query.current_trace.validate(validate: validate, query: query) do
           begin_t = Time.now
           errors = if validate == false
@@ -58,10 +60,13 @@ module GraphQL
           }
         end
       rescue GraphQL::ExecutionError => e
+        errors = [e]
         {
           remaining_timeout: nil,
-          errors: [e],
+          errors: errors,
         }
+      ensure
+        query.current_trace.end_validate(query, validate, errors)
       end
 
       # Invoked when static validation times out.

data/lib/graphql/tracing/active_support_notifications_trace.rb

@@ -4,8 +4,12 @@ require "graphql/tracing/notifications_trace"
 
 module GraphQL
   module Tracing
-    # This implementation forwards events to ActiveSupport::Notifications
-    # with a `graphql` suffix.
+    # This implementation forwards events to ActiveSupport::Notifications with a `graphql` suffix.
+    #
+    # @example Sending execution events to ActiveSupport::Notifications
+    #   class MySchema < GraphQL::Schema
+    #     trace_with(GraphQL::Tracing::ActiveSupportNotificationsTrace)
+    #   end
     module ActiveSupportNotificationsTrace
       include NotificationsTrace
       def initialize(engine: ActiveSupport::Notifications, **rest)

data/lib/graphql/tracing/appoptics_trace.rb

@@ -22,10 +22,12 @@ module GraphQL
       # These GraphQL events will show up as 'graphql.execute' spans
       EXEC_KEYS = ['execute_multiplex', 'execute_query', 'execute_query_lazy'].freeze
 
+
       # During auto-instrumentation this version of AppOpticsTracing is compared
       # with the version provided in the appoptics_apm gem, so that the newer
       # version of the class can be used
 
+
       def self.version
         Gem::Version.new('1.0.0')
       end
@@ -83,7 +85,7 @@ module GraphQL
         end
       end
 
-      def execute_field_lazy(query:, field:, ast_node:, arguments:, object:)
+      def execute_field_lazy(query:, field:, ast_node:, arguments:, object:)  # rubocop:disable Development/TraceCallsSuperCop
         execute_field(query: query, field: field, ast_node: ast_node, arguments: arguments, object: object)
       end
 

data/lib/graphql/tracing/appsignal_trace.rb

@@ -4,6 +4,12 @@ require "graphql/tracing/platform_trace"
 
 module GraphQL
   module Tracing
+    # Instrumentation for reporting GraphQL-Ruby times to Appsignal.
+    #
+    # @example Installing the tracer
+    #   class MySchema < GraphQL::Schema
+    #     trace_with GraphQL::Tracing::AppsignalTrace
+    #   end
     module AppsignalTrace
       include PlatformTrace
 

data/lib/graphql/tracing/data_dog_trace.rb

@@ -4,6 +4,11 @@ require "graphql/tracing/platform_trace"
 
 module GraphQL
   module Tracing
+    # A tracer for reporting to DataDog
+    # @example Adding this tracer to your schema
+    #   class MySchema < GraphQL::Schema
+    #     trace_with GraphQL::Tracing::DataDogTrace
+    #   end
     module DataDogTrace
       # @param tracer [#trace] Deprecated
       # @param analytics_enabled [Boolean] Deprecated

data/lib/graphql/tracing/detailed_trace/memory_backend.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Tracing
+    class DetailedTrace
+      # An in-memory trace storage backend. Suitable for testing and development only.
+      # It won't work for multi-process deployments and everything is erased when the app is restarted.
+      class MemoryBackend
+        def initialize(limit: nil)
+          @limit = limit
+          @traces = {}
+          @next_id = 0
+        end
+
+        def traces(last:, before:)
+          page = []
+          @traces.values.reverse_each do |trace|
+            if page.size == last
+              break
+            elsif before.nil? || trace.begin_ms < before
+              page << trace
+            end
+          end
+          page
+        end
+
+        def find_trace(id)
+          @traces[id]
+        end
+
+        def delete_trace(id)
+          @traces.delete(id.to_i)
+          nil
+        end
+
+        def delete_all_traces
+          @traces.clear
+          nil
+        end
+
+        def save_trace(operation_name, duration, begin_ms, trace_data)
+          id = @next_id
+          @next_id += 1
+          @traces[id] = DetailedTrace::StoredTrace.new(
+            id: id,
+            operation_name: operation_name,
+            duration_ms: duration,
+            begin_ms: begin_ms,
+            trace_data: trace_data
+          )
+          if @limit && @traces.size > @limit
+            del_keys = @traces.keys[0...-@limit]
+            del_keys.each { |k| @traces.delete(k) }
+          end
+          id
+        end
+      end
+    end
+  end
+end

data/lib/graphql/tracing/detailed_trace/redis_backend.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Tracing
+    class DetailedTrace
+      class RedisBackend
+        KEY_PREFIX = "gql:trace:"
+        def initialize(redis:, limit: nil)
+          @redis = redis
+          @key = KEY_PREFIX + "traces"
+          @remrangebyrank_limit = limit ? -limit - 1 : nil
+        end
+
+        def traces(last:, before:)
+          before = case before
+          when Numeric
+            "(#{before}"
+          when nil
+            "+inf"
+          end
+          str_pairs = @redis.zrange(@key, before, 0, byscore: true, rev: true, limit: [0, last || 100], withscores: true)
+          str_pairs.map do |(str_data, score)|
+            entry_to_trace(score, str_data)
+          end
+        end
+
+        def delete_trace(id)
+          @redis.zremrangebyscore(@key, id, id)
+          nil
+        end
+
+        def delete_all_traces
+          @redis.del(@key)
+        end
+
+        def find_trace(id)
+          str_data = @redis.zrange(@key, id, id, byscore: true).first
+          if str_data.nil?
+            nil
+          else
+            entry_to_trace(id, str_data)
+          end
+        end
+
+        def save_trace(operation_name, duration_ms, begin_ms, trace_data)
+          id = begin_ms
+          data = JSON.dump({ "o" => operation_name, "d" => duration_ms, "b" => begin_ms, "t" => Base64.encode64(trace_data) })
+          @redis.pipelined do |pipeline|
+            pipeline.zadd(@key, id, data)
+            if @remrangebyrank_limit
+              pipeline.zremrangebyrank(@key, 0, @remrangebyrank_limit)
+            end
+          end
+          id
+        end
+
+        private
+
+        def entry_to_trace(id, json_str)
+          data = JSON.parse(json_str)
+          StoredTrace.new(
+            id: id,
+            operation_name: data["o"],
+            duration_ms: data["d"].to_f,
+            begin_ms: data["b"].to_i,
+            trace_data: Base64.decode64(data["t"]),
+          )
+        end
+      end
+    end
+  end
+end

data/lib/graphql/tracing/detailed_trace.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+require "graphql/tracing/detailed_trace/memory_backend"
+require "graphql/tracing/detailed_trace/redis_backend"
+
+module GraphQL
+  module Tracing
+    # `DetailedTrace` can make detailed profiles for a subset of production traffic.
+    #
+    # When `MySchema.detailed_trace?(query)` returns `true`, a profiler-specific `trace_mode: ...` will be used for the query,
+    # overriding the one in `context[:trace_mode]`.
+    #
+    # __Redis__: The sampler stores its results in a provided Redis database. Depending on your needs,
+    # You can configure this database to retail all data (persistent) or to expire data according to your rules.
+    # If you need to save traces indefinitely, you can download them from Perfetto after opening them there.
+    #
+    # @example Adding the sampler to your schema
+    #   class MySchema < GraphQL::Schema
+    #     # Add the sampler:
+    #     use GraphQL::Tracing::DetailedTrace, redis: Redis.new(...), limit: 100
+    #
+    #     # And implement this hook to tell it when to take a sample:
+    #     def self.detailed_trace?(query)
+    #       # Could use `query.context`, `query.selected_operation_name`, `query.query_string` here
+    #       # Could call out to Flipper, etc
+    #       rand <= 0.000_1 # one in ten thousand
+    #     end
+    #   end
+    #
+    # @see Graphql::Dashboard GraphQL::Dashboard for viewing stored results
+    class DetailedTrace
+      # @param redis [Redis] If provided, profiles will be stored in Redis for later review
+      # @param limit [Integer] A maximum number of profiles to store
+      def self.use(schema, trace_mode: :profile_sample, memory: false, redis: nil, limit: nil)
+        storage = if redis
+          RedisBackend.new(redis: redis, limit: limit)
+        elsif memory
+          MemoryBackend.new(limit: limit)
+        else
+          raise ArgumentError, "Pass `redis: ...` to store traces in Redis for later review"
+        end
+        schema.detailed_trace = self.new(storage: storage, trace_mode: trace_mode)
+        schema.trace_with(PerfettoTrace, mode: trace_mode, save_profile: true)
+      end
+
+      def initialize(storage:, trace_mode:)
+        @storage = storage
+        @trace_mode = trace_mode
+      end
+
+      # @return [Symbol] The trace mode to use when {Schema.detailed_trace?} returns `true`
+      attr_reader :trace_mode
+
+      # @return [String] ID of saved trace
+      def save_trace(operation_name, duration_ms, begin_ms, trace_data)
+        @storage.save_trace(operation_name, duration_ms, begin_ms, trace_data)
+      end
+
+      # @param last [Integer]
+      # @param before [Integer] Timestamp in milliseconds since epoch
+      # @return [Enumerable<StoredTrace>]
+      def traces(last: nil, before: nil)
+        @storage.traces(last: last, before: before)
+      end
+
+      # @return [StoredTrace, nil]
+      def find_trace(id)
+        @storage.find_trace(id)
+      end
+
+      # @return [void]
+      def delete_trace(id)
+        @storage.delete_trace(id)
+      end
+
+      # @return [void]
+      def delete_all_traces
+        @storage.delete_all_traces
+      end
+
+      class StoredTrace
+        def initialize(id:, operation_name:, duration_ms:, begin_ms:, trace_data:)
+          @id = id
+          @operation_name = operation_name
+          @duration_ms = duration_ms
+          @begin_ms = begin_ms
+          @trace_data = trace_data
+        end
+
+        attr_reader :id, :operation_name, :duration_ms, :begin_ms, :trace_data
+      end
+    end
+  end
+end