How to set up Platform Insights for your APM service provider.
Platform Insights lets you forward commercetools API telemetry to your Application Performance Monitoring (APM) provider. You can send two types of data by setting the
eventTypes field in your configuration:- Metrics: aggregated request data, including attributes such as
endpoint,http_method, andhttp_status. Use this to monitor API performance and usage patterns. - Logs: individual request log entries. Use this for detailed tracing and debugging.
You can enable one or both event types per provider, and configure up to five providers simultaneously. For example, you can send metrics to New Relic and Datadog at the same time by including both in the
providers array of a single request.Prerequisites
Before you begin, make sure you have the following:
- A commercetools Project with an API Client that has the
manage_project_settings:{projectKey}scope. Replace the{region}placeholder in the request URLs with the value for your Project's Region. For the available values, see Hosts. - A Bearer Token for your API Client. For guidance on obtaining one, see Client credentials flow.
- The Platform Insights add-on activated for your commercetools Project.
- An active account with your chosen APM provider.
New Relic
Log in to your New Relic account. Navigate to the Account Settings page and select API Keys.
Create a new API key of type Ingest - License.
With this API key, you can configure Platform Insights to send data to New Relic.
Send a PUT request to the following endpoint with the API key and region in the body. The supported values for
region are eu and us: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" : "eu12345NRAL",
"eventTypes" : [ "Metrics", "Logs" ]
} ]
}
DATA
After a successful response, it may take up to five minutes for the data to start flowing to New Relic.
View the commercetools service
After Platform Insights sends data, a new service called commercetools appears under APM & Services.
All data from commercetools through Platform Insights appears under the commercetools service.
Metrics
To analyze the data further, use the Query Console. All metrics from commercetools are prefixed with
ct_, and you can filter them in the data explorer.
All metrics provide attributes like
endpoint, http_method, and http_status to help you understand the performance of your API usage.
Logs
Besides the aggregated metrics, you can also see the logs from commercetools. To receive them in addition to metrics, include
Logs in the eventTypes array of your configuration request.They appear in the Logs section of the commercetools service.
For more information, see the New Relic documentation.
Datadog
Log in to your Datadog account. Navigate to Organization Settings and select API Keys.
Create a new API key and copy its value.
With this API key, you can configure Platform Insights to send data to Datadog.
Send a PUT request to the following endpoint with the API key and site in the body:
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" : "Datadog",
"site" : "EU1",
"apiKey" : "ddApiKey12345",
"eventTypes" : [ "Metrics", "Logs" ]
} ]
}
DATA
Set
site to the value that matches your Datadog organization. The following values are supported: US1, US3, US5, EU1, US1-FED, and AP1.After a successful response, it may take up to five minutes for the data to start flowing to Datadog.
Metrics
All metrics sent from commercetools are prefixed with
ct_ and include attributes such as endpoint, http_method, and http_status. You can explore them using the Metrics Explorer in your Datadog account.
Logs
To receive logs in addition to metrics, include
Logs in the eventTypes array of your configuration request.You can view the incoming logs in the Log Explorer section of your Datadog account. Use the search and filtering tools to explore your commercetools API activity.
For more information, see the Datadog documentation.
Dynatrace
Log in to your Dynatrace account. Navigate to Access Tokens and create a new token with the
Ingest-Logs and Ingest-Metrics scopes.
You also need your environment ID, which is the subdomain of your Dynatrace URL. For example, if your Dynatrace URL is
https://dtMyEnvironment.live.dynatrace.com, your environment ID is dtMyEnvironment.With the token and environment ID, send a PUT request to configure Platform Insights:
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" : "DynatraceSaaS",
"environmentId" : "dtMyEnvironment",
"apiKey" : "dtabc1234",
"eventTypes" : [ "Metrics", "Logs" ]
} ]
}
DATA
After a successful response, it may take up to five minutes for the data to start flowing to Dynatrace.
Metrics
All metrics sent from commercetools are prefixed with
ct_ and include attributes such as endpoint, http_method, and http_status. You can create a new dashboard to visualize them in a panel.
Logs
To receive logs in addition to metrics, include
Logs in the eventTypes array of your configuration request. After configuration, Platform Insights sends request logs from commercetools directly to Dynatrace.You can view the incoming logs in the Logs section of your Dynatrace account.
For more information, see the Dynatrace documentation.
Verify your configuration
To confirm that your configuration was saved correctly, send a GET request to the same endpoint:
curl -X GET https://api.{region}.commercetools.com/{projectKey}/insights-configuration \
--header "Authorization: Bearer ${BEARER_TOKEN}"
The response contains a
ProjectConfiguration object with your active providers, their event types, and the time the configuration was last modified.