# Platform Insights

Detect, monitor, and analyze the performance of commercetools API platform.

With Platform Insights, you can analyze metrics and server-side logs collected from commercetools APIs. This allows you to monitor and manage the health of your commercetools application.
Platform Insights complements your client-side logging and does not replace it.

Platform Insights can be integrated and used with the following popular Application Performance Monitoring (APM) services: [New Relic](https://docs.newrelic.com/), [Datadog](https://docs.datadoghq.com/), [OpenTelemetry](https://opentelemetry.io/docs/), and [Dynatrace](https://docs.dynatrace.com/docs).

Platform Insights is offered as an Add-On product. To get access, see the [offering page](/offering/platform-insights.md#get-access-to-platform-insights).

Find details about the integration with APM providers in the [Integrate APM provider](/tutorials/apm-integration.md) guide.

## Monitor and track API metrics

You can analyze the performance of commercetools APIs by tracking the following Platform Insights metrics in the **Metrics** section of your preferred APM.

| Metric name | Description | Type |
| --- | --- | --- |
| [ct\_time\_sec](/api/platform-insights.md#ct_time_sec-request-processing-time) | Average time (in seconds) to process a request in commercetools API platform. | Histogram |
| [ct\_response\_count](/api/platform-insights.md#ct_response_count-response-count) | Number of responses received from commercetools API platform for all API calls. | Counter |
| [ct\_sent\_bytes](/api/platform-insights.md#ct_sent_bytes-bytes-sent) | Number of bytes that commercetools API platform sends to your end users as part of API responses. | Counter |
| [ct\_received\_bytes](/api/platform-insights.md#ct_received_bytes-bytes-received) | Number of bytes received by commercetools API platform from end user requests. | Counter |
| [ct\_error\_count](/api/platform-insights.md#ct_error_count-error-count) | Number of requests that returned HTTP error status codes - client-side errors (`4xx`) or server-side (`5xx`) errors. | Counter |
| [ct\_extension\_time\_sec](/api/platform-insights.md#ct_extension_time_sec-extension-processing-time) | Average time (in seconds) to process an extension in commercetools API platform. | Histogram |

### ct\_time\_sec (Request Processing Time)

`ct_time_sec` tracks the average time, in seconds, that it takes to process a request in commercetools 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 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 sent 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 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 requests or changes required in the client application.

### ct\_extension\_time\_sec (Extension Processing Time)

`ct_extension_time_sec` tracks the average time, in seconds, that it takes to process an extension call in Composable Commerce over a specific period. This metric measures the elapsed time between making the extension call. It helps you understand the overall performance and efficiency of your extensions being called from commercetools.

This data exports as a histogram, showing the distribution of response times for different extensions.

## Examine API performance metrics

You can filter Platform Insights metrics 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 for improvement.

For example, if you notice a significantly higher [`ct_time_sec`](/api/platform-insights.md#ct_time_sec-request-processing-time) value for certain endpoints, investigate related HTTP methods and status codes. Then you can take action to improve those slow requests.

## Receive logs from commercetools

When using the Platform Insights logs forwarding feature in the **Logs** section of your APM tool, you can view the commercetools API logs.

### API access logs

The API access logs provide detailed information about each request made to Composable Commerce APIs.

```json title="Example access log entry for a Create Product Type API call"
{
  "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
}
```

### Extension logs

When using [API Extensions](/api/projects/api-extensions.md), Platform Insights also forwards the logs for triggering them. Extension logs are identified by the resource attributes `source_type: "extension"` and `service.component: "extensions"`, and by `http_x_service_name: "extensions"` in the log body. In addition to the common fields ([`correlation_id`](/api/general-concepts.md#correlation-id), [`ctp_project_key`](/search.md?urn=ctp:api:type:Project), `duration`, `environment`, `level`, `severity`, and `timestamp`), each log entry contains the following fields:

| Field | Description |
| --- | --- |
| `extension_action` | The type of action that triggered the Extension call, for example, `Create`, `Update`. |
| `extension_actions` | The number of returned update actions. |
| `extension_id` | The `id` of the triggered [Extension](/search.md?urn=ctp:api:type:Extension). |
| `extension_key` | The `key` of the triggered [Extension](/search.md?urn=ctp:api:type:Extension). |
| `extension_outcome` | Indicates whether the validation performed by the Extension succeeded or failed. |
| `extension_type_id` | The [ExtensionResourceTypeId](/search.md?urn=ctp:api:type:ExtensionResourceTypeId) for which the Extension triggered an operation. |
| `extension_duration` | The time it takes to receive a response from the Extension, in milliseconds. |
| `extensions_chain_duration` | The time it takes to process the responses from all the Extensions in an [Extension Chain](/api/api-extensibility-overview.md#extension-chaining), in milliseconds. |

```json title="Example of an Extension log entry"
{
	"correlation_id": "9e4dda60b9b1c58f5fff72f0ab38809a",
	"ctp_project_key": "test-project",
	"duration": 0.014,
	"environment": "prod",
	"extension_action": "Update",
	"extension_actions": 0,
	"extension_id": "812d58b5-ff37",
	"extension_key": "promotions",
	"extension_outcome": "success",
	"extension_type_id": "cart",
	"extension_url": "https://promotions.example.com/event/",
	"http_x_service_name": "extensions",
	"level": "info",
	"severity": "info",
	"timestamp": "2026-02-26T09:44:09.593449551Z",
	"source_type": "extension",
	"service.name": "commercetools",
	"service.component": "extensions"
}
```

### Managed MCP Servers tool execution logs

Platform Insights only forwards logs for tool executions on Managed MCP Servers. The [Commerce MCP](/api/dev-tooling/mcp/commerce-mcp.md) server is a Managed MCP Server that produces these logs. Use these logs to monitor the status of MCP tool executions and to capture error information in your APM tool.

MCP tool execution logs are identified by the resource attributes `source_type: "mcp-service"` and `service.component: "mcp-service"`, and by `ct_service_name: "mcp-service"` in the log body. In addition to the common fields ([`correlation_id`](/api/general-concepts.md#correlation-id), [`ctp_project_key`](/search.md?urn=ctp:api:type:Project), `environment`, `message`, `severity`, `level`, and `timestamp`), each log entry contains the following fields:

| Field | Description |
| --- | --- |
| `mcp_event` | The type of the MCP tool execution event. Possible values are `tool.execution.start`, `tool.execution.success`, `tool.execution.error`, `session.created`, `session.closed`, and `session.deleted`. This provides a more detailed classification than `mcp_outcome`. |
| `mcp_outcome` | The result of the MCP tool execution, either `success` or `error`. This lets you quickly filter for successful or failed executions. An `error` outcome sets the log `severity` to `warn`. |
| `mcp_session_id` | The unique identifier of the MCP session. |
| `mcp_tool_name` | The name of the invoked MCP tool, for example, `read_products`. |
| `duration` | The time it takes to execute the MCP tool, in seconds. |

The `message` field is always `MCP server call`.

```json title="Example of a successful MCP tool execution log entry"
{
	"correlation_id": "ct-managed-mcp-servers-3w7S42x2RqqZC6-Wh3B1dA-JVjHScgRSWWIfIXeqHzZBg",
	"ct_service_name": "mcp-service",
	"ctp_project_key": "managed-mcp-servers",
	"duration": 0.073,
	"environment": "prod",
	"level": "info",
	"mcp_event": "tool.execution.success",
	"mcp_outcome": "success",
	"mcp_session_id": "b04bcfa5-2f5f-4aa4-9c6e-579ac0f6ab36",
	"mcp_tool_name": "read_products",
	"message": "MCP server call",
	"severity": "info",
	"timestamp": "2026-06-11T08:46:01.206Z",
	"source_type": "mcp-service",
	"service.name": "commercetools",
	"service.component": "mcp-service"
}
```

When an MCP tool execution fails, `mcp_outcome` is set to `error` and the log `severity` is set to `warn`.

```json title="Example of a failed MCP tool execution log entry"
{
	"correlation_id": "ct-managed-mcp-servers-sPxzbI2YSdmTgmzx5MZiNw-T9lXpFYOQ0m30wYzdtcWSQ",
	"ct_service_name": "mcp-service",
	"ctp_project_key": "managed-mcp-servers",
	"duration": 0.021,
	"environment": "prod",
	"level": "warn",
	"mcp_event": "tool.execution.error",
	"mcp_outcome": "error",
	"mcp_session_id": "bec4f5c7-679d-464b-ae7b-28e06809df72",
	"mcp_tool_name": "update_stores",
	"message": "MCP server call",
	"severity": "warn",
	"timestamp": "2026-06-11T08:46:01.523Z",
	"source_type": "mcp-service",
	"service.name": "commercetools",
	"service.component": "mcp-service"
}
```

## Representations

Representations are JSON objects submitted or received as payloads in API requests and responses.

#### ProjectConfiguration

[type definition](/search.md?urn=ctp:insights:type:ProjectConfiguration).

#### Provider

The options for exporting data to an APM provider.

##### NewRelicProvider

[type definition](/search.md?urn=ctp:insights:type:NewRelicProvider).

##### DynatraceSaaSProvider

[type definition](/search.md?urn=ctp:insights:type:DynatraceSaaSProvider).

##### DynatraceActiveGateProvider

[type definition](/search.md?urn=ctp:insights:type:DynatraceActiveGateProvider).

##### DatadogProvider

[type definition](/search.md?urn=ctp:insights:type:DatadogProvider).

##### OtlpProvider

[type definition](/search.md?urn=ctp:insights:type:OtlpProvider).

##### OtlpHttpProvider

[type definition](/search.md?urn=ctp:insights:type:OtlpHttpProvider).

#### OtlpProviderHeader

[type definition](/search.md?urn=ctp:insights:type:OtlpProviderHeader).

#### ProjectConfigurationDraft

[type definition](/search.md?urn=ctp:insights:type:ProjectConfigurationDraft).

#### ProviderDraft

Defines the options for exporting data to an APM provider.

##### NewRelicProviderDraft

[type definition](/search.md?urn=ctp:insights:type:NewRelicProviderDraft).

##### DynatraceSaaSProviderDraft

[type definition](/search.md?urn=ctp:insights:type:DynatraceSaaSProviderDraft).

##### DynatraceActiveGateProviderDraft

[type definition](/search.md?urn=ctp:insights:type:DynatraceActiveGateProviderDraft).

##### DatadogProviderDraft

[type definition](/search.md?urn=ctp:insights:type:DatadogProviderDraft).

##### OtlpProviderDraft

[type definition](/search.md?urn=ctp:insights:type:OtlpProviderDraft).

##### OtlpHttpProviderDraft

[type definition](/search.md?urn=ctp:insights:type:OtlpHttpProviderDraft).

#### OtlpProviderHeaderDraft

[type definition](/search.md?urn=ctp:insights:type:OtlpProviderHeaderDraft).

#### ProviderTypeId

[type definition](/search.md?urn=ctp:insights:type:ProviderTypeId).

#### EventType

[type definition](/search.md?urn=ctp:insights:type:EventType).

#### NewRelicRegion

[type definition](/search.md?urn=ctp:insights:type:NewRelicRegion).

#### DatadogSite

[type definition](/search.md?urn=ctp:insights:type:DatadogSite).

#### Attribute

##### StringAttribute

[type definition](/search.md?urn=ctp:insights:type:StringAttribute).

#### AttributeDraft

##### StringAttributeDraft

[type definition](/search.md?urn=ctp:insights:type:StringAttributeDraft).

#### AttributeTypeId

[type definition](/search.md?urn=ctp:insights:type:AttributeTypeId).

## Get Insights configuration

[endpoint definition](/search.md?urn=ctp:insights:endpoint:/{projectKey}/insights-configuration:GET).

## Create or Replace Insights configuration

[endpoint definition](/search.md?urn=ctp:insights:endpoint:/{projectKey}/insights-configuration:PUT).

## Update Insights configuration

[endpoint definition](/search.md?urn=ctp:insights:endpoint:/{projectKey}/insights-configuration:POST).

## Update actions

#### ConfigurationActivateAction

[type definition](/search.md?urn=ctp:insights:type:ConfigurationActivateAction).

#### ConfigurationDeactivateAction

[type definition](/search.md?urn=ctp:insights:type:ConfigurationDeactivateAction).

#### ConfigurationRemoveProviderAction

[type definition](/search.md?urn=ctp:insights:type:ConfigurationRemoveProviderAction).

#### ConfigurationSetActiveAction

[type definition](/search.md?urn=ctp:insights:type:ConfigurationSetActiveAction).

#### ConfigurationSetEventTypesAction

[type definition](/search.md?urn=ctp:insights:type:ConfigurationSetEventTypesAction).

#### ConfigurationSetProviderAction

[type definition](/search.md?urn=ctp:insights:type:ConfigurationSetProviderAction).

#### ConfigurationAddAttributeAction

[type definition](/search.md?urn=ctp:insights:type:ConfigurationAddAttributeAction).

#### ConfigurationRemoveAttributeAction

[type definition](/search.md?urn=ctp:insights:type:ConfigurationRemoveAttributeAction).

#### ConfigurationSetAttributesAction

[type definition](/search.md?urn=ctp:insights:type:ConfigurationSetAttributesAction).

## Delete Insights configuration

[endpoint definition](/search.md?urn=ctp:insights:endpoint:/{projectKey}/insights-configuration:DELETE).

## Related pages

- [Area overview page with navigation](/api.md)
- [Previous page: Load testing](/api/load-testing.md)
- [Search documentation and API specs](/search.md)