optics-agent 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: baf3d71a589fb44d4c5334e9536b40bf102776be
-  data.tar.gz: 5d2c8f79f113afb70a170d4464b577b83db45c9a
+  metadata.gz: c6c80fb6905bbb97a8edee4ae2fb1d57d9cca76c
+  data.tar.gz: 969d07c49e74405731ba62ab699982f86c41daa4
 SHA512:
-  metadata.gz: c55989f7e56a1f233ca326e848e3869666714a2b0a892adb11c96d985e5331159fa69b23a27aa58332bf2ae155697a6f1b45bf613aad8a7511aa5fd0dcf594d0
-  data.tar.gz: 877b3599a864ddb80e66df0f2c9b95578ececf581dc87136fb8db819f90beb4a4e2b2ea6b9a2c36272f18c7159006c8bf7db2e3bbd6dc67d9c51f87c2512bacc
+  metadata.gz: 8b6dbc2a2f0a7f259ba2b4994be4c054e05bdc8ec8fe6d8a4da484830bcdbc5c5afa739dea52a62a4765750b73947ebe9c2a096a7b345383ae0e7c7beb0e92fa
+  data.tar.gz: af83946a5b4e0990de46b802865a95fecd8612a2adb085fafe5c0b4b6d8caa69b86909c0cdb29077e9989ec0238ae55a56048dc83c90946fe91d1f50f4231063

data/README.md

@@ -1,8 +1,6 @@
 # optics-agent-ruby
 Optics Agent for GraphQL Monitoring in Ruby.
 
