---
title: Cross application tracing in Ruby
source: https://docs.newrelic.com/docs/apm/agents/ruby-agent/features/cross-application-tracing-ruby
---

> #### ⚠️ IMPORTANT
>
> As of version 8.0.0 of the Ruby agent, [distributed tracing](https://docs.newrelic.com/docs/apm/distributed-tracing/getting-started/introduction-distributed-tracing) is on by default. Distributed tracing improves on cross application tracing and is recommended for large, distributed systems.
>
> Cross application tracing is deprecated in favor of distributed tracing and will be removed in a future agent version. If you need to continue using cross application tracing, such as for a non-standard middleware framework, see the [configuration information](#configuration) in this document.

## Requirements

Follow these requirements to use cross application tracing with the Ruby agent:

1.  Make sure the requests being instrumented use a [supported HTTP client library](https://docs.newrelic.com/docs/ruby/ruby-http-clients).
2.  Install or update to the [latest Ruby agent](https://docs.newrelic.com/docs/ruby/ruby-agent-installation) (version 3.5.5.38 or higher).
3.  Follow the requirements for middleware installation.

## Middleware installation [#middleware]

Cross application tracing works with Rack, and therefore requires Rails 2.3 or greater, or another compatible framework.

-   If you use Rails, the Ruby agent will install the middleware automatically.
-   If you use a different Rack-based framework, manually add the `NewRelic::Rack::AgentHooks` middleware to your stack.

## Configuration [#configuration]

Cross application tracing can be controlled by a configuration flag. As of version 8.0.0 of the Ruby agent, the default for `cross_application_tracer.enabled` is `false`, even when unspecified. To enable cross application tracing, you must set this flag to `true` amd set `distributed_tracing.enabled` to `false`.

```yaml
cross_application_tracer:
  enabled: true
distributed_tracing:
  enabled: false
```

For versions below 8.0.0, cross application can be configured using the following setting.

```yaml
cross_application_tracer:
  enabled: true
```

## Cross application trace measurements [#cat-measurements]

The **external** measurement (from the calling application) will always be larger than the **internal** measurement (from the called application). The external measurement is collected by New Relic's instrumentation of the HTTP client library (such as Net::HTTP). The internal measurement is taken by New Relic's instrumentation of the web framework (such as Rails) in the called application.

Here are some of the major components included in the external measurement that are **not** included in the internal measurement:

**From calling app to target host**

-   DNS time to resolve the target hostname
-   Time to establish a new TCP connection with the target host (TCP 3-way handshake plus SSL negotiation, if SSL is in use)
-   Time spent in the HTTP client library to prepare and serialize the HTTP request
-   Network latency to send the request across the wire to the target host

**Receiving host**

-   Time for the frontend web server on the receiving host to process the request and send it to the backend web server on the receiving host

-   Time for the request to be parsed in the backend web server on the receiving host

-   Time for the request to "percolate" through Rack middlewares on the receiving host

-   Time for the web framework to route the request to the appropriate controller action

    Once the web framework has routed it to the appropriate controller action, this is where the internal measurement happens. Then:

-   Time for the request to "percolate" back up through the Rack middlewares

-   Network latency to write the response back to the requesting server

-   Time on the requesting host for the HTTP response to be parsed by the HTTP client library

Some of these components are easier to control than others. For example, to capture timings for the **Receiving host** items above, make sure you have [request queue monitoring](https://docs.newrelic.com/docs/features/configuring-request-queue-reporting) set up on the receiving application.

## Get distributed tracing [#distributed-tracing]

As of version 8.0.0 of the Ruby agent, [distributed tracing](https://docs.newrelic.com/docs/apm/distributed-tracing/getting-started/introduction-distributed-tracing) is on by default. Distributed tracing is an improvement on cross application tracing and is recommended for large, distributed systems.