# OpenTelemetry

Monitor and observe your SDK with OpenTelemetry.

[OpenTelemetry](https://opentelemetry.io/docs/) is an observability framework and toolkit designed to create and manage telemetry data such as traces, metrics, and logs. You can use OpenTelemetry with a wide range of observability backends, including open-source tools like [Jaeger](https://www.jaegertracing.io/) and [Prometheus](https://prometheus.io/).

## Java SDK

### Prerequisites

- OpenTelemetry automatic instrumentation agent [configured](https://opentelemetry.io/docs/instrumentation/java/automatic/)

### Include OpenTelemetry monitoring in the Java SDK

The OpenTelemetry agent supports the `CompletableFutures` and HTTP clients used by the Java SDK, so you can trace every API call with OpenTelemetry without extra configuration in the SDK Client.

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

| Metric name | Description | Unit | Attributes |
| --- | --- | --- | --- |
| `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 OpenTelemetry with the Java SDK, refer to the [spring-otel](https://github.com/commercetools/commercetools-sdk-java-v2/tree/main/examples/spring-otel) example application.

```java title="Create a Java SDK client with telemetry middleware"
ApiRootBuilder
  .of()
  .defaultClient(credentials())
  .withSerializer(
    new OpenTelemetryResponseSerializer(
      ResponseSerializer.of(),
      GlobalOpenTelemetry.get()
    )
  )
  .withTelemetryMiddleware(
    new OpenTelemetryMiddleware(GlobalOpenTelemetry.get())
  )
  .build(projectKey);
```

The corresponding metric displays as follows in Prometheus:

![Prometheus metrics](https://docs.commercetools.com/dev-tooling/images/observability/otel-prometheus.png)

## 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
- OpenTelemetry instrumentation agent check the [documentation](https://opentelemetry.io/docs/languages/js/instrumentation/)

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 the OpenTelemetry collector with the TypeScript SDK.

## PHP SDK

### Prerequisites

- OpenTelemetry instrumentation agent for [Packagist](https://opentelemetry.io/docs/zero-code/php/)

### Include OpenTelemetry monitoring in the PHP SDK

The PHP SDK is fully compatible with OpenTelemetry for tracing async methods and HTTP client communications without additional configuration.

The [Symfony demo app](https://github.com/commercetools/commercetools-sdk-php-v2/tree/master/examples/symfony-app-opentelemetry) shows how to add OpenTelemetry as a collector in the PHP SDK by using Docker and then view the results in the New Relic UI.

## .NET SDK

### Prerequisites

- OpenTelemetry instrumentation agent for NuGet [configured](https://opentelemetry.io/docs/instrumentation/net/automatic/)

### Include OpenTelemetry monitoring in the .NET SDK

The .NET SDK is compatible with OpenTelemetry for tracing async methods and HTTP client communications without additional configuration.

The example [Me Endpoint Checkout App](https://github.com/commercetools/commercetools-dotnet-core-sdk-v2/tree/master/commercetools.Sdk/Examples/commercetools.Api.CheckoutApp#opentelemetry) exports traces and metrics to the command-line. By using the application config file, you can export them to an OpenTelemetry Protocol (OTLP) endpoint.

## Use the OpenTelemetry collector

For testing purposes, we provide a [OpenTelemetry Collector](https://github.com/commercetools/opentelemetry-collector-example) setup with Docker. It includes an OpenTelemetry collector, a Jaeger UI, Prometheus, [Grafana](https://grafana.com/oss/), New Relic, Dynatrace, and Datadog as export targets. Every commercetools SDK supports the OpenTelemetry Collector.

![Traces in the Jaegar UI](https://docs.commercetools.com/dev-tooling/images/observability/otel-jaeger-ui.png)

![Trace tags in Jaegar](https://docs.commercetools.com/dev-tooling/images/observability/otel-jaeger-ui-tags.png)

### Export to third-party observability tools

#### New Relic

To export to New Relic, do the following:

1. Add your New Relic license key to the `.env` [file](https://github.com/commercetools/opentelemetry-collector-example/blob/main/.env#L41).
2. Uncomment the New Relic command in the `docker-compose.yml` [file](https://github.com/commercetools/opentelemetry-collector-example/blob/main/docker-compose.yaml#L66).

#### Dynatrace

To export to Dynatrace, do the following:

1. Add your Dynatrace OTLP endpoint and API token to the `.env` [file](https://github.com/commercetools/opentelemetry-collector-example/blob/main/.env#L43-L45).
2. Uncomment the Dynatrace command in the `docker-compose.yml` [file](https://github.com/commercetools/opentelemetry-collector-example/blob/main/docker-compose.yaml#L68).

#### Datadog

To export to Datadog, do the following:

1. Add `DATADOG_API_KEY` to the `.env` [file](https://github.com/commercetools/opentelemetry-collector-example/blob/9fbe190e6b079862252cb455fac3b89bae4d8b77/.env#L48).
2. Update the `DATADOG_SITE` [variable](https://github.com/commercetools/opentelemetry-collector-example/blob/9fbe190e6b079862252cb455fac3b89bae4d8b77/.env#L49) if you are not using the `EU1` [Datadog site](https://docs.datadoghq.com/getting_started/site/#access-the-datadog-site).
3. Uncomment the Datadog command in the `docker-compose.yml` [file](https://github.com/commercetools/opentelemetry-collector-example/blob/9fbe190e6b079862252cb455fac3b89bae4d8b77/docker-compose.yaml#L70).

## Related pages

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