---
title: gRPC instrumentation
source: https://docs.newrelic.com/docs/apm/agents/ruby-agent/instrumented-gems/grpc-instrumentation
---

The [New Relic Ruby agent](https://docs.newrelic.com/docs/agents/ruby-agent/getting-started/new-relic-ruby) automatically instruments [gRPC](https://grpc.io/) clients and servers that use the [grpc](https://rubygems.org/gems/grpc) gem (version 1.0.0 or higher). All communication types are supported: unary, bidirectional, client-streaming, and server-streaming.

> #### ⚠️ IMPORTANT
>
> gRPC instrumentation requires Ruby agent version 8.10.0 or higher.

## Configuration (all settings are optional) [#config-overview]

You can configure the instrumentation of gRPC clients and servers separately. By default, both configuration options are set to `auto`, which is short for `automatic`. The agent's automatic behavior for each is to enable the instrumentation by attempting to leverage Ruby module prepend behavior at first and falling back on Ruby method chaining behavior if known compatibility issues are encountered.

See additional options and examples in the sections that follow.

### Client and server options [#combined-options]

You can alter the behavior of the agent by modifying the New Relic config file or by setting environment variables. Here are the options that apply to both clients and servers:

-   `auto`: The default that is enabled via automatic Ruby method behavior selection
-   `disabled`: Instrumentation disabled
-   `prepend`: Force the use of Ruby method prepending
-   `chain`: Force the use of Ruby method chaining

### Client-specific options [#client-specific]

Use the following only for clients:

-   config file parameter: `instrumentation.grpc_client`
-   environment variable: `NEW_RELIC_INSTRUMENTATION_GRPC_CLIENT`

### Server-specific options [#server-specific]

Use the following only for servers:

-   config file parameter: `instrumentation.grpc_server`
-   environment variable: `NEW_RELIC_INSTRUMENTATION_GRPC_SERVER`

### Examples of client and server configuration [#combined-examples]

To disable gRPC server instrumentation via the config file:

```yml
# newrelic.yml
instrumentation.grpc_server: disabled
```

To disable the gRPC client instrumentation via an environment variable:

```sh
export NEW_RELIC_INSTRUMENTATION_GRPC_CLIENT=disabled
```

## Verification [#verification]

Once the New Relic Ruby agent starts, it will detect the presence of the `grpc` gem having been loaded and then attempt to apply gRPC instrumentation. When successful at applying this instrumentation for the gRPC client and server components, the agent will write the following lines to its log file (`log/newrelic_agent.log` by default):

```log
INFO : Installing New Relic supported gRPC_Client instrumentation using Prepend
INFO : Installing New Relic supported gRPC_Server instrumentation using Prepend
```

## Usage [#usage]

As long as the instrumentation is working properly (see [Verification](#verification) above to confirm this), all instrumentation performed by the New Relic Ruby agent should be fully automatic and not require any modifications to any of your existing gRPC client and/or server code.

The New Relic Ruby agent's gRPC instrumentation includes distributed tracing headers in spans, which allows gRPC client and server calls to be connected to any other service that supports W3C distributed tracing. gRPC requests can be sent from a Ruby-based client to a server based on another language, and a Ruby-based server can field requests coming from a client based on another language.

> #### ⚠️ IMPORTANT
>
> gRPC client requests will not be reported to New Relic unless they are spawned when an existing New Relic transaction is present. Typically this means that a Rails controller method or background job process is active and responsible for the invocation of the gRPC client request. The request will then roll up under that outer wrapper's transaction in the New Relic web UI.
>
> gRPC server requests will always generate a new New Relic transaction and will not require nor roll-up to any pre-existing New Relic transaction.

## View data [#view-data]

You can see the collected gRPC data on a number of pages in the New Relic UI.

### Summary page [#summary]

On the UI [Summary page](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/apm-overview-page), gRPC client requests appear as web transactions and contribute data to the following charts: **Web transactions time**, **Throughput**, and **Error rate**.

### Distributed tracing page [#distributed-tracing-page]

> #### 💡 TIP
>
> Distributed tracing is turned on by default in new Ruby agents, but if you have questions, see [Distributed tracing for your Ruby services](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/distributed-tracing-ruby-agent/).

Check out gRPC data on the distributed tracing page of the UI:

1.  Go to **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > APM & services**.
2.  Click your entity (service).
3.  In the left pane's **Monitor** section, click **Distributed tracing**.
4.  Click on a trace group.
5.  Choose a trace from the list, and click on it.
6.  Click **Expand all**.
7.  From the resulting list of trace spans, click on an individual trace span.
8.  Click the **Attributes** tab in the right pane.
    -   **Client instances:** The `grpc_status`, `grpc_type`, `http.method`, and `http.url` attributes should all appear. In the event of a failed client request (which will have a `grpc_status` value other than `0`), an additional `grpc_message` attribute will appear with the gRPC status message.
    -   **Server instances:** The `request.grpc_type`, `request.method`, and `request.uri` attributes should all appear.

As long as both the client and server applications are being monitored by a New Relic agent with support for gRPC (in Ruby or another language), the distributed tracing map should do the following:

-   Display both the client and server applications.
-   Report on how many distinct call types were performed between them.

In the event of a gRPC-based Ruby exception, information about the exception will appear on the **Events > Errors** page.

## Support and feedback [#support-feedback]

When contacting New Relic for support and/or feedback related to the New Relic Ruby agent's gRPC instrumentation, please try to have answers to the following questions:

-   What version of the `grpc` gem are you using?
-   Do you use New Relic Infinite Tracing?
-   How would you describe your application's environment? (Framework, Ruby version, other key technologies used)
-   What do you use gRPC for?
-   Do you use Ruby for gRPC clients?
-   Do you use a different language for gRPC clients?
-   Do you use Ruby for gRPC servers?
-   Do you use a different language for gRPC servers?
-   Where are you calling your gRPC client code? (from a controller, a background job, etc.)
-   What strategy/strategies are you using to send your data? (unary, bidirectional, client-streaming, server-streaming)