Platform Insights

Elevate, May 20-22-2025, Miami Beach, Florida

Use Platform Insights metrics to detect, monitor, and analyze the performance of commercetools Composable Commerce APIs.

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:

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.
Metric nameDescriptionType
ct_time_secAverage time (in seconds) to process a request in Composable Commerce.Histogram
ct_response_countNumber of responses received from Composable Commerce for all API calls.Counter
ct_sent_bytesNumber of bytes that Composable Commerce sends to your end users as part of API responses.Counter
ct_received_bytesNumber of bytes received by Composable Commerce from end user requests.Counter
ct_error_countNumber of requests that returned HTTP error status codes - client-side errors (4xx) or server-side (5xx) errors.Counter

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.

ProjectConfiguration

The Platform Insights configuration of your Project.

active​
Boolean​
If true, the Platform Insights configuration is active.
projectKey​
String​

User-defined unique identifier of the Project

providers​
Array of Provider​

List of supported APM providers.

additionalAttributes​
Array of Attribute​

List of attributes to add to a metric

(uniqueProperty): name​
lastModifiedAt​
DateTime​

Date and time (UTC) the Platform Insights configuration was last updated.

lastModifiedBy​
ClientLogging​

IDs and references that last modified the Platform Insights configuration.

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

Provider

The options for exporting data to an APM provider

NewRelicProvider

type​
NewRelic

List of supported APM providers for your Platform Insights configuration.

active​
Boolean​
If true, this provider configuration is active.
valid​
Boolean​
If true, it is possible to send metrics to the APM provider.
eventTypes​
Array of EventType​

List of event types to be exported to a supported APM provider.

region​

Region in which your NewRelic account is hosted. For example, EU.

Example: json
{
  "type": "NewRelic",
  "active": true,
  "region": "eu",
  "eventTypes": [
    "Metrics"
  ]
}

DynatraceSaaSProvider

type​
DynatraceSaaS

List of supported APM providers for your Platform Insights configuration.

active​
Boolean​
If true, this provider configuration is active.
valid​
Boolean​
If true, it is possible to send metrics to the APM provider.
eventTypes​
Array of EventType​

List of event types to be exported to a supported APM provider.

environmentId​
String​

Unique user-defined environment identifier of your DynatraceSaaS account.

Example: json
{
  "type": "DynatraceSaaS",
  "active": true,
  "environmentId": "dtMyEnvironment",
  "eventTypes": [
    "Metrics"
  ]
}

DynatraceActiveGateProvider

type​
DynatraceActiveGate

List of supported APM providers for your Platform Insights configuration.

active​
Boolean​
If true, this provider configuration is active.
valid​
Boolean​
If true, it is possible to send metrics to the APM provider.
eventTypes​
Array of EventType​

List of event types to be exported to a supported APM provider.

activeGateDomain​
String​

Your ActiveGate domain.

activeGatePort​
Float​

Your ActiveGate domain port.

environmentId​
String​

Unique user-defined environment identifier of your DynatraceSaaS account.

Example: json
{
  "type": "DynatraceActiveGate",
  "active": true,
  "activeGateDomain": "my-active-gate.example.com",
  "environmentId": "dtMyEnvironment",
  "eventTypes": [
    "Metrics"
  ]
}

DatadogProvider

type​
Datadog

List of supported APM providers for your Platform Insights configuration.

active​
Boolean​
If true, this provider configuration is active.
valid​
Boolean​
If true, it is possible to send metrics to the APM provider.
eventTypes​
Array of EventType​

List of event types to be exported to a supported APM provider.

site​
DatadogSite​

Website where your Datadog account is hosted.

Example: json
{
  "type": "Datadog",
  "active": true,
  "site": "US1",
  "eventTypes": [
    "Metrics"
  ]
}

OtlpProvider

type​
Otlp

List of supported APM providers for your Platform Insights configuration.

active​
Boolean​
If true, this provider configuration is active.
valid​
Boolean​
If true, it is possible to send metrics to the APM provider.
eventTypes​
Array of EventType​

List of event types to be exported to a supported APM provider.