-This is an alpha release, suitable for use in development contexts. There are still some outstanding improvements to make it ready for production contexts; see the [known limitations](#known-limitations) section below.
-
 [![Gem Version](https://badge.fury.io/rb/optics-agent.svg)](https://badge.fury.io/rb/optics-agent) [![Build Status](https://travis-ci.org/apollostack/optics-agent-ruby.svg?branch=master)](https://travis-ci.org/apollostack/optics-agent-ruby)
 
 
@@ -16,96 +14,23 @@ gem 'optics-agent'
 
 To your `Gemfile`
 
-## Setup
-
 ### API key
 
-You'll need to run your app with the `OPTICS_API_KEY` environment variable set (or set via options) to the API key of your Apollo Optics service; you can get an API key by setting up a service at https://optics.apollodata.com.
-
-### Configuration
-
-After creating an agent (see below), you can configure it with
-
-```rb
-agent.set_options(option: value)
-```
-
-Possible options are:
-
-  - `api_key` - Your API key for the Optics service. This defaults to the OPTICS_API_KEY environment variable, but can be overridden here.
-  - `endpoint_url ['https://optics-report.apollodata.com']` - Where to send the reports. Defaults to the production Optics endpoint, or the `OPTICS_ENDPOINT_URL` environment variable if it is set. You shouldn't need to set this unless you are debugging
-  - `debug [false]` - Log detailed debugging messages
-  - `disable_reporting [false]` - Don't report anything to Optics (useful for testing)
-  - `print_reports [false]` - Print JSON versions of the data sent to Optics to the log
-  - `schema_report_delay_ms [10000]` - How long to wait before sending a schema report after startup, in, milliseconds
-  - `report_interval_ms [60000]` - How often to send reports in milliseconds. Defaults to 1 minute. Minimum 10 seconds. You shouldn't need to set this unless you are debugging.
-
-### Basic Rack/Sinatra
-
-Create an agent
-
-```ruby
-# we expect one day there'll be some options
-agent = OpticsAgent::Agent.instance
-```
-
-Register the Rack middleware (say in a `config.ru`):
-
-```ruby
-use agent.rack_middleware
-```
-
-Register the GraphQL middleware:
-
-```ruby
-agent.instrument_schema(YourSchema)
-```
-
-Add something like this to your route:
-
-```ruby
-post '/graphql' do
-  request.body.rewind
-  params = JSON.parse request.body.read
-  document = params['query']
-  variables = params['variables']
-
-  result = Schema.execute(
-    document,
-    variables: variables,
-    context: { optics_agent: env[:optics_agent].with_document(document) }
-  )
-
-  JSON.generate(result)
-end
-```
+You'll need to run your app with the `OPTICS_API_KEY` environment variable set (or set via `agent.configure`) to the API key of your Apollo Optics service; you can get an API key by setting up a service at https://optics.apollodata.com.
 
-## Rails
-
-The equivalent of the above for Rails is:
-
-Create an agent in `config/application.rb`, and register the rack middleware:
+## Rails Setup
 
+Create an agent in `config/initializers/optics_agent.rb`, and register the rack middleware:
 ```ruby
-module YourApplicationRails
-  class Application < Rails::Application
-    # ...
-
-    config.optics_agent = OpticsAgent::Agent.instance
-    config.middleware.use config.optics_agent.rack_middleware
-  end
+optics_agent = OpticsAgent::Agent.new
+optics_agent.configure do
+  schema YourSchema
+  # See other configuration options below
 end
-
-```
-
-Register the GraphQL middleware when you create your schema:
-
-```ruby
-Rails.application.config.optics_agent.instrument_schema(YourSchema)
+Rails.application.config.middleware.use optics_agent.rack_middleware
 ```
 
 Register Optics Agent on the GraphQL context within your `graphql` action as below:
-
 ```ruby
 def create
   query_string = params[:query]
@@ -125,16 +50,50 @@ end
 
 You can check out the GitHunt Rails API server example here: https://github.com/apollostack/githunt-api-rails
 
-## Known limitations
+## General Setup
 
-Currently the agent is in alpha state; it is intended for early access use in development or basic (non-performance oriented) staging testing.
+You must:
 
-We are working on resolving a [list of issues](https://github.com/apollostack/optics-agent-ruby/projects/1) to put together a production-ready beta launch. The headline issues as things stand are:
+1. Create an agent with `OpticsAgent::Agent.new`
+2. Register your schema with the `agent.configure` block
+3. Attach the `agent.rack_middleware` to your Rack router
+4. Ensure you pass the `optics_agent` context from the rack environment to your schema execution.
 
-- The agent is overly chatty and uses a naive threading mechanism that may lose reporting data when threads exit/etc.
-- Instrumentation timings may not be correct in all uses cases, and query times include the full rack request time.
+### Configuration
+
+After creating an agent, you can configure it with:
+
+```rb
+# defaults are show below
+agent.configure do
+  # The schema you wish to instrument
+  schema YourSchema
+
+  # Your API key for the Optics service. This defaults to the OPTICS_API_KEY environment variable, but can be overridden here.
+  api_key ENV['OPTICS_API_KEY']
+
+  # Log detailed debugging messages
+  debug false
+
+  # Don't report anything to Optics (useful for testing)
+  disable_reporting false
 
-You can follow along with our [Beta Release Project](https://github.com/apollostack/optics-agent-ruby/projects/1), or even get in touch if you want to help out getting there!
+  # Print JSON versions of the data sent to Optics to the log
+  print_reports false
+
+  # Send detailed traces along with usage reports
+  report_traces true
+
+  # How long to wait before sending a schema report after startup, in, milliseconds
+  schema_report_delay_ms 10 * 1000
+
+  # How often to send reports in milliseconds. Defaults to 1 minute. Minimum 10 seconds. You shouldn't need to set this unless you are debugging.
+  report_interval_ms 60 * 1000
+
+  # Where to send the reports. Defaults to the production Optics endpoint, or the `OPTICS_ENDPOINT_URL` environment variable if it is set. You shouldn't need to set this unless you are debugging
+  endpoint_url 'https://optics-report.apollodata.com'
+end
+```
 
 ## Development
 

data/lib/optics-agent.rb

@@ -2,3 +2,4 @@ module OpticsAgent
 end
 
 require 'optics-agent/agent'
+require 'optics-agent/instrumenters/patch-graphql-schema'

data/lib/optics-agent/agent.rb

@@ -1,89 +1,112 @@
-require 'singleton'
 require 'optics-agent/rack-middleware'
-require 'optics-agent/graphql-middleware'
+require 'optics-agent/instrumenters/field'
 require 'optics-agent/reporting/report_job'
 require 'optics-agent/reporting/schema_job'
 require 'optics-agent/reporting/query-trace'
 require 'net/http'
+require 'faraday'
 
 module OpticsAgent
-  # XXX: this is a class but acts as a singleton right now.
-  # Need to figure out how to pass the agent into the middleware
-  #   (for instance we could dynamically generate a middleware class,
-  #    or ask the user to pass the agent as an option) to avoid it
   class Agent
-    include Singleton
     include OpticsAgent::Reporting
 
-    attr_reader :schema
+    attr_reader :schema, :report_traces
 
     def initialize
       @query_queue = []
       @semaphone = Mutex.new
 
       # set defaults
-      self.set_options
-    end
-
-    def set_options(
-      debug: false,
-      disable_reporting: false,
-      print_reports: false,
-      schema_report_delay_ms: 10 * 1000,
-      report_interval_ms: 60 * 1000,
-      api_key: ENV['OPTICS_API_KEY'],
-      endpoint_url: ENV['OPTICS_ENDPOINT_URL'] || 'https://optics-report.apollodata.com'
-    )
-      @debug = debug
-      @disable_reporting = disable_reporting || !endpoint_url || endpoint_url.nil?
-      @print_reports = print_reports
-      @schema_report_delay_ms = schema_report_delay_ms
-      @report_interval_ms = report_interval_ms
-      @api_key = api_key
-      @endpoint_url = endpoint_url
+      @configuration = Configuration.new
+    end
+
+    def configure(&block)
+      @configuration.instance_eval(&block)
+
+      if @configuration.schema && @schema != @configuration.schema
+        instrument_schema(@configuration.schema)
+      end
+    end
+
+    def disabled?
+      @configuration.disable_reporting || !@configuration.api_key || !@schema
+    end
+
+    def report_traces?
+      @configuration.report_traces
     end
 
     def instrument_schema(schema)
+      unless @configuration.api_key
+        warn """No api_key set.
+Either configure it or use the OPTICS_API_KEY environment variable.
+"""
+        return
+      end
+
+      if @schema
+        warn """Agent has already instrumented a schema.
+Perhaps you are calling both `agent.configure { schema YourSchema }` and
+`agent.instrument_schema YourSchema`?
+"""
+        return
+      end
+
       @schema = schema
-      debug "adding middleware to schema"
-      schema.middleware << graphql_middleware
+      @schema._attach_optics_agent(self)
 
-      unless @disable_reporting
+      unless disabled?
         debug "spawning schema thread"
         Thread.new do
           debug "schema thread spawned"
-          sleep @schema_report_delay_ms / 1000
+          sleep @configuration.schema_report_delay_ms / 1000.0
           debug "running schema job"
           SchemaJob.new.perform(self)
         end
       end
     end
 
-    # we call this method on every request to ensure that the reporting thread
+    # We call this method on every request to ensure that the reporting thread
     # is active in the correct process for pre-forking webservers like unicorn
     def ensure_reporting!
-      unless @reporting_thread_active
+      unless @schema
+        warn """No schema instrumented.
+Use the `schema` configuration setting, or call `agent.instrument_schema`
+"""
+        return
+      end
+
+      unless @reporting_thread_active || disabled?
         schedule_report
         @reporting_thread_active = true
       end
     end
 
+    def reporting_connection
+      @reporting_connection ||=
+        Faraday.new(:url => @configuration.endpoint_url) do |faraday|
+          # XXX: allow setting adaptor in config
+          faraday.adapter :net_http_persistent
+        end
+    end
+
     def schedule_report
       debug "spawning reporting thread"
       Thread.new do
         debug "reporting thread spawned"
         while true
-          sleep @report_interval_ms / 1000
+          sleep @configuration.report_interval_ms / 1000.0
           debug "running reporting job"
           ReportJob.new.perform(self)
+          debug "finished running reporting job"
         end
       end
     end
 
-    def add_query(query, rack_env, start_time, end_time)
+    def add_query(*args)
       @semaphone.synchronize {
         debug { "adding query to queue, queue length was #{@query_queue.length}" }
-        @query_queue << [query, rack_env, start_time, end_time]
+        @query_queue << args
       }
     end
 
@@ -97,32 +120,31 @@ module OpticsAgent
     end
 
     def rack_middleware
+      # We need to pass ourselves to the class we return here because
+      # rack will instanciate it. (See comment at the top of RackMiddleware)
+      OpticsAgent::RackMiddleware.agent = self
       OpticsAgent::RackMiddleware
     end
 
     def graphql_middleware
-      # graphql middleware doesn't seem to need the agent but certainly could have it
-      OpticsAgent::GraphqlMiddleware.new
+      warn "You no longer need to pass the optics agent middleware, it now attaches itself"
     end
 
     def send_message(path, message)
-      req = Net::HTTP::Post.new(path)
-      req['x-api-key'] = @api_key
-      req['user-agent'] = "optics-agent-rb"
-
-      req.body = message.class.encode(message)
-      if @debug || @print_reports
-        log "sending message: #{message.class.encode_json(message)}"
+      response = reporting_connection.post do |request|
+        request.url path
+        request.headers['x-api-key'] = @configuration.api_key
+        request.headers['user-agent'] = "optics-agent-rb"
+
+        request.body = message.class.encode(message)
+        if @configuration.debug || @configuration.print_reports
+          log "sending message: #{message.class.encode_json(message)}"
+        end
       end
 
-      uri = URI.parse(@endpoint_url)
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = true
-      res = http.request(req)
-
-      if @debug || @print_reports
-        log "got response: #{res.inspect}"
-        log "response body: #{res.body.inspect}"
+      if @configuration.debug || @configuration.print_reports
+        log "got response: #{response}"
+        log "response body: #{response.body}"
       end
     end
 
@@ -131,11 +153,48 @@ module OpticsAgent
       puts "optics-agent: #{message}"
     end
 
+    def warn(message = nil)
+      log "WARNING: #{message}"
+    end
+
     def debug(message = nil)
-      if @debug
+      if @configuration.debug
         message = yield unless message
         log "DEBUG: #{message} <#{Process.pid} | #{Thread.current.object_id}>"
       end
     end
   end
+
+  class Configuration
+    def self.defaults
+      {
+        schema: nil,
+        debug: false,
+        disable_reporting: false,
+        print_reports: false,
+        report_traces: true,
+        schema_report_delay_ms: 10 * 1000,
+        report_interval_ms: 60 * 1000,
+        api_key: ENV['OPTICS_API_KEY'],
+        endpoint_url: ENV['OPTICS_ENDPOINT_URL'] || 'https://optics-report.apollodata.com'
+      }
+    end
+
+    # Allow e.g. `debug false` == `debug = false` in configuration blocks
+    defaults.each_key do |key|
+      define_method key, ->(*maybe_value) do
+        if (maybe_value.length === 1)
+          self.instance_variable_set("@#{key}", maybe_value[0])
+        elsif (maybe_value.length === 0)
+          self.instance_variable_get("@#{key}")
+        else
+          throw new ArgumentError("0 or 1 argument expected")
+        end
+      end
+    end
+
+    def initialize
+      self.class.defaults.each { |key, value| self.send(key, value) }
+    end
+  end
 end

data/lib/optics-agent/instrumentation/query-schema.rb

@@ -3,7 +3,11 @@ module OpticsAgent
     INTROSPECTION_QUERY ||= IO.read("#{File.dirname(__FILE__)}/introspection-query.graphql")
 
     def introspect_schema(schema)
-      schema.execute(INTROSPECTION_QUERY)['data']['__schema']
+      result = schema.execute(INTROSPECTION_QUERY,
+        context: {optics_agent: :skip}
+      )
+
+      result['data']['__schema']
     end
   end
 end

data/lib/optics-agent/instrumenters/field.rb

@@ -0,0 +1,51 @@
+module OpticsAgent
+  module Instrumenters
+    class Field
+      attr_accessor :agent
+
+      def instrument(type, field)
+        old_resolve_proc = field.resolve_proc
+        new_resolve_proc = ->(obj, args, ctx) {
+          if @agent
+            middleware(@agent, type, obj, field, args, ctx, ->() { old_resolve_proc.call(obj, args, ctx) })
+          else
+            old_resolve_proc.call(obj, args, ctx)
+          end
+        }
+
+        field.redefine do
+          resolve(new_resolve_proc)
+        end
+      end
+
+      def middleware(agent, parent_type, parent_object, field_definition, field_args, query_context, next_middleware)
+        agent_context = query_context[:optics_agent]
+
+        unless agent_context
+          agent.warn """No agent passed in graphql context.
+  Ensure you set `context: {optics_agent: env[:optics_agent].with_document(document) }``
+  when executing your graphql query.
+  If you don't want to instrument this query, pass `context: {optics_agent: :skip}`.
+  """
+          return
+        end
+
+        # This happens when an introspection query occurs (reporting schema)
+        # Also, people could potentially use it to skip reporting
+        if agent_context == :skip
+          return next_middleware.call
+        end
+
+        query = agent_context.query
+
+        start_offset = query.duration_so_far
+        result = next_middleware.call
+        duration = query.duration_so_far - start_offset
+
+        query.report_field(parent_type.to_s, field_definition.name, start_offset, duration)
+
+        result
+      end
+    end
+  end
+end

data/lib/optics-agent/instrumenters/patch-graphql-schema.rb

@@ -0,0 +1,29 @@
+# Monkey patch GraphQL::Schema.define so that it automatically attaches our
+# field instrumenter. Our instrumenter will do nothing unless we later attach
+# an agent to it, which this will also allow us to do.
+
+require 'graphql'
+require 'optics-agent/instrumenters/field'
+
+module OpticsAgent::GraphQLSchemaExtensions
+  def define(**kwargs, &block)
+    @instrumenter = OpticsAgent::Instrumenters::Field.new
+
+    class << self
+      def _attach_optics_agent(agent)
+        agent.debug "Attaching agent to field instrumenter"
+        @instrumenter.agent = agent
+      end
+    end
+
+    instrumenter = @instrumenter
+    super **kwargs do
+      instance_eval(&block) if block
+      instrument :field, instrumenter
+    end
+  end
+end
+
+class GraphQL::Schema
+  prepend OpticsAgent::GraphQLSchemaExtensions
+end

data/lib/optics-agent/normalization/query.rb

@@ -58,7 +58,7 @@ module OpticsAgent
 
         visitor[Nodes::InlineFragment].leave << -> (node, parent) do
           selections = current[:selections]
-          stack[0][:selections] << "... on #{node.type} #{block(selections)}"
+          stack[0][:selections] << "... on #{node.type.name} #{block(selections)}"
         end
 
         visitor[Nodes::FragmentSpread].leave << -> (node, parent) do
@@ -90,7 +90,7 @@ module OpticsAgent
         visitor[Nodes::FragmentDefinition].leave << -> (node, parent) do
           selections = current[:selections]
           if (used_fragment_names.include?(node.name))
-            output << " fragment #{node.name} on #{node.type} " \
+            output << " fragment #{node.name} on #{node.type.name} " \
               + block(selections)
           end
         end

data/lib/optics-agent/rack-middleware.rb

@@ -1,19 +1,25 @@
 require 'optics-agent/agent'
 require 'optics-agent/reporting/query'
-
 module OpticsAgent
   class RackMiddleware
+    # Right now we assume there'll only be a single rack middleware in an
+    # app, and set the agent via a class attribute. This means that in theory
+    # you could use more than one agent, but at most one middleware.
+    # In the future, if we see a need for more than one middleware, we could
+    # probably just copy the class when calling `agent.rack_middleware`
+    class << self
+      attr_accessor :agent
+    end
+
     def initialize(app, options={})
       @app = app
     end
 
     def call(env)
-      start_time = Time.now
-
-      # XXX: figure out a way to pass this in here
-      agent = OpticsAgent::Agent.instance
+      agent = self.class.agent
       agent.ensure_reporting!
       agent.debug { "rack-middleware: request started" }
+
       query = OpticsAgent::Reporting::Query.new
 
       # Attach so resolver middleware can access
@@ -21,12 +27,11 @@ module OpticsAgent
 
       result = @app.call(env)
 
-      # XXX: this approach means if the user forgets to call with_document
-      # we just never log queries. Can we detect if the request is a graphql one?
       agent.debug { "rack-middleware: request finished" }
       if (query.document)
         agent.debug { "rack-middleware: adding query to agent" }
-        agent.add_query(query, env, start_time, Time.now)
+        query.finish!
+        agent.add_query(query, env)
       end
 
       result

data/lib/optics-agent/reporting/helpers.rb

@@ -11,13 +11,16 @@ module OpticsAgent::Reporting
   def generate_timestamp(time)
     Apollo::Optics::Proto::Timestamp.new({
       seconds: time.to_i,
-      nanos: time.to_i % 1 * 1e9
+      nanos: duration_nanos(time.to_i % 1)
     });
   end
 
-  def duration_nanos(start_time, end_time)
-    throw "start_time before end_time" if (start_time > end_time)
-    ((end_time - start_time) * 1e9).to_i
+  def duration_nanos(duration_in_seconds)
+    (duration_in_seconds * 1e9).to_i
+  end
+
+  def duration_micros(duration_in_seconds)
+    (duration_in_seconds * 1e6).to_i
   end
 
   # XXX: implement
@@ -29,9 +32,11 @@ module OpticsAgent::Reporting
     }
   end
 
-  def add_latency(counts, start_time, end_time)
-    micros = (end_time - start_time) * 1e6
-    bucket = latency_bucket(micros)
-    counts[bucket] += 1
+  def add_latency(counts, duration_in_seconds)
+    counts[latency_bucket_for_duration(duration_in_seconds)] += 1
+  end
+
+  def latency_bucket_for_duration(duration_in_seconds)
+    latency_bucket(duration_micros(duration_in_seconds))
   end
 end

data/lib/optics-agent/reporting/query-trace.rb

@@ -10,11 +10,11 @@ module OpticsAgent::Reporting
 
     attr_accessor :report
 
-    def initialize(query, rack_env, start_time, end_time)
+    def initialize(query, rack_env)
       trace = Trace.new({
-        start_time: generate_timestamp(start_time),
-        end_time: generate_timestamp(end_time),
-        duration_ns: duration_nanos(start_time, end_time),
+        start_time: generate_timestamp(query.start_time),
+        end_time: generate_timestamp(query.end_time),
+        duration_ns: duration_nanos(query.duration),
         signature: query.signature
       })
 
@@ -31,11 +31,11 @@ module OpticsAgent::Reporting
       })
 
       nodes = []
-      query.each_report do |type_name, field_name, field_start_time, field_end_time|
+      query.each_report do |type_name, field_name, start_offset, duration|
         nodes << Trace::Node.new({
           field_name: "#{type_name}.#{field_name}",
-          start_time: duration_nanos(start_time, field_start_time),
-          end_time: duration_nanos(start_time, field_end_time)
+          start_time: duration_nanos(start_offset),
+          end_time: duration_nanos(start_offset + duration)
         })
       end
       trace.execute = Trace::Node.new({

data/lib/optics-agent/reporting/query.rb

@@ -2,6 +2,8 @@ require 'apollo/optics/proto/reports_pb'
 require 'optics-agent/reporting/helpers'
 require 'optics-agent/normalization/latency'
 require 'optics-agent/normalization/query'
+require 'hitimes'
+require 'forwardable'
 
 module OpticsAgent::Reporting
   # This is a convenience class that enables us to fairly blindly
@@ -12,13 +14,25 @@ module OpticsAgent::Reporting
     include OpticsAgent::Normalization
     include OpticsAgent::Normalization::Query
 
+    extend Forwardable
+
     attr_accessor :document
+    attr_reader :start_time, :end_time
+    def_delegators :@interval, :duration, :duration_so_far
 
     def initialize
       @reports = []
 
       @document = nil
-      @signature
+      @signature = nil
+
+      @start_time = Time.now
+      @interval = Hitimes::Interval.now
+    end
+
+    def finish!
+      @end_time = Time.now
+      @interval.stop
     end
 
     def signature
@@ -32,8 +46,8 @@ module OpticsAgent::Reporting
     end
 
     # we do nothing when reporting to minimize impact
-    def report_field(type_name, field_name, start_time, end_time)
-      @reports << [type_name, field_name, start_time, end_time]
+    def report_field(type_name, field_name, start_offset, duration)
+      @reports << [type_name, field_name, start_offset, duration]
     end
 
     def each_report
@@ -44,7 +58,7 @@ module OpticsAgent::Reporting
 
     # add our results to an existing StatsPerSignature
     def add_to_stats(stats_per_signature)
-      each_report do |type_name, field_name, start_time, end_time|
+      each_report do |type_name, field_name, start_offset, duration|
         type_stat = stats_per_signature.per_type.find { |ts| ts.name == type_name }
         unless type_stat
           type_stat = TypeStat.new({ name: type_name })
@@ -60,7 +74,7 @@ module OpticsAgent::Reporting
           type_stat.field << field_stat
         end
 
-        add_latency(field_stat.latency_count, start_time, end_time)
+        add_latency(field_stat.latency_count, duration)
       end
     end
   end

data/lib/optics-agent/reporting/report.rb

@@ -1,6 +1,7 @@
 require 'apollo/optics/proto/reports_pb'
 require 'optics-agent/reporting/helpers'
 require 'optics-agent/normalization/latency'
+require 'hitimes'
 
 module OpticsAgent::Reporting
   # This class represents a complete report that we send to the optics server
@@ -11,9 +12,10 @@ module OpticsAgent::Reporting
     include OpticsAgent::Reporting
     include OpticsAgent::Normalization
 
-    attr_accessor :report
+    attr_reader :report
+    attr_reader :traces_to_report
 
-    def initialize
+    def initialize(report_traces: true)
       # internal report that we encapsulate
       @report = StatsReport.new({
         header: ReportHeader.new({
@@ -21,28 +23,39 @@ module OpticsAgent::Reporting
         }),
         start_time: generate_timestamp(Time.now)
       })
+
+      @interval = Hitimes::Interval.now
+
+      @report_traces = report_traces
+      @traces_to_report = []
     end
 
     def finish!
       @report.end_time ||= generate_timestamp(Time.now)
-      @report.realtime_duration || duration_nanos(@report.start_time, @report.end_time)
+      @report.realtime_duration || duration_nanos(@interval.stop)
     end
 
     def send_with(agent)
+      agent.debug do
+        n_queries = 0
+        @report.per_signature.values.each do |signature_stats|
+          signature_stats.per_client_name.values.each do |client_stats|
+            n_queries += client_stats.count_per_version.values.reduce(&:+)
+          end
+        end
+        "Sending #{n_queries} queries and #{@traces_to_report.length} traces"
+      end
       self.finish!
+      @traces_to_report.each do |trace|
+        trace.send_with(agent)
+      end
       agent.send_message('/api/ss/stats', @report)
     end
 
-    # XXX: record timing / client
-    def add_query(query, rack_env, start_time, end_time)
+    def add_query(query, rack_env)
       @report.per_signature[query.signature] ||= StatsPerSignature.new
       signature_stats = @report.per_signature[query.signature]
 
-      add_client_stats(signature_stats, rack_env, start_time, end_time)
-      query.add_to_stats(signature_stats)
-    end
-
-    def add_client_stats(signature_stats, rack_env, start_time, end_time)
       info = client_info(rack_env)
       signature_stats.per_client_name[info[:client_name]] ||= StatsPerClientName.new({
         latency_count: empty_latency_count,
@@ -51,10 +64,20 @@ module OpticsAgent::Reporting
       client_stats = signature_stats.per_client_name[info[:client_name]]
 
       # XXX: handle errors
-      add_latency(client_stats.latency_count, start_time, end_time)
-
+      add_latency(client_stats.latency_count, query.duration)
       client_stats.count_per_version[info[:client_version]] ||= 0
       client_stats.count_per_version[info[:client_version]] += 1
+
+      query.add_to_stats(signature_stats)
+
+      if @report_traces
+        # Is this the first query we've seen in this reporting period and
+        # latency bucket? In which case we want to send a trace
+        bucket = latency_bucket_for_duration(query.duration)
+        if (client_stats.latency_count[bucket] == 1)
+          @traces_to_report << QueryTrace.new(query, rack_env)
+        end
+      end
     end
 
     # take a graphql schema and add returnTypes to all the fields on our report

data/lib/optics-agent/reporting/report_job.rb

@@ -3,17 +3,18 @@ require 'optics-agent/reporting/report'
 module OpticsAgent::Reporting
   class ReportJob
     def perform(agent)
-      report = OpticsAgent::Reporting::Report.new
-      agent.clear_query_queue.each do |item|
-        report.add_query(*item)
+      begin
+        report = OpticsAgent::Reporting::Report.new(report_traces: agent.report_traces?)
+        agent.clear_query_queue.each do |item|
+          report.add_query(*item)
+        end
 
-        # XXX: don't send *every* trace
-        query_trace = QueryTrace.new(*item)
-        query_trace.send_with(agent)
+        report.decorate_from_schema(agent.schema)
+        report.send_with(agent)
+      rescue StandardError => e
+        agent.debug "report failed #{e}"
+        raise
       end
-
-      report.decorate_from_schema(agent.schema)
-      report.send_with(agent)
     end
   end
 end

data/lib/optics-agent/reporting/schema_job.rb

@@ -3,8 +3,14 @@ require 'optics-agent/reporting/schema'
 module OpticsAgent::Reporting
   class SchemaJob
     def perform(agent)
-      schema = OpticsAgent::Reporting::Schema.new agent.schema
-      schema.send_with(agent)
+      begin
+        schema = OpticsAgent::Reporting::Schema.new agent.schema
+        schema.send_with(agent)
+      rescue StandardError => e
+        agent.debug "schema report failed #{e}"
+        agent.debug e.backtrace
+        raise
+      end
     end
   end
 end

data/spec/{graphql-middleware_spec.rb → field_instrumenter_spec.rb}

@@ -1,10 +1,10 @@
 require 'ostruct'
-require 'optics-agent/graphql-middleware'
+require 'optics-agent/instrumenters/field'
 require 'graphql'
 
 include OpticsAgent
 
-describe GraphqlMiddleware do
+describe Instrumenters::Field do
   it 'collects the correct query stats' do
     person_type = GraphQL::ObjectType.define do
       name "Person"
@@ -25,23 +25,26 @@ describe GraphqlMiddleware do
       end
     end
 
+    instrumenter = Instrumenters::Field.new
+    instrumenter.agent = true
     schema = GraphQL::Schema.define do
       query query_type
+      instrument :field, instrumenter
     end
 
-    schema.middleware << GraphqlMiddleware.new
-
     query = spy("query")
+    allow(query).to receive(:duration_so_far).and_return(1.0)
+
     schema.execute('{ person { firstName lastName } }', {
       context: { optics_agent: OpenStruct.new(query: query) }
     })
 
     expect(query).to have_received(:report_field).exactly(3).times
     expect(query).to have_received(:report_field)
-      .with('Query', 'person', be_instance_of(Time), be_instance_of(Time))
+      .with('Query', 'person', be_instance_of(Float), be_instance_of(Float))
     expect(query).to have_received(:report_field)
-      .with('Person', 'firstName', be_instance_of(Time), be_instance_of(Time))
+      .with('Person', 'firstName', be_instance_of(Float), be_instance_of(Float))
     expect(query).to have_received(:report_field)
-      .with('Person', 'lastName', be_instance_of(Time), be_instance_of(Time))
+      .with('Person', 'lastName', be_instance_of(Float), be_instance_of(Float))
   end
 end

data/spec/query_trace_spec.rb

@@ -9,12 +9,13 @@ include OpticsAgent::Reporting
 describe QueryTrace do
   it "can represent a simple query" do
     query = Query.new
-    query.report_field 'Person', 'firstName', 1, 1.1
-    query.report_field 'Person', 'lastName', 1, 1.1
-    query.report_field 'Query', 'person', 1, 1.22
+    query.report_field 'Person', 'firstName', 1, 0.1
+    query.report_field 'Person', 'lastName', 1.1, 0.1
+    query.report_field 'Query', 'person', 1.2, 0.22
     query.document = '{field}'
+    query.finish!
 
-    trace = QueryTrace.new(query, {}, 1, 1.25)
+    trace = QueryTrace.new(query, {})
 
     expect(trace.report).to be_instance_of(TracesReport)
     expect(trace.report.trace.length).to eq(1)
@@ -26,7 +27,7 @@ describe QueryTrace do
       match_array(['Query.person', 'Person.firstName', 'Person.lastName'])
 
     firstName_node = nodes.find { |n| n.field_name == 'Person.firstName' }
-    expect(firstName_node.start_time).to eq(0)
-    expect(firstName_node.end_time).to eq(0.1 * 1e9)
+    expect(firstName_node.start_time).to eq(1 * 1e9)
+    expect(firstName_node.end_time).to eq(1.1 * 1e9)
   end
 end

data/spec/report_spec.rb

@@ -9,13 +9,14 @@ include Apollo::Optics::Proto
 describe Report do
   it "can represent a simple query" do
     query = Query.new
-    query.report_field 'Person', 'firstName', 1, 1.1
-    query.report_field 'Person', 'lastName', 1, 1.1
-    query.report_field 'Query', 'person', 1, 1.22
+    query.report_field 'Person', 'firstName', 1, 0.1
+    query.report_field 'Person', 'lastName', 1.1, 0.1
+    query.report_field 'Query', 'person', 1.2, 0.22
+    query.finish!
     query.document = '{field}'
 
     report = Report.new
-    report.add_query query, {}, 1, 1.25
+    report.add_query query, {}
     report.finish!
 
     expect(report.report).to be_an_instance_of(StatsReport)
@@ -38,20 +39,22 @@ describe Report do
 
   it "can aggregate the results of multiple queries with the same shape" do
     queryOne = Query.new
-    queryOne.report_field 'Person', 'firstName', 1, 1.1
-    queryOne.report_field 'Person', 'lastName', 1, 1.1
-    queryOne.report_field 'Query', 'person', 1, 1.22
+    queryOne.report_field 'Person', 'firstName', 1, 0.1
+    queryOne.report_field 'Person', 'lastName', 1.1, 0.1
+    queryOne.report_field 'Query', 'person', 1.2, 0.22
+    queryOne.finish!
     queryOne.document = '{field}'
 
     queryTwo = Query.new
-    queryTwo.report_field 'Person', 'firstName', 1, 1.05
-    queryTwo.report_field 'Person', 'lastName', 1, 1.05
-    queryTwo.report_field 'Query', 'person', 1, 1.2
+    queryTwo.report_field 'Person', 'firstName', 1, 0.05
+    queryTwo.report_field 'Person', 'lastName', 1.05, 0.05
+    queryTwo.report_field 'Query', 'person', 1.1, 0.20
+    queryTwo.finish!
     queryTwo.document = '{field}'
 
     report = Report.new
-    report.add_query queryOne, {}, 1, 1.1
-    report.add_query queryTwo, {}, 1, 1.1
+    report.add_query queryOne, {}
+    report.add_query queryTwo, {}
     report.finish!
 
     expect(report.report).to be_an_instance_of(StatsReport)
@@ -74,20 +77,22 @@ describe Report do
 
   it "can aggregate the results of multiple queries with a different shape" do
     queryOne = Query.new
-    queryOne.report_field 'Person', 'firstName', 1, 1.1
-    queryOne.report_field 'Person', 'lastName', 1, 1.1
-    queryOne.report_field 'Query', 'person', 1, 1.22
+    queryOne.report_field 'Person', 'firstName', 1, 0.1
+    queryOne.report_field 'Person', 'lastName', 1.1, 0.1
+    queryOne.report_field 'Query', 'person', 1.2, 0.22
+    queryOne.finish!
     queryOne.document = '{fieldOne}'
 
     queryTwo = Query.new
-    queryTwo.report_field 'Person', 'firstName', 1, 1.05
-    queryTwo.report_field 'Person', 'lastName', 1, 1.05
-    queryTwo.report_field 'Query', 'person', 1, 1.02
+    queryTwo.report_field 'Person', 'firstName', 1, 0.05
+    queryTwo.report_field 'Person', 'lastName', 1.05, 0.05
+    queryTwo.report_field 'Query', 'person', 1.1, 0.20
+    queryTwo.finish!
     queryTwo.document = '{fieldTwo}'
 
     report = Report.new
-    report.add_query queryOne, {}, 1, 1.1
-    report.add_query queryTwo, {}, 1, 1.1
+    report.add_query queryOne, {}
+    report.add_query queryTwo, {}
     report.finish!
 
     expect(report.report).to be_an_instance_of(StatsReport)
@@ -110,12 +115,13 @@ describe Report do
 
   it "can decorate it's fields with resultTypes from a schema" do
     query = Query.new
-    query.report_field 'Person', 'firstName', 1, 1.1
-    query.report_field 'Person', 'age', 1, 1.1
+    query.report_field 'Person', 'firstName', 1, 0.1
+    query.report_field 'Person', 'age', 1.1, 0.1
+    query.finish!
     query.document = '{field}'
 
     report = Report.new
-    report.add_query query, {}, 1, 1.25
+    report.add_query query, {}
     report.finish!
 
     person_type = GraphQL::ObjectType.define do
@@ -147,13 +153,14 @@ describe Report do
 
   it "can handle introspection fields" do
     query = Query.new
-    query.report_field 'Query', '__schema', 1, 1.1
-    query.report_field 'Query', '__typename', 1, 1.1
-    query.report_field 'Query', '__type', 1, 1.1
+    query.report_field 'Query', '__schema', 1, 0.1
+    query.report_field 'Query', '__typename', 1.1, 0.1
+    query.report_field 'Query', '__type', 1.2, 1.1
+    query.finish!
     query.document = '{field}'
 
     report = Report.new
-    report.add_query query, {}, 1, 1.25
+    report.add_query query, {}
     report.finish!
 
     query_type = GraphQL::ObjectType.define do
@@ -180,4 +187,54 @@ describe Report do
     expect(typename_stats.returnType).to eq('Query')
   end
 
+  describe "trace reporting" do
+    class QueryMock
+      attr_reader :signature, :duration, :start_time, :end_time
+      def initialize(signature, duration)
+        @signature = signature
+        @duration = duration
+        @start_time = Time.now
+        @end_time = Time.now
+      end
+
+      def add_to_stats(_); end
+      def each_report(); end
+    end
+
+    it "only sends one trace for two queries of the same shape and latency" do
+      queryOne = QueryMock.new '{field}', 1
+      queryTwo = QueryMock.new '{field}', 1
+
+      report = Report.new
+      report.add_query queryOne, {}
+      report.add_query queryTwo, {}
+      report.finish!
+
+      expect(report.traces_to_report.length).to be(1)
+    end
+
+    it "sends two traces for two queries of the same shape and different latencies" do
+      queryOne = QueryMock.new '{field}', 1
+      queryTwo = QueryMock.new '{field}', 1.1
+
+      report = Report.new
+      report.add_query queryOne, {}
+      report.add_query queryTwo, {}
+      report.finish!
+
+      expect(report.traces_to_report.length).to be(2)
+    end
+
+    it "sends two traces for two queries of different shapes and the same latency" do
+      queryOne = QueryMock.new '{fieldOne}', 1
+      queryTwo = QueryMock.new '{fieldTwo}', 1
+
+      report = Report.new
+      report.add_query queryOne, {}
+      report.add_query queryTwo, {}
+      report.finish!
+
+      expect(report.traces_to_report.length).to be(2)
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: optics-agent
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - 'Tom Coleman '
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.19.0
+        version: 1.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.19.0
+        version: 1.1.0
 - !ruby/object:Gem::Dependency
   name: google-protobuf
   requirement: !ruby/object:Gem::Requirement
@@ -38,6 +38,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 3.1.0
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+- !ruby/object:Gem::Dependency
+  name: net-http-persistent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: hitimes
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.4
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -77,9 +119,10 @@ files:
 - lib/apollo/optics/proto/reports_pb.rb
 - lib/optics-agent.rb
 - lib/optics-agent/agent.rb
-- lib/optics-agent/graphql-middleware.rb
 - lib/optics-agent/instrumentation/introspection-query.graphql
 - lib/optics-agent/instrumentation/query-schema.rb
+- lib/optics-agent/instrumenters/field.rb
+- lib/optics-agent/instrumenters/patch-graphql-schema.rb
 - lib/optics-agent/normalization/latency.rb
 - lib/optics-agent/normalization/query.rb
 - lib/optics-agent/rack-middleware.rb
@@ -91,7 +134,7 @@ files:
 - lib/optics-agent/reporting/schema.rb
 - lib/optics-agent/reporting/schema_job.rb
 - spec/benchmark/benchmark.rb
-- spec/graphql-middleware_spec.rb
+- spec/field_instrumenter_spec.rb
 - spec/latency_spec.rb
 - spec/query-normalization_spec.rb
 - spec/query_trace_spec.rb
@@ -126,7 +169,7 @@ specification_version: 4
 summary: An Agent for Apollo Optics
 test_files:
 - spec/benchmark/benchmark.rb
-- spec/graphql-middleware_spec.rb
+- spec/field_instrumenter_spec.rb
 - spec/latency_spec.rb
 - spec/query-normalization_spec.rb
 - spec/query_trace_spec.rb

data/lib/optics-agent/graphql-middleware.rb

@@ -1,18 +0,0 @@
-module OpticsAgent
-  class GraphqlMiddleware
-    def call(parent_type, parent_object, field_definition, field_args, query_context, next_middleware)
-      # This happens when an introspection query occurs (reporting schema)
-      # However, we could also use it to tell people if they've set things up wrong.
-      return next_middleware.call unless query_context[:optics_agent]
-
-      start_time = Time.now
-      result = next_middleware.call
-      end_time = Time.now
-
-      query = query_context[:optics_agent].query
-      query.report_field(parent_type.to_s, field_definition.name, start_time, end_time)
-
-      result
-    end
-  end
-end