tracing.md

title	layout	doc_stub	search	section	desc	index	redirect_from
Tracing	guide	false	true	Queries	Observation hooks for execution	11	/queries/instrumentation

{{ "GraphQL::Tracing::Trace" | api_doc }} provides hooks to observe and modify events during runtime. Tracing hooks are methods, defined in modules and mixed in with {{ "Schema.trace_with" | api_doc }}.

module CustomTrace
  def parse(query_string:)
    # measure, log, etc
    super
  end

  # ...
end

To include a trace module when running queries, add it to the schema with trace_with:

# Run `MyCustomTrace` for all queries
class MySchema < GraphQL::Schema
  trace_with(MyCustomTrace)
end

For a full list of methods and their arguments, see {{ "GraphQL::Tracing::Trace" | api_doc }}.

By default, GraphQL-Ruby makes a new trace instance when it runs a query. You can pass an existing instance as context: { trace: ... }. Also, GraphQL.parse( ..., trace: ...) accepts a trace instance.

Trace Modes

You can attach a trace module to run only in some circumstances by using mode:. For example, to add detailed tracing for only some requests:

trace_with DetailedTrace, mode: :detailed_metrics

Then, to opt into that trace, use context: { trace_mode: :detailed_metrics, ... } when executing queries.

Any custom trace modes also include the default trace_with ... modules (that is, those added without any particular mode: ... configuration).

ActiveSupport::Notifications

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

To enable it, install the tracer:

# Send execution events to ActiveSupport::Notifications
class MySchema < GraphQL::Schema
  trace_with(GraphQL::Tracing::ActiveSupportNotificationsTrace)
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).

AppOptics

AppOptics instrumentation will be automatic starting with appoptics_apm-4.11.0.gem. For earlier gem versions please add appoptics_apm tracing as follows:

require 'appoptics_apm'

class MySchema < GraphQL::Schema
  trace_with GraphQL::Tracing::AppOpticsTrace
end

{{ "/queries/appoptics_example.png" | link_to_img:"appoptics monitoring" }}

Appsignal

To add AppSignal instrumentation:

class MySchema < GraphQL::Schema
  trace_with GraphQL::Tracing::AppsignalTrace
end

{{ "/queries/appsignal_example.png" | link_to_img:"appsignal monitoring" }}

New Relic

To add New Relic instrumentation:

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

{{ "/queries/new_relic_example.png" | link_to_img:"new relic monitoring" }}

Scout

To add Scout APM instrumentation:

class MySchema < GraphQL::Schema
  trace_with GraphQL::Tracing::ScoutTrace
end

{{ "/queries/scout_example.png" | link_to_img:"scout monitoring" }}

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" | link_to_img:"skylight monitoring" }}

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

Datadog

To add Datadog instrumentation:

class MySchema < GraphQL::Schema
  trace_with GraphQL::Tracing::DataDogTrace
end

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
  trace_with GraphQL::Tracing::PrometheusTrace
end

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

# lib/graphql_collector.rb
if defined?(PrometheusExporter::Server)
  require 'graphql/tracing'

  class GraphQLCollector < GraphQL::Tracing::PrometheusTrace::GraphQLCollector
  end
end

bundle exec prometheus_exporter -a lib/graphql_collector.rb

Sentry

To add Sentry instrumentation:

class MySchema < GraphQL::Schema
  trace_with GraphQL::Tracing::SentryTrace
end

{{ "/queries/sentry_example.png" | link_to_img:"sentry monitoring" }}

Statsd

You can add Statsd instrumentation by initializing a statsd client and passing it to {{ "GraphQL::Tracing::StatsdTrace" | api_doc }}:

$statsd = Statsd.new 'localhost', 9125
# ...

class MySchema < GraphQL::Schema
  use GraphQL::Tracing::StatsdTrace, statsd: $statsd
end

Any Statsd client that implements .time(name) { ... } will work.