endpoint​
String​
headers​
Array of OtlpProviderHeader​
Example: json
{
  "type": "Otlp",
  "active": true,
  "endpoint": "https://myotlpprovider.com:14317",
  "headers": [
    {
      "name": "api-key"
    }
  ],
  "eventTypes": [
    "Metrics"
  ]
}

OtlpHttpProvider

type​
OtlpHttp

List of supported APM providers for your Platform Insights configuration.

active​
Boolean​
If true, this provider configuration is active.
valid​
Boolean​
If true, it is possible to send metrics to the APM provider.
eventTypes​
Array of EventType​

List of event types to be exported to a supported APM provider.

endpoint​
String​
headers​
Array of OtlpProviderHeader​
Example: json
{
  "type": "OtlpHttp",
  "active": true,
  "endpoint": "https://myotlpprovider.com:14318",
  "headers": [
    {
      "name": "api-key"
    }
  ],
  "eventTypes": [
    "Metrics"
  ]
}

OtlpProviderHeader

name​
String​

ProjectConfigurationDraft

Draft to create a Platform Insights configuration for your Project.

active​
Boolean​
If true, the Platform Insights configuration is active.
providers​
Array of ProviderDraft​

List of supported APM providers.

(uniqueProperty): type​
additionalAttributes​
Array of AttributeDraft​

List of attributes to add to a metric

(uniqueProperty): name​
Example: json
{
  "providers": [
    {
      "type": "NewRelic",
      "eventTypes": [
        "Metrics"
      ],
      "region": "eu",
      "apiKey": "euNR12345"
    }
  ]
}

ProviderDraft

Defines the options for exporting data to an APM provider

NewRelicProviderDraft

active​
Boolean​
If true, this provider configuration is active.
type​
NewRelic

The APM provider for your Platform Insights configuration.

eventTypes​
Array of EventType​

List of event types to be exported to the APM provider.

region​

Region in which your NewRelic account is based. For example, EU.

apiKey​
String​
API key (type Ingest - License) used to authenticate your NewRelic account.
Example: json
{
  "type": "NewRelic",
  "region": "eu",
  "apiKey": "euNR12345",
  "eventTypes": [
    "Metrics"
  ]
}

DynatraceSaaSProviderDraft

active​
Boolean​
If true, this provider configuration is active.
type​
DynatraceSaaS

The APM provider for your Platform Insights configuration.

eventTypes​
Array of EventType​

List of event types to be exported to the APM provider.

environmentId​
String​

Unique user-defined environment identifier of your DynatraceSaaS account.

