• Easy-to-use trace instrumentation that collects and collates latencydata for your Ruby application. If you just want latency trace datafor your application to appear on the Google Cloud Platform Console,see the section oninstrumenting your app.
• An idiomatic Ruby API for querying, analyzing, and manipulating tracedata in your Ruby application. For an introduction to the Trace API,see the section on theTrace API.

Instrumenting Your App

This library integrates with Rack-based web frameworks such as Ruby OnRails to provide latency trace reports for your application.Specifcally, it:

• Provides a Rack middleware that automatically reports latency tracesfor http requests handled by your application, and measures thelatency of each request as a whole.
• Integrates withActiveSupport::Notifications to add importantlatency-affecting events such as ActiveRecord queries to the trace.
• Provides a simple API for your application code to define andmeasure latency-affecting processes specific to your application.

When this library is installed and configured in your runningapplication, you can view your application's latency traces in real timeby opening the Google Cloud Console in your web browser and navigatingto the "Trace" section. It also integrates with Google App EngineFlexible and Google Container Engine to provide additional informationfor applications hosted in those environments.

Note that not all requests will have traces. By default, the library willsample about one trace every ten seconds per Ruby process, to preventheavily used applications from reporting too much data. It will alsoomit certain requests used by Google App Engine for health checking. SeeGoogle::Cloud::Trace::TimeSampler for more details.

Using instrumentation with Ruby on Rails

To install application instrumentation in your Ruby on Rails app, addthis gem,google-cloud-trace, to your Gemfile and update your bundle.Then add the following line to yourconfig/application.rb file:

require"google/cloud/trace/rails"

This will install a Railtie that automatically integrates with theRails framework, installing the middleware and the ActiveSupportintegration for you. Your application traces, including basic requesttracing, ActiveRecord query measurements, and view render measurements,should then start appearing in the Cloud Console.

See theGoogle::Cloud::Trace::Railtie class for more information,including how to customize your application traces.

Using instrumentation with Sinatra

To install application instrumentation in your Sinatra app, add this gem,google-cloud-trace, to your Gemfile and update your bundle. Then addthe following lines to your main application Ruby file:

require"google/cloud/trace"useGoogle::Cloud::Trace::Middleware

This will install the trace middleware in your application, providingbasic request tracing for your application. You may measure additionalprocesses such as database queries or calls to external services usingother classes in this library. See theGoogle::Cloud::Trace::Middlewaredocumentation for more information.

Using instrumentation with other Rack-based frameworks

To install application instrumentation in an app using another Rack-basedweb framework, add this gem,google-cloud-trace, to your Gemfile andupdate your bundle. Then add install the trace middleware in yourmiddleware stack. In most cases, this means adding these lines to yourconfig.ru Rack configuration file:

require"google/cloud/trace"useGoogle::Cloud::Trace::Middleware

Some web frameworks have an alternate mechanism for modifying themiddleware stack. Consult your web framework's documentation for moreinformation.

The Stackdriver diagnostics suite

The trace library is part of the Stackdriver diagnostics suite, whichalso includes error reporting and log analysis. If you include thestackdriver gem in your Gemfile, this trace library will be includedautomatically. In addition, if you include thestackdriver gem in anapplication using Ruby On Rails, the Railtie will be installedautomatically; you will not need to write any code to view latencytraces for your appl. See the documentation for the "stackdriver" gemfor more details.

Stackdriver Trace API

This library also includes an easy to use Ruby client for theStackdriver Trace API. This API provides calls to report and modifyapplication traces, as well as to query and analyze existing traces.

For further information on the trace API, seeGoogle::Cloud::Trace::Project.

Querying traces using the API

Using the Stackdriver Trace API, your application can query and analyzeits own traces and traces of other projects. Here is an example queryfor all traces in the past hour.

require"google/cloud/trace"trace_client=Google::Cloud::Trace.newtraces=trace_client.list_tracesTime.now-3600,Time.nowtraces.eachdo|trace|puts"Retrieved trace ID:#{trace.trace_id}"end

Each trace is an object of typeGoogle::Cloud::Trace::TraceRecord,which provides methods for analyzing tasks that took place during therequest trace. Seehttps://cloud.google.com/trace for more informationon the kind of data you can capture in a trace.

Reporting traces using the API

Usually it is easiest to use this library's trace instrumentationfeatures to collect and record application trace information. However,you may also use the trace API to update this data. Here is an example:

require"google/cloud/trace"trace_client=Google::Cloud::Trace.newtrace=Google::Cloud::Trace.newtrace.in_span"root_span"do# Do stuff...endtrace_client.patch_tracestrace

Additional information

Stackdriver Trace can be configured to be used in Rack applications or to usegRPC's logging. To learn more, see theInstrumentation Guide andLogging guide.