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
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.
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
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, 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. |
{
"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. |
{
"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. |
{
"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. |
{
"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. |
{
"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​ |
{
"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​ |
{
"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 ​ |
{
"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. |
{
"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 |
{
"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 |
{
"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. |
{
"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​ |
{
"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​ |
{
"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​ |
{
"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}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
application/json
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",
"active": true,
"region": "eu",
"eventTypes": ["Metrics"]
}
]
}
Put Insights configuration
manage_project:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
application/json
application/json
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",
"active": true,
"region": "eu",
"eventTypes": ["Metrics"]
}
]
}
Update Insights configuration
manage_project:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
application/json
application/json
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",
"active": true,
"region": "eu",
"eventTypes": ["Metrics"]
}
]
}
Delete Insights configuration
manage_project:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
application/json
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",
"active": true,
"region": "eu",
"eventTypes": ["Metrics"]
}
]
}