# Datadog

Monitor and observe your SDK with Datadog.

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

## Java SDK

### Prerequisites

- Version 17.6 (or later) of the Java SDK
- Active Datadog account with an [API key](https://docs.datadoghq.com/account_management/api-app-keys/)

### Include the Datadog middleware in the Java SDK

The Java SDK integrates with Datadog through the [commercetools-monitoring-datadog](https://central.sonatype.com/artifact/com.commercetools.sdk/commercetools-monitoring-datadog) module.

After adding `commercetools-monitoring-datadog` as a dependency in your application, add the Datadog middleware and serializer to your SDK using the `.withTelemetryMiddleware()` and `withSerializer()` methods.

```java title="Create a Java SDK client with Datadog telemetry middleware"
ApiHttpClient apiHttpClient = ApiRootBuilder
  .of()
  .defaultClient(ServiceRegion.GCP_EUROPE_WEST1.getApiUrl())
  .withTelemetryMiddleware(
    new DatadogMiddleware(ApiClient.getDefaultApiClient())
  )
  .withSerializer(
    new DatadogResponseSerializer(
      ResponseSerializer.of(),
      ApiClient.getDefaultApiClient()
    )
  )
  .buildClient();
```

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

| Metric name | Description | Unit | Tags |
| --- | --- | --- | --- |
| `commercetools.client.total_requests` | Number of requests made by the SDK. | Count | `http.response.status_code``http.request.method``server.address``server.port` |
| `commercetools.client.error_requests` | Number of requests made by the SDK with an HTTP error response (status code between `400` and `599`). | Count | `http.response.status_code``http.request.method``server.address``server.port` |
| `commercetools.client.duration` | Duration of the API request. | Milliseconds | `http.response.status_code``http.request.method``server.address``server.port` |
| `commercetools.json.serialization` | Duration of the JSON serialization of the API response. | Milliseconds | `response.body.type` |
| `commercetools.json.deserialization` | Duration of the JSON deserialization of the API request. | Milliseconds | `request.body.type  ` |

For an example of integrating Datadog with the Java SDK, refer to the [Spring Boot Datadog example application](https://github.com/commercetools/commercetools-sdk-java-v2/tree/main/commercetools/commercetools-monitoring-datadog).

## TypeScript SDK

### Prerequisites

- Version 3.0.0 (or later) of the [@commercetools/ts-client](https://www.npmjs.com/package/@commercetools/ts-client)
- Version 5.5.0 of the Datadog [dd-trace](https://www.npmjs.com/package/dd-trace) package
- Active Datadog account with an [API key](https://docs.datadoghq.com/account_management/api-app-keys/)
- Install the appropriate Datadog [integration](https://docs.datadoghq.com/integrations) for your environment if you are using a non-containerized service or direct host integration
  - You can run the script [install.sh](https://github.com/commercetools/commercetools-sdk-typescript/tree/master/examples/datadog-express-apm/host-agent/install.sh) to install the Datadog agent on macOS

### Include the Datadog middleware in the TypeScript SDK

The TypeScript SDK integrates Datadog using the [@commercetools/ts-sdk-apm](https://www.npmjs.com/package/@commercetools/ts-sdk-apm) module.

Create a [`tracer.js`](https://github.com/commercetools/commercetools-sdk-typescript/blob/master/examples/datadog-express-apm/host-agent/tracer.js) or `tracer.ts` module in your project and add the following:

```typescript title="tracer.ts"
import tracer from 'dd-trace';
tracer.init();
export default tracer;
```

```javascript title="tracer.js"
require('dd-trace').init();
```

After adding `@commercetools/ts-sdk-apm` as a dependency, add the Datadog instrumentation to your app using the [`withTelemetryMiddleware()`](/dev-tooling/ts-sdk-middleware.md#telemetrymiddleware) middleware method.

```typescript title="Create a TypeScript SDK client with Datadog telemetry middleware"
import { ClientBuilder } from '@commercetools/ts-client';
import { createTelemetryMiddleware } from '@commercetools/ts-sdk-apm';

// Configure the telemetry options
const telemetryOptions = {
  createTelemetryMiddleware,
  userAgent: 'typescript-sdk-middleware-datadog',
  tracer: async () => await import('dd-trace').init(),
  customMetrics: {
    datadog: true,
  },
};

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

`@commercetools/ts-sdk-apm` adds the Datadog instrumentation module to monitor request execution and response times along with counters for requests, errors, and other metrics.

You can add custom metrics in your application by including the [Datadog tracing library](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/dd_libraries/nodejs) module and then adding in your code some settings to define your custom metrics as shown in the following examples:

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

```typescript title="Create custom metric to view the error client response"
agent.init().dogstatsd.increment(`ct_error_response_count`, 1, {
  env: 'dev',
  status_code: statusCode,
  http_method: response.req.method,
  success: false,
});
```

This example includes the metric to count all the client requests:

```typescript title="Create custom metric to view all client requests"
agent.dogstatsd.gauge(`ct_request_count`, count(), {
  env: 'dev',
});
```

For more examples about integrating Datadog with the TypeScript SDK by using a `host` or `containerized` agent, see the [Datadog example application](https://github.com/commercetools/commercetools-sdk-typescript/tree/master/examples/datadog-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 | Tags |
| --- | --- | --- | --- |
| `ct_success_response_count` | Number of requests made by the SDK with an HTTP success response (status code between `200` and `399`). | Count | `http.environment``http.status_code``http.method.success<true>` |
| `ct_error_response_count` | Number of requests made by the SDK with an HTTP error response (status code between `400` and `599`). | Count | `http.environment``http.status_code``http.method.success<false>` |
| `ct_request_count` | Number of requests made to the commercetools API, representing the volume of interactions from your application. | Count | `http.environment` |

For more information about `ct_success_response_count`and `ct_error_response_count` custom metrics, see [here](https://github.com/commercetools/commercetools-sdk-typescript/blob/master/examples/datadog-express-apm/host-agent/utils/response.js). And for more information about `ct_request_count`, see [this file](https://github.com/commercetools/commercetools-sdk-typescript/blob/master/examples/datadog-express-apm/host-agent/src/app.js).

For more information about the various custom metrics that the Datadog Node.js agent can capture, see [Datadog's documentation](https://docs.datadoghq.com/metrics/custom_metrics).

## PHP SDK

### Prerequisites

- Version 10.5 (or later) of the PHP SDK

### Datadog Agent

If you want to monitor your application by using [Datadog Agent](https://docs.datadoghq.com/agent/), then there is no need to change the SDK. To install the Datadog Agent on your host and configure it to monitor your application, follow the steps specified in [Datadog's documentation](https://docs.datadoghq.com/agent/).

To test an application with the PHP SDK and Datadog, use the provided [example application](https://github.com/commercetools/commercetools-sdk-php-v2/blob/master/examples/symfony-app-datadog).

## .NET SDK

### Prerequisites

- Version 11.0 (or later) of the .NET SDK

### Datadog Agent

If you want to monitor your application by using [Datadog Agent](https://docs.datadoghq.com/agent/), then there is no need to change the SDK. To install the Datadog Agent on your host and configure it to monitor your application, follow the steps specified in [Datadog's documentation](https://docs.datadoghq.com/agent/).

To test an application with the .NET SDK and Datadog, use the provided [example application](https://github.com/commercetools/commercetools-dotnet-core-sdk-v2/blob/master/commercetools.Sdk/Examples/commercetools.Api.ApmExample/README.md).

## Related pages

- [Area overview page with navigation](/dev-tooling.md)
- [Previous page: OpenTelemetry](/dev-tooling/observability/opentelemetry.md)