Platform Insights

With Platform Insights, you can analyze metrics and anticipate issues earlier to deliver more reliable and efficient applications. Platform Insights lets you view server-side metrics derived from server logs. The data from Platform Insights can be integrated and used with the following Application Performance Monitoring (APM) services:

• New Relic
• Datadog
• OpenTelemetry
• Dynatrace

By viewing the performance metrics of Composable Commerce APIs along with your own application data, you can analyze the details of the entire system at one place. This makes it easy and efficient to monitor and manage the health of your application.

Monitor and track API metrics

You can analyze the performance of Composable Commerce APIs by tracking the following Platform Insights metrics in the Metrics section of your preferred APM.

ct_time_sec (Request Processing Time)

ct_time_sec tracks the average time, in seconds, that it takes to process a request in Composable Commerce over a specific period. This metric measures the elapsed time between making an API request and receiving the first byte of the response. It helps you understand the overall performance and efficiency of the API calls.

This data exports as a histogram, showing the distribution of response times for different requests.

ct_response_count (Response Count)

ct_response_count tracks the total number of responses received from Composable Commerce for all API calls during a given period. It offers insights into the volume of processed requests and how end users utilize various API requests and methods.

This metric reports a simple count of responses, grouped by HTTP status.

By monitoring this metric, you can determine peak usage times, identify trends in API consumption, and evaluate whether your application is scaling effectively to manage traffic.

For instance, if you notice that the response count spikes significantly during a marketing campaign or holiday season, you can prepare your system to accommodate the increased load and thereby ensure a smooth user experience.

ct_sent_bytes (Bytes Sent)

ct_sent_bytes represents the total number of bytes that Composable Commerce sends to your end users as part of API responses over a specific duration. This metric helps you gauge the volume of transferred data, understand how API usage impacts bandwidth, and optimize payloads returned by the API.

ct_received_bytes (Bytes Received)

ct_received_bytes tracks the number of bytes received by Composable Commerce from end user requests during a given period. This metric is useful to assess the volume of incoming data traffic patterns and helps ensure your system is capable of managing the data load.

ct_error_count (Error Count)

ct_error_count logs all the requests that returned HTTP error status codes over a specific period, indicating client-side (4xx) or server-side (5xx) errors. This metric is crucial to identify and resolve recurring issues, such as invalid requests or server problems, ensuring a smoother user experience and improving system reliability.

For instance, a sudden spike in errors might point to issues with API queries or changes required in the client application.

Examine API performance metrics

You can filter Platform Insights metrics by using various attributes such as http_status, endpoint, http_method, and project_key. This enables you to evaluate and identify key areas of your APIs that may need to be improved.

For example, if you notice an unexpectedly higher ct_time_sec value for certain endpoints, then you can pinpoint the HTTP methods or status codes associated with those slow requests and take appropriate action to resolve the issue.

Representations

Representations are JSON objects submitted or received as payload to API requests or responses.

Update actions

Get Insights configuration

curl --get https://api.{region}.commercetools.com/{projectKey}/insights-configuration -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

{
  "active": true,
  "projectKey": "my-project-key",
  "lastModifiedAt": "2024-12-12T12:01:03.000Z",
  "providers": [
    {
      "type": "NewRelic",
      "region": "eu",
      "eventTypes": ["Metrics"]
    }
  ]
}

Put Insights configuration

curl -X PUT https://api.{region}.commercetools.com/{projectKey}/insights-configuration -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "providers" : [ {
    "type" : "NewRelic",
    "region" : "eu",
    "apiKey" : "euNR12345",
    "eventTypes" : [ "Metrics" ]
  } ]
}
DATA

{
  "active": true,
  "projectKey": "my-project-key",
  "lastModifiedAt": "2024-12-12T12:01:03.000Z",
  "providers": [
    {
      "type": "NewRelic",
      "region": "eu",
      "eventTypes": ["Metrics"]
    }
  ]
}

Update Insights configuration

curl https://api.{region}.commercetools.com/{projectKey}/insights-configuration -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "actions" : [ {
    "action" : "activate"
  } ]
}
DATA

{
  "active": true,
  "projectKey": "my-project-key",
  "lastModifiedAt": "2024-12-12T12:01:03.000Z",
  "providers": [
    {
      "type": "NewRelic",
      "region": "eu",
      "eventTypes": ["Metrics"]
    }
  ]
}

Delete Insights configuration

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/insights-configuration -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

{
  "active": true,
  "projectKey": "my-project-key",
  "lastModifiedAt": "2024-12-12T12:01:03.000Z",
  "providers": [
    {
      "type": "NewRelic",
      "region": "eu",
      "eventTypes": ["Metrics"]
    }
  ]
}