About the Stellate Ruby Metrics Plugin

The Stellate GraphQL Ruby Metrics Plugin is a powerful tool designed to integrate Stellate with your existing GraphQL Ruby API with just a few lines of code. It enhances your GraphQL::Schema class by providing features for schema syncing and metrics logging, allowing for a seamless connection with the Stellate service for performance insights and analytics.

Benefits of the Stellate Plugin

The primary benefit of using the Stellate Ruby Plugin is to be able to collect metrics without setting up the Stellate Edge proxy. For more information about the Stellate Edge proxy, read Stellate Edge proxy. In addition:

An ancillary benefit is the ability to automatically synchronize your GraphQL schema with your Stellate service, ensuring that your API's structure is always up to date.
The plugin extends your schema class with a execute_with_logging method, which captures and logs detailed information about GraphQL requests and their execution. This data is invaluable for debugging, monitoring performance, and understanding API usage patterns.

Before you Begin

Before you install and use the Stellate Ruby Plugin (the stellate gem), you need to:

Set Up a Stellate Service: You must have an active Stellate service set up. The stellage gem is designed to work with you Stellate service. It provides performance insights and analytics for GraphQL Ruby-based APIs.

Create a Logging Token: To implement this plugin, you need to create a logging token specific to your Stellate service. This token is used to authenticate and log metrics data from your GraphQL API to your Stellate dashboard. You can get your logging token by going to your Stellate Dashboard > Services > Your Service > Config > Tokens.

Add to the Gemfiles: If not already in place, add graphql-rails and graphql to your Gemfile. For example:

      gem 'graphqu-rails',  group: :development
      gem 'graphql'

Once these prerequisites are met, you can install the GraphQL Ruby Plugin.

Note: If you are using the Stellate Dashboard workflow, you cannot advance to next steps unless the plugin is installed correctly. Although, you can exit from the workflow, it provides a quick way to validate your installation.

Install the GraphQL Ruby Metrics Plugin

To install the GraphQL Ruby Metrics Plugin, follow these two steps:

Add the stellate gem to your Gemfile:

   gem 'stellate'

Run the bundle install command to install the gem.

Set up the Ruby GraphQL Metrics Plugin

Using the stellate gem involves a few simple setup steps:

Before you can make use of this gem, you must have set up a Stellate service and create a logging token. See the prior Before You Begin section for more information.
The stellate gem integrates directly into your GraphQL::Schema class. You must make sure to "require" the gem and then place it somewhere inside the class:
```
require 'stellate'
```

Configure your schema class with the Stellate service name and logging token:

class MySchema < GraphQL::Schema
  @stellate_service_name = 'my-service'
  @stellate_token = 'stl8_m3y!5t8oken'
end

Automatically sync the schema with your Stellate service using Stellate::SchemaSyncing.

class MySchema < GraphQL::Schema
  @stellate_service_name = 'my-service'
  @stellate_token = 'stl8_m3y!5t8oken'

   use Stellate::SchemaSyncing
end

Extend this class with a execute_with_logging class method that wraps the # execute method and logs information about the request and execution to your Stellate service.

The following code snippet shows a configuration example:

class MySchema < GraphQL::Schema
  @stellate_service_name = 'my-service'
  @stellate_token = 'stl8_xyz'

  use Stellate::SchemaSyncing

  extend Stellate::MetricsLogging
end

This class gives you a new method that you can use to replace your current execute method, which is what you call to run a GraphQL request in Ruby.

Finally, change all MySchema.execute() calls to MySchema.execute_with_logging(). Both these functions accept the same arguments. For example:
```
}
result = RubyGraphqlDemoSchema.execute_with_logging ()
{
```
Stellate can provide you with even more insights if you also provide the execute_with_logging() method with the map of HTTP headers of type ActionDispatch::Http::Headers. An example for a call to this function would look like this:

MySchema.execute_with_logging(
  query,
  variables: variables,
  context: context,
  operation_name: operation_name,
  headers: request.headers
)

Validate the Stellate Ruby Plugin

To validate that your plugin is working:

Once you install and configure your plugin, run a request.
Switch to your Stellate service view.
Click Requests (look in the lower left side of the screen).

Improve the GraphQL Ruby Plugin Speed

The Stellate GraphQL Ruby plugin includes the Non-Blocking HTTP requests feature to address slow response times caused by blocking HTTP requests to Stellate. By adding a callback function, you can now work around this issue.

Non-Blocking HTTP requests

By default, this plugin performs blocking HTTP requests to log requests or sync the schema. Stellate does run at the Edge in dozens of locations around the world, but these additional response times still negatively affect the response times for your API.

You can pass a callback function as an argument to the execute with login function, allowing users to handle the HTTP request asynchronously. This change significantly improves the speed of the request. To use the callback argument for both the execute with login and sync functions, we allow you to move these blocking HTTP requests into any non-blocking process. This can be achieved by passing the callback function like so:

# Define a method that will set up a non-blocking process
def my_callback(http_to_stellate)
  # `http_to_stellate` is a lambda that will perform the HTTP request to
  # Stellate, you can set up any async side-process here or queue this task
  # with something like Sidekiq.

  # Invoke the lambda like this:
  http_to_stellate.call
end

# Pass the callback to the schema syncing like so:
class MySchema < GraphQL::Schema
  # ...

  use Stellate::SchemaSyncing, callback: :my_callback

  # ...
end

# Pass the callback to the request logging like so:
MySchema.execute_with_logging(
  # GraphQL-specific arguments
  query,
  variables:, context:, operation_name:,
  # Stellate-specific arguments
  headers: request.headers, callback: :my_callback
)

Additionally, you can use tools like Sidekiq for scheduling asynchronous processes.