New Relic

Java SDK

Prerequisites

• Version 13.1 (or later) of the Java SDK
• New Relic Java agent configured

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:

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

• Version 2.3.0 (or later) of the TypeScript SDK
• Version 1.0.0 (or later) of the @commercetools/ts-sdk-apm
• Version 10.0.0 (or later) of New Relic's Node.js agent
• New Relic Node.js agent configured

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/sdk-client-v2'

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

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

Add the New Relic agent configuration

Once the New Relic agent is installed, create a file named newrelic.js in your project root and copy the following code into it. You should modify app_name and license_key to match your New Relic profile.

('use strict');
/**
 * New Relic agent configuration.
 *
 * See lib/config/default.js in the agent distribution for a more complete
 * description of configuration variables and their potential values.
 */
exports.config = {
  /**
   * Array of application names.
   */
  app_name: [process.env.NEW_RELIC_APP_NAME],
  /**
   * Your New Relic license key.
   */
  license_key: process.env.NEW_RELIC_LICENSE_KEY,
  logging: {
    /**
     * Level at which to log. 'trace' is most useful to New Relic when diagnosing
     * issues with the agent, 'info', and higher will impose the least overhead on
     * production applications.
     */
    level: 'info',
  },
  /**
   * When true, all request headers except for those listed in attributes.exclude
   * will be captured for all traces, unless otherwise specified in a destination's
   * attributes include/exclude lists.
   */
  allow_all_headers: true,
  attributes: {
    /**
     * Prefix of attributes to exclude from all destinations. Allows * as wildcard
     * at end.
     *
     * NOTE: If excluding headers, they must be in camelCase form to be filtered.
     *
     * @env NEW_RELIC_ATTRIBUTES_EXCLUDE
     */
    exclude: [
      'request.headers.cookie',
      'request.headers.authorization',
      'request.headers.proxyAuthorization',
      'request.headers.setCookie*',
      'request.headers.x*',
      'response.headers.cookie',
      'response.headers.authorization',
      'response.headers.proxyAuthorization',
      'response.headers.setCookie*',
      'response.headers.x*',
    ],
  },
};

An example newrelic.js file is also available in the New Relic Express example application. 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.

// 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}`)
})

{
  "script": {
    "start": "node -r ./path/to/newrelic.js app.js"
  }
}

Include the New Relic Node.js Agent to add the following custom metrics:

You can capture other custom metrics using the Node.js New Relic agent. You can find example usage of custom metrics in our New Relic Express example application.

The New Relic Express example application also contains example use of the command-line configuration.

PHP SDK

Prerequisites

• PHP 8.1 (or later)
• New Relic Agent & Daemon configured

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.

Using 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.