# New Relic

Monitor and observe your SDK with New Relic.

[New Relic](https://docs.newrelic.com/) supports different languages, frameworks, and platforms to retrieve metrics and traces.

## Java SDK

### Prerequisites

- Version 13.1 (or later) of the Java SDK
- [New Relic Java agent](https://docs.newrelic.com/docs/apm/agents/java-agent/getting-started/introduction-new-relic-java/) configured

### Include the New Relic middleware in the Java SDK

The Java SDK integrates with New Relic through the [commercetools-monitoring-newrelic](https://central.sonatype.com/artifact/com.commercetools.sdk/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.

```java
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`.

```java
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 it instruments every call, including asynchronous calls in different threads.

To adhere to best practices, reuse the API Client across the application lifetime. You should also configure the `ContextClient` to leave the inner client open, even after closing the `ContextClient` itself.

The `commercetools-monitoring-newrelic` module includes a telemetry middleware and a serializer that adds the following metrics:

| Metric name | Description | Unit |
| --- | --- | --- |
| `Custom/Commercetools/Client/Request/Total` | Number of requests made by the SDK. | Count |
| `Custom/Commercetools/Client/Request/Error` | Number of requests made by the SDK with an HTTP error response (status code between `400` and `599`). | Count |
| `Custom/Commercetools/Client/Duration` | Duration of the API request. | Milliseconds |
| `Custom/Commercetools/Json/Serialization` | Duration of the JSON serialization of the API response. | Milliseconds |
| `Custom/Commercetools/Json/Deserialization` | Duration of the JSON deserialization of the API request. | 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](https://github.com/commercetools/commercetools-sdk-java-v2/tree/main/commercetools/commercetools-monitoring-newrelic).

## TypeScript SDK

### Prerequisites

- Version 3.0.0 (or later) of the [@commercetools/ts-client](https://www.npmjs.com/package/@commercetools/ts-client)
- Version 1.0.0 (or later) of the [@commercetools/ts-sdk-apm](https://www.npmjs.com/package/@commercetools/ts-sdk-apm)
- Version 10.0.0 (or later) of [New Relic's Node.js agent](https://www.npmjs.com/package/newrelic)
- [New Relic Node.js agent](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/getting-started/introduction-new-relic-nodejs/) configured

The TypeScript SDK uses the [@commercetools/ts-sdk-apm](https://www.npmjs.com/package/@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](https://github.com/commercetools/commercetools-sdk-typescript/tree/master/examples/newrelic-express-apm) 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.

```typescript
// 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 installing the New Relic agent, create a file named `newrelic.js` in your project root and copy [this code](https://github.com/commercetools/commercetools-sdk-typescript/tree/master/examples/newrelic-express-apm/newrelic.js) into it. You must modify `app_name` and `license_key` to match your [New Relic](https://one.newrelic.com/) profile.

You can view the default New Relic agent configurations for all the possible and implementable configurations [here](https://github.com/newrelic/node-newrelic/blob/main/lib/config/default.js).

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.

```typescript title="Require the New Relic Agent configuration file"
// 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}`)
})
```

```json title="Command for requiring the New Agent configuration file"
{
  "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](https://github.com/commercetools/commercetools-sdk-typescript/tree/master/examples/newrelic-express-apm). In the same folder, there are some examples about how to set up custom metrics like the ones mentioned here:

| Metric name | Description | Unit |
| --- | --- | --- |
| `Custom/Commercetools/Client/Request/Total` | Number of requests made to APIs, representing the volume of interactions from your application. | Count |
| `Custom/Commercetools/Client/Request/Success` | Number of requests made by the SDK with an HTTP success response (status code between `200` and `399`). | Count |
| `Custom/Commercetools/Client/Request/Error` | Number 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:

```typescript title="Create custom metrics to see successful client responses"
newrelic.recordMetric(`Service/Response/Success/${statusCode}`, statusCode);
```

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

```typescript title="Create custom metrics to see all client requests"
newrelic.recordMetric(`Commercetools/Client/Request/Total`, count();
```

For more information about `Custom/Commercetools/Client/Request/Success`and `Custom/Commercetools/Client/Request/Error` custom metrics, see [here](https://github.com/commercetools/commercetools-sdk-typescript/blob/master/examples/newrelic-express-apm/src/utils/response.js). And for more information about `Custom/Commercetools/Client/Request/Total`, see [this file](https://github.com/commercetools/commercetools-sdk-typescript/blob/master/examples/newrelic-express-apm/src/app.js).

For more information about the various custom metrics that the New Relic Node.js agent can capture, see [NewRelic's documentation](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/extend-your-instrumentation/nodejs-custom-metrics).

## PHP SDK

### Prerequisites

- PHP 8.1 (or later)
- New [Relic Agent & Daemon configured](https://docs.newrelic.com/docs/apm/agents/php-agent/installation/php-agent-installation-overview/#components)

### Include the monitoring package in the PHP SDK

The New Relic PHP Agent supports the [Guzzle HTTP client](https://docs.guzzlephp.org/en/stable/), so New Relic can monitor each API call without extra configuration in the SDK Client.

The [Symfony demo app](https://github.com/commercetools/commercetools-sdk-php-v2/tree/master/examples/symfony-app-newrelic) 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](https://github.com/commercetools/commercetools-dotnet-core-sdk-v2/tree/master/commercetools.Sdk/Examples/commercetools.Api.NewRelicExample#newrelic) demonstrates how to profile applications using New Relic.

## Use the New Relic dashboard

You can now send requests in your application through your SDK and monitor the reported data dashboard, telemetry, and performance statistics in [New Relic](https://one.newrelic.com/).

For more information on using the New Relic dashboard, consult [Understand your system with the New Relic entity explorer, Lookout, and Navigator](https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/core-concepts/new-relic-explorer-view-performance-across-apps-services-hosts/) and other [New Relic documentation](https://docs.newrelic.com/).

## Related pages

- [Area overview page with navigation](/dev-tooling.md)
- [Previous page: Overview](/dev-tooling/observability.md)
- [Next page: Dynatrace](/dev-tooling/observability/dynatrace.md)