Tracing

GraphQL::Tracing provides a .trace hook to observe events from the GraphQL runtime.

A tracer must implement .trace, for example:

class MyCustomTracer
  def self.trace(key, data)
    # do stuff with key & data
    yield
  end
end

.trace is called with:

key: the event happening in the runtime
data: a hash of metadata about the event
&block: the event itself, it must be yielded and the value must be returned

To run a tracer for every query, add it to the schema with tracer:

# Run `MyCustomTracer` for all queries
class MySchema < GraphQL::Schema
  tracer(MyCustomTracer)
end

Or, to run a tracer for one query only, add it to context: as tracers: [...], for example:

# Run `MyCustomTracer` for this query
MySchema.execute(..., context: { tracers: [MyCustomTracer]})

For a full list of events, see the GraphQL::Tracing API docs.

ActiveSupport::Notifications

You can emit events to ActiveSupport::Notifications with an experimental tracer, ActiveSupportNotificationsTracing.

To enable it, install the tracer:

# Send execution events to ActiveSupport::Notifications
class MySchema < GraphQL::Schema
  tracer(GraphQL::Tracing::ActiveSupportNotificationsTracing)
end

Monitoring

Several monitoring platforms are supported out-of-the box by GraphQL-Ruby (see platforms below).

Leaf fields are not monitored (to avoid high cardinality in the metrics service).

Implementations are based on Tracing::PlatformTracing.

Appsignal

To add AppSignal instrumentation:

class MySchema < GraphQL::Schema
  use(GraphQL::Tracing::AppsignalTracing)
end

/queries/appsignal_example.png

New Relic

To add New Relic instrumentation:

class MySchema < GraphQL::Schema
  use(GraphQL::Tracing::NewRelicTracing)
  # Optional, use the operation name to set the new relic transaction name:
  # use(GraphQL::Tracing::NewRelicTracing, set_transaction_name: true)
end

/queries/new_relic_example.png

Scout

To add Scout APM instrumentation:

class MySchema < GraphQL::Schema
  use(GraphQL::Tracing::ScoutTracing)
end

/queries/scout_example.png

Skylight

To add Skylight instrumentation, you may either enable the GraphQL probe or use ActiveSupportNotificationsTracing.

# config/application.rb
config.skylight.probes << "graphql"

/queries/skylight_example.png

GraphQL instrumentation for Skylight is available in versions >= 4.2.0.

Datadog

To add Datadog instrumentation:

class MySchema < GraphQL::Schema
  use(GraphQL::Tracing::DataDogTracing, options)
end

You may provide options as a Hash with the following values:

Key	Description	Default
`analytics_enabled`	Enable analytics for spans. `true` for on, `nil` to defer to Datadog global setting, `false` for off.	`false`
`analytics_sample_rate`	Rate which tracing data should be sampled for Datadog analytics. Must be a float between `0` and `1.0`.	`1.0`
`service`	Service name used for `graphql` instrumentation	`'ruby-graphql'`
`tracer`	`Datadog::Tracer` used to perform instrumentation. Usually you don’t need to set this.	`Datadog.tracer`

For more details about Datadog’s tracing API, check out the Ruby documentation or the APM documentation for more product information.

Prometheus

To add Prometheus instrumentation:

require 'prometheus_exporter/client'

class MySchema < GraphQL::Schema
  use(GraphQL::Tracing::PrometheusTracing)
end

The PrometheusExporter server must be run with a custom type collector that extends GraphQL::Tracing::PrometheusTracing::GraphQLCollector:

# lib/graphql_collector.rb

require 'graphql/tracing'

class GraphQLCollector < GraphQL::Tracing::PrometheusTracing::GraphQLCollector
end

bundle exec prometheus_exporter -a lib/graphql_collector.rb