Documentation

New Relic

Elevate, May 20-22-2025, Miami Beach, Florida

Monitor and observe your SDK with New Relic.

New Relic supports different languages, frameworks, and platforms to retrieve metrics and traces.

Java SDK

Prerequisites

Include the New Relic middleware in the Java SDK

The Java SDK integrates with New Relic through the commercetools-monitoring-newrelic module.
After adding commercetools-monitoring-newrelic as a dependency in your application, add the New Relic middleware to your SDK using the .withTelemetryMiddleware() method.
ApiHttpClient apiHttpClient = ApiRootBuilder
  .of()
  .defaultClient(ServiceRegion.GCP_EUROPE_WEST1.getApiUrl())
  .withTelemetryMiddleware(new NewRelicTelemetryMiddleware())
  .buildClient();
NewRelicTelemetryMiddleware reads NewRelicContext from the request, restores the transaction context, and logs request-response details to New Relic as external calls.
To create a trace per web request, such as in a Spring boot application, create a client with the New Relic transaction. You can achieve this by using the SDK's ContextClient.
ContextApiHttpClient contextClient = ContextApiHttpClient.of(
  apiHttpClient,
  NewRelicContext.of(NewRelic.getAgent().getTransaction()),
  false // don't close the ApiHttpClient
);
ProjectApiRoot apiRoot = ProjectApiRoot.fromClient(projectKey, contextClient);
The ContextClient adds the NewRelicContext object to every API request to ensure that even asynchronous calls in different threads are instrumented.
To adhere to best practices, reuse the API Client across the application lifetime. You should also ensure the ContextClient is configured to leave the inner client open, even if the ContextClient itself is closed.
The commercetools-monitoring-newrelic module includes a telemetry middleware and a serializer that adds the following metrics:
Metric nameDescriptionUnit
Custom/Commercetools/Client/Request/TotalNumber of requests made by the SDK.Count
Custom/Commercetools/Client/Request/ErrorNumber of requests made by the SDK with an HTTP error response (status code between 400 and 599).Count
Custom/Commercetools/Client/DurationDuration of the request to commercetools Composable Commerce.Milliseconds
Custom/Commercetools/Json/SerializationDuration of the JSON serialization of the response from Composable Commerce.Milliseconds
Custom/Commercetools/Json/DeserializationDuration of the JSON deserialization of the request to Composable Commerce.Milliseconds

The metrics are created as metric timeslice data and therefore requires the New Relic Application Performance Monitoring in your application.

For an example of integrating New Relic with the Java SDK, refer to the Spring Boot New Relic example application.

TypeScript SDK

Prerequisites

The TypeScript SDK uses the @commercetools/ts-sdk-apm package and the withTelemetryMiddleware() middleware builder method to integrate with New Relic and OpenTelemetry. This setup allows for the collection and uploading of metrics and trace data to New Relic, enhancing monitoring capabilities.
See the New Relic Express example application for a demonstration of using New Relic with the TypeScript SDK.

Include the monitoring package in the TypeScript SDK

The following code example demonstrates how to set up your SDK client for using New Relic monitoring.

// Import the @commercetools/ts-sdk-apm package
import { createTelemetryMiddleware } from '@commercetools/ts-sdk-apm'
import { ClientBuilder } from '@commercetools/ts-client'

// Configure the telemetry options
const telemetryOptions = {
  apm: () => require('newrelic'),
  userAgent: 'typescript-sdk-middleware-newrelic',
  createTelemetryMiddleware,
  customMetrics: {
    newrelic: true,
  },
}

// Create the client with the withTelemetryMiddleware() middleware
const client = new ClientBuilder()
  .withClientCredentialsFlow(...)
  .withHttpMiddleware(...)
  .withTelemetryMiddleware(telemetryOptions) // telemetry middleware
  ...
  .build()

Add the New Relic agent configuration

After the New Relic agent is installed, create a file named newrelic.js in your project root and then copy this code into it. You must modify app_name and license_key to match your New Relic profile.
You can view the default New Relic agent configurations for all the possible and implementable configurations here.

You should require the configuration file during application launch either by adding it at the first line of the application entry module/file or as a command-line argument. Both approaches produce the same result.

Require the New Relic Agent configuration filetypescript
// app.js
require('./path/to/newrelic.js') // require the nodejs New relic agent configuration here
import express from 'express'
...
const app = express()

app.listen('8000', function() {
  console.log(`server listening on port ${8000}`)
})
Command for requiring the New Agent configuration filejson
{
  "script": {
    "start": "node -r ./path/to/newrelic.js app.js"
  }
}
For more examples about integrating NewRelic with the TypeScript SDK, see the NewRelic example application. In the same folder, there are some examples about how to set up custom metrics like the ones mentioned here:
Metric nameDescriptionUnit
Custom/Commercetools/Client/Request/TotalNumber of requests made to Composable Commerce APIs, representing the volume of interactions from your application.Count
Custom/Commercetools/Client/Request/SuccessNumber of requests made by the SDK with an HTTP success response (status code between 200 and 399).Count
Custom/Commercetools/Client/Request/ErrorNumber of requests made by the SDK with an HTTP error response (status code between 400 and 599).Count

This example includes the metric to count all the successful client responses:

Create custom metrics to see successful client responsestypescript
newrelic.recordMetric(`Service/Response/Success/${statusCode}`, statusCode);

Alternatively, you can include this metric to count all the client requests:

Create custom metrics to see all client requeststypescript
newrelic.recordMetric(`Commercetools/Client/Request/Total`, count();
For more information about Custom/Commercetools/Client/Request/Successand Custom/Commercetools/Client/Request/Error custom metrics, see here. And for more information about Custom/Commercetools/Client/Request/Total, see this file.
For more information about the various custom metrics that the New Relic Node.js agent can capture, see NewRelic's documentation.

PHP SDK

Prerequisites

Include the monitoring package in the PHP SDK

The New Relic PHP Agent supports the Guzzle HTTP client, so New Relic can monitor each API call without extra configuration in the SDK Client.
The Symfony demo app demonstrates how to include New Relic in the PHP SDK using a Docker environment.

.NET SDK

Include the monitoring package in the .NET SDK

The New Relic agent supports the monitoring of async methods. New Relic can trace API calls without extra configuration using auto instrumentation.

The NewRelicExample App demonstrates how to profile applications using New Relic.

Use the New Relic dashboard

You can now send requests in your application to commercetools Composable Commerce through your SDK and monitor the reported data dashboard, telemetry, and performance statistics in New Relic.
For more information on using the New Relic dashboard, consult Understand your system with the New Relic entity explorer, Lookout, and Navigator and other New Relic documentation.