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.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 |
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. |
{
"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 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. |
{
"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 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. |
{
"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 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. |
{
"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 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. |
{
"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 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​ | The destination for your 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 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​ | The destination for your 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​ | The name of the header |
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. 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​ | NewRelicThe 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. If omitted 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​ | DynatraceSaaSThe 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.
If omitted 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​ | DynatraceActiveGateThe 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
If omitted 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​ | DatadogThe 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. If omitted 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​ | OtlpThe APM provider for your Platform Insights configuration. |
eventTypes​Array of EventType​ | List of event types to be exported to the APM provider. |
endpoint​String​ | The destination for your 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​ | OtlpHttpThe APM provider for your Platform Insights configuration. |
eventTypes​Array of EventType​ | List of event types to be exported to the APM provider. |
endpoint​String​ | The destination for your 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​ | The name of the header Pattern:Â^[a-zA-Z][a-zA-Z0-9-_]*$​ |
value​String​ | The 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 in which 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 configuration for Platform Insights.
action​String​ | "activate" |
{
"action": "activate"
}ConfigurationDeactivateAction
Deactivates a configuration for Platform Insights.
action​String​ | "deactivate" |
{
"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. |
{
"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​ |
{
"action": "setActive",
"provider": "NewRelic",
"active": true
}ConfigurationSetEventTypesAction
action​String​ | "setEventTypes" |
provider​ | Provider to be updated |
eventTypes​Array of EventType​ | EventTypes used for this provider |
{
"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. |
{
"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 |
{
"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 |
{
"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 |
{
"action": "setAttributes",
"attributes": [
{
"type": "String",
"eventType": "Metrics",
"name": "team",
"value": "commercetools"
}
]
}Get Insights configuration
Use this endpoint to get 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"]
}
]
}