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
| Metric name | Description | Type |
|---|---|---|
| ct_time_sec | Average time (in seconds) to process a request in Composable Commerce. | Histogram |
| ct_response_count | Number of responses received from Composable Commerce for all API calls. | Counter |
| ct_sent_bytes | Number of bytes that Composable Commerce sends to your end users as part of API responses. | Counter |
| ct_received_bytes | Number of bytes received by Composable Commerce from end user requests. | Counter |
| ct_error_count | Number 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.
ct_response_count to determine peak usage times, identify API consumption trends, and assess if your application scales effectively to manage traffic.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
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.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
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. |
{
"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​ | NewRelicList 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. |
{
"type": "NewRelic",
"active": true,
"region": "eu",
"eventTypes": [
"Metrics"
]
}DynatraceSaaSProvider
type​ | DynatraceSaaSList 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. |
{
"type": "DynatraceSaaS",
"active": true,
"environmentId": "dtMyEnvironment",
"eventTypes": [
"Metrics"
]
}DynatraceActiveGateProvider
type​ | DynatraceActiveGateList 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. |
{
"type": "DynatraceActiveGate",
"active": true,
"activeGateDomain": "my-active-gate.example.com",
"environmentId": "dtMyEnvironment",
"eventTypes": [
"Metrics"
]
}DatadogProvider
type​ | DatadogList 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. |
{
"type": "Datadog",
"active": true,
"site": "US1",
"eventTypes": [
"Metrics"
]
}OtlpProvider
type​ | OtlpList 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. |
{
"type": "Otlp",
"active": true,
"endpoint": "https://myotlpprovider.com:14317",
"headers": [
{
"name": "api-key"
}
],
"eventTypes": [
"Metrics"
]
}OtlpHttpProvider
type​ | OtlpHttpList 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. |
{
"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​ |
{
"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​ | NewRelicAPM 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. |
{
"type": "NewRelic",
"region": "eu",
"apiKey": "euNR12345",
"eventTypes": [
"Metrics"
]
}DynatraceSaaSProviderDraft
active​Boolean​ | If true, this provider configuration is active. |
type​ | DynatraceSaaSAPM 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. |
{
"type": "DynatraceSaaS",
"environmentId": "dtMyEnvironment",
"apiKey": "dtabc1234",
"eventTypes": [
"Metrics"
]
}DynatraceActiveGateProviderDraft
active​Boolean​ | If true, this provider configuration is active. |
type​ | DynatraceActiveGateAPM 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. |
{
"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​ | DatadogAPM 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. |
{
"type": "Datadog",
"site": "US1",
"apiKey": "ddApiKey12345",
"eventTypes": [
"Metrics"
]
}OtlpProviderDraft
active​Boolean​ | If true, this provider configuration is active. |
type​ | OtlpAPM 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. |
{
"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​ | OtlpHttpAPM 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. |
{
"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.
NewRelicDynatraceSaaSDynatraceActiveGateDatadogOtlpOtlpHttp
EventType
List of event types to be exported to a supported APM provider.
LogsMetrics
NewRelicRegion
List of regions where NewRelic is hosted.
euus
DatadogSite
US1US3US5EU1US1-FEDAP1
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​ |
{
"actions": [
{
"action": "activate"
}
]
}ConfigurationActivateAction
Activates a Platform Insights configuration for your Project.
action​String​ | "activate" |
{
"action": "activate"
}ConfigurationDeactivateAction
Deactivates a Platform Insights configuration for your Project.
action​String​ | "deactivate" |
{
"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. |
{
"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​ |
{
"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. |
{
"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. |
{
"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. |
{
"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. |
{
"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. |
{
"action": "setAttributes",
"attributes": [
{
"type": "String",
"eventType": "Metrics",
"name": "team",
"value": "commercetools"
}
]
}Get Insights configuration
Use this endpoint to retrieve the Platform Insights configuration for your Project.
manage_project:{projectKey}regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
application/jsoncurl --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",
"active": true,
"region": "eu",
"eventTypes": ["Metrics"]
}
]
}Put Insights configuration
manage_project:{projectKey}regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
application/jsonapplication/jsoncurl -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",
"active": true,
"region": "eu",
"eventTypes": ["Metrics"]
}
]
}Update Insights configuration
manage_project:{projectKey}regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
application/jsonapplication/jsoncurl 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",
"active": true,
"region": "eu",
"eventTypes": ["Metrics"]
}
]
}Delete Insights configuration
manage_project:{projectKey}regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
application/jsoncurl -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",
"active": true,
"region": "eu",
"eventTypes": ["Metrics"]
}
]
}