OpenTelemetry

Monitor and observe your SDK with OpenTelemetry.

OpenTelemetry 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 and Prometheus.

Java SDK

Prerequisites

OpenTelemetry automatic instrumentation agent configured

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 request to commercetools Composable Commerce.	Milliseconds	`http.response.status_code` `http.request.method` `server.address` `server.port`
`commercetools.json.serialization`	Duration of the JSON serialization of the response from Composable Commerce.	Milliseconds	`response.body.type`
`commercetools.json.deserialization`	Duration of the JSON deserialization of the request to Composable Commerce.	Milliseconds	`request.body.type`

For an example of integrating OpenTelemetry with the Java SDK, refer to the spring-otel example application.

Create a Java SDK client with telemetry middlewareJava

ApiRootBuilder
  .of()
  .defaultClient(credentials())
  .withSerializer(
    new OpenTelemetryResponseSerializer(
      ResponseSerializer.of(),
      GlobalOpenTelemetry.get()
    )
  )
  .withTelemetryMiddleware(
    new OpenTelemetryMiddleware(GlobalOpenTelemetry.get())
  )
  .build(projectKey);

The corresponding metric is displayed as follows in Prometheus:

PHP SDK

Prerequisites

OpenTelemetry instrumentation agent for Packagist

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

Include OpenTelemetry monitoring in the .NET SDK

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

The example Me Endpoint Checkout App is preconfigured to export traces and metrics to the command-line. By using the application config file, you can export them to an OpenTelemetry Protocol (OTLP) endpoint.

Using the OpenTelemetry collector

For testing purposes, we provide a OpenTelemetry Collector setup with Docker. It includes an OpenTelemetry collector, a Jaeger UI, Prometheus, Grafana, New Relic, Dynatrace, and Datadog as export targets. Every commercetools SDK supports the OpenTelemetry Collector.

Exporting to third-party observability tools

New Relic

To export to New Relic, do the following:

Add your New Relic license key to the .env file.
Uncomment the New Relic command in the docker-compose.yml file.

Dynatrace

To export to Dynatrace, do the following:

Add your Dynatrace OTLP endpoint and API token to the .env file.
Uncomment the Dynatrace command in the docker-compose.yml file.

Datadog

To export to Datadog, do the following:

Add DATADOG_API_KEY to the .env file.
Update the DATADOG_SITE variable if you are not using the EU1 Datadog site.
Uncomment the Datadog command in the docker-compose.yml file.