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 section below.

Add

gem 'optics-agent'

To your Gemfile

You'll need to run your app with the OPTICS_API_KEY environment variable set to the API key of your Apollo Optics service; at the moment Optics is in early access alpha--get in touch if you want to be part of our early access program.

Create an agent

# we expect one day there'll be some options
agent = OpticsAgent::Agent.instance

Register the Rack middleware (say in a config.ru):

use agent.rack_middleware

Register the Graphql middleware:

agent.instrument_schema(YourSchema)

Add something like this to your route:

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

The equivalent of the above for Rails is:

Create an agent in config/apllication.rb, and register the rack middleware:

module YourApplicationRails
  class Application < Rails::Application
    # ...

    config.optics_agent = OpticsAgent::Agent.instance
    config.middleware.use config.optics_agent.rack_middleware
  end
end

Register the Graphql middleware when you create your schema:

Rails.application.config.optics_agent.instrument_schema(YourSchema)

Register Optics Agent on the GraphQL context within your graphql action as below:

def create
  query_string = params[:query]
  query_variables = ensure_hash(params[:variables])

  result = YourSchema.execute(
    query_string,
    variables: query_variables,
    context: {
      optics_agent: env[:optics_agent].with_document(query_string)
    }
  )

  render json: result
end

You can check out the GitHunt Rails API server example here: https://github.com/apollostack/githunt-api-rails

Currently the agent is in alpha state; it is intended for early access use in development or basic (non-performance oriented) staging testing.

We are working on resolving a list of issues to put together a production-ready beta launch. The headline issues as things stand are:

• 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.

You can follow along with our Beta Release Project, or even get in touch if you want to help out getting there!

bundle install
bundle exec rspec

Ensure you've installed protobuf and development dependencies.

# this works on OSX
brew install protobuf

# ensure it's version 3
protoc --version

bundle install

Compile the .proto definitions with

bundle exec rake protobuf:compile