gRPC instrumentation

The New Relic Ruby agent automatically instruments gRPC clients and servers that use the grpc gem (version 1.0.0 or higher). All communication types are supported: unary, bidirectional, client-streaming, and server-streaming.

Configuration (all settings are optional)

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

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

Use the following only for clients:

• config file parameter: instrumentation.grpc_client
• environment variable: NEW_RELIC_INSTRUMENTATION_GRPC_CLIENT

Server-specific options

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

To disable gRPC server instrumentation via the config file:

# newrelic.yml
instrumentation.grpc_server: disabled

To disable the gRPC client instrumentation via an environment variable:

$
export NEW_RELIC_INSTRUMENTATION_GRPC_CLIENT=disabled

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):

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

Usage

As long as the instrumentation is working properly (see 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.

View data

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

Summary page

On the UI Summary 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

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

1. Go to 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

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)