Pattern: ^[^.|/:'"`#?]+$​
apiKey​
String​
API key used to authenticate your DynatraceSaaS account. Scopes needed Ingest-Logs and Ingest-Metrics
Example: json
{
  "type": "DynatraceSaaS",
  "environmentId": "dtMyEnvironment",
  "apiKey": "dtabc1234",
  "eventTypes": [
    "Metrics"
  ]
}

DynatraceActiveGateProviderDraft

active​
Boolean​
If true, this provider configuration is active.
type​
DynatraceActiveGate

The APM provider for your Platform Insights configuration.

eventTypes​
Array of EventType​

List of event types to be exported to the APM provider.

activeGateDomain​
String​

Your ActiveGate domain.

Pattern: ^[^|/:#?'"`]+$​
activeGatePort​
Float​

Your ActiveGate domain port.

environmentId​
String​

Unique user-defined environment identifier of your DynatraceActiveGate account.

Pattern: ^[^.|/:'"`#?]+$​
apiKey​
String​
API key used to authenticate your DynatraceActiveGate account. Scopes needed Ingest-Logs and Ingest-Metrics
Example: json
{
  "type": "DynatraceActiveGate",
  "activeGateDomain": "my-active-gate.example.com",
  "environmentId": "dtMyEnvironment",
  "apiKey": "dtabc1234",
  "eventTypes": [
    "Metrics"
  ]
}

DatadogProviderDraft

active​
Boolean​
If true, this provider configuration is active.
type​
Datadog

The APM provider for your Platform Insights configuration.

eventTypes​
Array of EventType​

List of event types to be exported to the APM provider.

site​
DatadogSite​

Website where your Datadog account is hosted.

apiKey​
String​

API key used to authenticate your Datadog account.

Example: json
{
  "type": "Datadog",
  "site": "US1",
  "apiKey": "ddApiKey12345",
  "eventTypes": [
    "Metrics"
  ]
}

OtlpProviderDraft

active​
Boolean​
If true, this provider configuration is active.
type​
Otlp

The APM provider for your Platform Insights configuration.

eventTypes​
Array of EventType​

List of event types to be exported to the APM provider.

endpoint​
String​
headers​
Array of OtlpProviderHeaderDraft​
Example: json
{
  "type": "Otlp",
  "endpoint": "https://myotlpprovider.com:14317",
  "headers": [
    {
      "name": "api-key",
      "value": "apiKey1234"
    }
  ],
  "eventTypes": [
    "Metrics"
  ]
}

OtlpHttpProviderDraft

active​
Boolean​
If true, this provider configuration is active.
type​
OtlpHttp

The APM provider for your Platform Insights configuration.

eventTypes​
Array of EventType​

List of event types to be exported to the APM provider.

endpoint​
String​
headers​
Array of OtlpProviderHeaderDraft​
Example: json
{
  "type": "OtlpHttp",
  "endpoint": "https://myotlpprovider.com:14318",
  "headers": [
    {
      "name": "api-key",
      "value": "apiKey1234"
    }
  ],
  "eventTypes": [
    "Metrics"
  ]
}

OtlpProviderHeaderDraft

name​
String​
Pattern: ^[a-zA-Z][a-zA-Z0-9-_]*$​
value​
String​
Pattern: ^[^']+$​

ProviderTypeId

List of supported APM providers for your Platform Insights configuration.

NewRelic
DynatraceSaaS
DynatraceActiveGate
Datadog
Otlp
OtlpHttp

EventType

List of event types to be exported to a supported APM provider.

Logs
Metrics

NewRelicRegion

List of regions in which NewRelic is hosted.

eu
us

DatadogSite

US1
US3
US5
EU1
US1-FED
AP1

Attribute

StringAttribute

eventType​
EventType​

List of event types to be exported to a supported APM provider.

type​
String
name​
String​
value​
String​

AttributeDraft

StringAttributeDraft

eventType​
EventType​

List of event types to be exported to a supported APM provider.

type​
String
name​
String​
value​
String​

AttributeTypeId

String

Update actions

ConfigurationUpdate

Update actions to be performed on the Platform Insights configuration for your Project.

actions​
Array of ConfigurationUpdateAction​
Example: json
{
  "actions": [
    {
      "action": "activate"
    }
  ]
}

ConfigurationActivateAction

Activates a configuration for Platform Insights.

action​
String​
"activate"
Example: json
{
  "action": "activate"
}

ConfigurationDeactivateAction

Deactivates a configuration for Platform Insights.

action​
String​
"deactivate"
Example: json
{
  "action": "deactivate"
}

ConfigurationRemoveProviderAction

Removes an APM provider from a Platform Insights configuration.

action​
String​
"removeProvider"
provider​

List of supported APM providers for your Platform Insights configuration.

Example: json
{
  "action": "removeProvider",
  "provider": "NewRelic"
}

ConfigurationSetActiveAction

Activates a provider configuration for Platform Insights.

action​
String​
"setActive"
provider​

List of supported APM providers for your Platform Insights configuration.

active​
Boolean​
Example: json
{
  "action": "setActive",
  "provider": "NewRelic",
  "active": true
}

ConfigurationSetEventTypesAction

action​
String​
"setEventTypes"
provider​

Provider to be updated

eventTypes​
Array of EventType​

EventTypes used for this provider

Example: json
{
  "action": "setEventTypes",
  "provider": "NewRelic",
  "eventTypes": [
    "Logs",
    "Metrics"
  ]
}

ConfigurationSetProviderAction

Sets an APM provider to a Platform Insights configuration.

action​
String​
"setProvider"
provider​

New APM provider to be set for your Platform Insights configuration.

Example: json
{
  "action": "setProvider",
  "provider": {
    "type": "NewRelic",
    "eventTypes": [
      "Metrics"
    ],
    "region": "eu",
    "apiKey": "euNR12345"
  }
}

ConfigurationAddAttributeAction

Add attribute to be added to insights events.

action​
String​
"addAttribute"
attribute​

Attribute to be set

Example: json
{
  "action": "addAttribute",
  "attribute": {
    "type": "String",
    "eventType": "Metrics",
    "name": "team",
    "value": "commercetools"
  }
}

ConfigurationRemoveAttributeAction

Remove attribute from insights configuration.

action​
String​
"removeAttribute"
attribute​
String​

Attribute to be removed

Example: json
{
  "action": "removeAttribute",
  "attribute": "name"
}

ConfigurationSetAttributesAction

Sets attributes to be added to insights events.

action​
String​
"setAttributes"
attributes​
Array of AttributeDraft​

The list of attributes to be set

Example: json
{
  "action": "setAttributes",
  "attributes": [
    {
      "type": "String",
      "eventType": "Metrics",
      "name": "team",
      "value": "commercetools"
    }
  ]
}

Get Insights configuration

GET
https://api.{region}.commercetools.com/{projectKey}/insights-configuration

Use this endpoint to get the Platform Insights configuration for your project.

OAuth 2.0 Scopes:
manage_project:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Response:
200

ProjectConfiguration

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/insights-configuration -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: ProjectConfigurationjson
{
  "active": true,
  "projectKey": "my-project-key",
  "lastModifiedAt": "2024-12-12T12:01:03.000Z",
  "providers": [
    {
      "type": "NewRelic",
      "active": true,
      "region": "eu",
      "eventTypes": ["Metrics"]
    }
  ]
}

Put Insights configuration

PUT
https://api.{region}.commercetools.com/{projectKey}/insights-configuration
Use this endpoint to either create a Platform Insights configuration or update an existing Platform Insights configuration. After you create a Platform Insights configuration, it becomes active in an eventually consistent way.
OAuth 2.0 Scopes:
manage_project:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Request Body:ProjectConfigurationDraftasapplication/json
Response:
200

ProjectConfiguration

asapplication/json
Request Example:cURL
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
200 Response Example: ProjectConfigurationjson
{
  "active": true,
  "projectKey": "my-project-key",
  "lastModifiedAt": "2024-12-12T12:01:03.000Z",
  "providers": [
    {
      "type": "NewRelic",
      "active": true,
      "region": "eu",
      "eventTypes": ["Metrics"]
    }
  ]
}

Update Insights configuration

POST
https://api.{region}.commercetools.com/{projectKey}/insights-configuration
Use this endpoint to perform specific update actions such as enabling or disabling an existing Platform Insights configuration. After you enable or disable a Platform Insights configuration, the action is performed in an eventually consistent way.
OAuth 2.0 Scopes:
manage_project:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Request Body:ConfigurationUpdateasapplication/json
Response:
200

ProjectConfiguration

asapplication/json
Request Example:cURL
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
200 Response Example: ProjectConfigurationjson
{
  "active": true,
  "projectKey": "my-project-key",
  "lastModifiedAt": "2024-12-12T12:01:03.000Z",
  "providers": [
    {
      "type": "NewRelic",
      "active": true,
      "region": "eu",
      "eventTypes": ["Metrics"]
    }
  ]
}

Delete Insights configuration

DELETE
https://api.{region}.commercetools.com/{projectKey}/insights-configuration
Use this endpoint to delete the Platform Insights configuration details of your project. After you delete a Platform Insights configuration, it is deleted in an eventually consistent way.
OAuth 2.0 Scopes:
manage_project:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Response:
200

ProjectConfiguration

asapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/insights-configuration -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: ProjectConfigurationjson
{
  "active": true,
  "projectKey": "my-project-key",
  "lastModifiedAt": "2024-12-12T12:01:03.000Z",
  "providers": [
    {
      "type": "NewRelic",
      "active": true,
      "region": "eu",
      "eventTypes": ["Metrics"]
    }
  ]
}