Platform Insights

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 with your own application data, you can analyze your entire system in 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.

Monitor ct_response_count to determine peak usage times, identify API consumption trends, and assess if your application scales effectively to manage traffic.
For example, if ct_response_count spikes significantly during marketing campaigns or holiday seasons, you can scale your system to 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 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, including invalid requests and server problems.

For example, 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 a significantly higher ct_time_sec value for certain endpoints, investigate related HTTP methods and status codes. Then you can take action to improve those slow requests.

Receive access logs from commercetools

When using the Platform Insights logs forwarding feature in the Logs section of your preferred APM tool, you can view the logs from Composable Commerce APIs.

Here's an example of a sample Composable Commerce API log entry:

{
  "correlation_id": "my-project-key-a50e5bec-9ac4-4967-be91-dee8ed9e087a",
  "ctp_api_endpoint": "POST /<project-key>/product-types",
  "ctp_client_id": "myclientid",
  "ctp_http_endpoint": "/<project-key>/product-types",
  "ctp_project_key": "my-project-key",
  "datadog.host.name": "europe-west1.gcp.commercetools.com",
  "duration": 0.111,
  "environment": "prod",
  "http_method": "POST",
  "http_msec": 1764321656.452,
  "http_received_bytes": 516,
  "http_remote": "10.10.10.10",
  "http_sent_bytes": 920,
  "http_status": 201,
  "http_uri": "/my-project-key/product-types",
  "http_useragent": "some-user-agent/3.23.0",
  "http_x_service_name": "api",
  "instrumentation.provider": "opentelemetry",
  "level": "info",
  "message": "POST /my-project-key/product-types 201",
  "project_key_group_by_attr": "my-project-key",
  "service.component": "api",
  "service.name": "commercetools",
  "service.region": "europe-west1.gcp.commercetools.com",
  "severity": "info",
  "severity.text": "info",
  "source_type": "nginx-access",
  "timestamp": 1764321656452
}

Representations

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

ProjectConfiguration

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.

lastModifiedAt​
DateTime​

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

lastModifiedBy​
ClientLogging​

User IDs and references who 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's 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 where 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's 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's 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's 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's 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​

Destination for your OpenTelemetry Protocol (OTLP) provider.

headers​
Array of OtlpProviderHeader​

Headers configured for connecting to your OTLP provider.

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's 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​

Destination for your OpenTelemetry Protocol (OTLP) provider.

headers​
Array of OtlpProviderHeader​

Headers configured for connecting to your OTLP provider.

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

OtlpProviderHeader

name​
String​

Name of the header.

ProjectConfigurationDraft

Draft to create a Platform Insights configuration for your Project.

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

List of supported APM providers.

MaxItems: 5​
additionalAttributes​
Array of AttributeDraft​

List of Attributes to add to a metric.

MaxItems: 10​
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

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) that's used to authenticate your NewRelic account. If you don't specify the API key, an existing key will be kept.
Example: json
{
  "type": "NewRelic",
  "region": "eu",
  "apiKey": "euNR12345",
  "eventTypes": [
    "Metrics"
  ]
}

DynatraceSaaSProviderDraft

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

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. The required scopes are Ingest-Logs and Ingest-Metrics. If you don't specify the API key, an existing key will be kept.
Example: json
{
  "type": "DynatraceSaaS",
  "environmentId": "dtMyEnvironment",
  "apiKey": "dtabc1234",
  "eventTypes": [
    "Metrics"
  ]
}

DynatraceActiveGateProviderDraft

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

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. The required scopes are Ingest-Logs and Ingest-Metrics If you don't specify the API key, an existing key will be kept.
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

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 in which your Datadog account is hosted.

apiKey​
String​

API key used to authenticate your Datadog account. If you don't specify the API key, an existing key will be kept.

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

OtlpProviderDraft

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

APM provider for your Platform Insights configuration.

eventTypes​
Array of EventType​

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

endpoint​
String​

Destination for your OpenTelemetry Protocol (OTLP) provider.

headers​
Array of OtlpProviderHeaderDraft​

Headers configured for connecting to your OTLP provider.

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

APM provider for your Platform Insights configuration.

eventTypes​
Array of EventType​

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

endpoint​
String​

Destination for your OpenTelemetry Protocol (OTLP) provider.

headers​
Array of OtlpProviderHeaderDraft​

Headers configured for connecting to your OTLP provider.

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

OtlpProviderHeaderDraft

name​
String​

Name of the header.

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

Value of the header.

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 where 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​
MaxLength: 30​
value​
String​
MaxLength: 100​

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 Platform Insights configuration for your Project.

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

ConfigurationDeactivateAction

Deactivates a Platform Insights configuration for your Project.

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

ConfigurationRemoveProviderAction

Removes an APM provider from a Platform Insights configuration for your Project.

action​
String​
"removeProvider"
provider​

List of supported APM providers for your Platform Insights configuration.

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

ConfigurationSetActiveAction

Activates a provider Platform Insights configuration for your Project.

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 in the Platform Insights configuration for your Project.

eventTypes​
Array of EventType​

List of eventTypes to be used for this provider.

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

ConfigurationSetProviderAction

Sets an APM provider to a Platform Insights configuration for your Project.

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

Adds Attributes that are to be included in the events of your Platform Insights configuration.

action​
String​
"addAttribute"
attribute​

Attribute to be set for your Platform Insights configuration.

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

ConfigurationRemoveAttributeAction

Removes Attributes from your Platform Insights configuration.

action​
String​
"removeAttribute"
attribute​
String​

Attribute to be removed from your Platform Insights configuration.

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

ConfigurationSetAttributesAction

Sets the Attributes that are to be added to the events of your Platform Insights configuration.

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

List of Attributes to be set for the events of your Platform Insights configuration.

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

as
application/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

as
application/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

as
application/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's deleted in an eventually consistent manner.
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

as
application/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"]
    }
  ]
}