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

Installing

Add

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

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

# 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

Rails

The equivalent of the above for Rails is:

Create an agent in config/application.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

Known limitations

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!

Development

Running tests

bundle install
bundle exec rspec

Building protobuf definitions

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