# ampersand/magento2-log-correlation-id

> Magento 2 correlation id for requests and logs

`composer require ampersand/magento2-log-correlation-id`

Canonical URL: https://packagento.com/ampersand/magento2-log-correlation-id

## At a glance

- **Vendor**: ampersand (https://packagento.com/ampersand.md)
- **Latest version**: 2.0.1 — released 2025-10-06
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/ampersand/magento2-log-correlation-id and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require ampersand/magento2-log-correlation-id:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## What it does

Magento 2 correlation id for requests and logs

## README

[![Build Status](https://app.travis-ci.com/AmpersandHQ/magento2-log-correlation-id.svg?token=4DzjEueYNQwZuk3ywXjG&branch=main)](https://app.travis-ci.com/AmpersandHQ/magento2-log-correlation-id)

Magento 2 log correlation id for PHP requests/processes and magento logs.

This is useful when debugging issues on a production site as high amounts of traffic can cause many logs to be written and identifying which logs belong to a specific failing request can sometimes be difficult.

With this you should easily be able to find all associated logs for a given web request or CLI process.
- From a web request you can look at the `X-Log-Correlation-Id` header then search all your magento log files for the logs corresponding to only that request.
- You can also find the log correlation identifier attached to New Relic transactions.

### Install

Composer install the module.
```bash
composer require ampersand/magento2-log-correlation-id
```

Add the additional dependency injection config necessary to boot early in the application flow
```bash
mkdir app/etc/ampersand_magento2_log_correlation
cp vendor/ampersand/magento2-log-correlation-id/dev/ampersand_magento2_log_correlation/di.xml app/etc/ampersand_magento2_log_correlation/
```

At this point you can make any configuration changes
- [Add identifier to MySQL queries (disabled by default)](#add-identifier-to-mysql-queries)
- [Change the key name from `amp_correlation_id`](#change-the-key-name-from-amp_correlation_id)
- [Use existing correlation id from request header](#use-existing-correlation-id-from-request-header)

Run module installation
```bash
php bin/magento setup:upgrade
```

### Uninstall

```bash
rm app/etc/ampersand_magento2_log_correlation/di.xml
php bin/magento module:disable Ampersand_LogCorrelationId
```

### How it works

####  Entry point

This module creates a new cache decorator (`src/CacheDecorator/CorrelationIdDecorator.php`). 

It needs to be here so that it's constructed immediately after `Magento\Framework\Cache\Frontend\Decorator\Logger` which is the class responsible for instantiating `Magento\Framework\App\Request\Http` and the Logger triggered after. 

This is the earliest point in the magento stack where we can get any existing traceId from a request header (for example `cf-request-id`) and have it attached to any logs produced.

This cache decorator initialises the identifier which is immutable for the remainder of the request.

#### Exit points
- The correlation ID is attached to web responses as `X-Log-Correlation-Id` in `src/HttpResponse/HeaderProvider/LogCorrelationIdHeader.php`
    - REST API requests work a bit differently in Magento and attach the header using `src/Plugin/AddToWebApiResponse.php`
- Monolog files have the correlation ID added into their context section under the key `amp_correlation_id` via `src/Processor/MonologCorrelationId.php`
- Magento database logs have this identifier added by `src/Plugin/AddToDatabaseLogs.php`
- New Relic has this added as a custom parameter under the key `amp_correlation_id`
- CLI processes have it added as their "title" by using `cli_set_process_title` via `Ampersand\LogCorrelationId\CacheDecorator\CorrelationIdDecorator::setCliProcessTitle`
- MySQL queries have it added as a comment at the end of the query via `Ampersand\LogCorrelationId\Plugin\AddToDatabaseQueries::afterGetConnection`

### Example usage

Firstly you need to expose the header in your logs, this is an example for apache logs

```apacheconf
Header always note X-Log-Correlation-Id amp_correlation_id
LogFormat "%t %U %{amp_correlation_id}n" examplelogformat
CustomLog "/path/to/var/log/httpd/access_log" examplelogformat
```

If you are using Nginx, that's how you can add the correlation id to the access logs

```nginx
log_format examplelogformat '$time_local  $request $sent_http_x_log_correlation_id'
```

The above configuration would give log output like the following when viewing a page

```shell
[13/Jan/2021:11:34:37 +0000] /some-cms-page/ cid-61e04d741bf78
```

You could then search for all magento logs pertaining to that request 

```shell
$ grep -ri 61e04d741bf78 ./var/log
./var/log/system.log:[2022-01-13 16:04:14] main.INFO: some_log_entry_61e04d7e2ed03 {"amp_correlation_id":"cid-61e04d741bf78","some":"context"} []
```

If the request was long-running, or had an error it may also be flagged in new relic with the custom parameter `amp_correlation_id`
 
### Configuration and Customisation

#### Add identifier to MySQL queries 

Inside `app/etc/ampersand_magento2_log_correlation/di.xml`  you can change to `disabled="false"`

```diff
  <type name="Magento\Framework\App\ResourceConnection">
-     <plugin name="ampersand_log_correlation_id_db_query_plugin" disabled="true" />
+     <plugin name="ampersand_log_correlation_id_db_query_plugin" disabled="false" />
  </type>
```

This will add the correlation identifier to all queries like `SELECT store_group.* FROM store_group /* 'cid-652918943af7b811319570' */ `

#### Change the key name from `amp_correlation_id`

You can change the monolog/new relic key from `amp_correlation_id` using `app/etc/ampersand_magento2_log_correlation/di.xml`

```xml
<type name="Ampersand\LogCorrelationId\Service\CorrelationIdentifier">
    <arguments>
        <argument name="identifierKey" xsi:type="string">your_key_name_here</argument>
    </arguments>
</type>
```

#### Use existing correlation id from request header

If you want to use an upstream correlation/trace ID you can define one `app/etc/ampersand_magento2_log_correlation/di.xml`

```xml
<type name="Ampersand\LogCorrelationId\Service\CorrelationIdentifier">
    <arguments>
        <argument name="headerInput" xsi:type="string">X-Your-Header-Here</argument>
    </arguments>
</type>
```

If this is present on the request magento will use that value for `X-Log-Correlation-Id`, the monolog context, and the New Relic parameter. Otherwise magento will generate one.

_(README truncated for .md surface. Full README on https://packagento.com/ampersand/magento2-log-correlation-id.)_

## Recent Versions

| Version | Released |
|---|---|
| 2.0.1 | 2025-10-06 |
| 2.0.0 | 2025-03-11 |
| 1.4.0 | 2023-10-27 |
| 1.3.2 | 2023-08-23 |
| 1.3.1 | 2022-10-24 |
| 1.3.0 | 2022-10-18 |
| 1.2.5 | 2022-09-01 |
| 1.2.4 | 2022-09-01 |
| 1.2.3 | 2022-04-22 |
| 1.2.2 | 2022-01-31 |

Showing 10 of 16 versions. Full release history on https://packagento.com/ampersand/magento2-log-correlation-id.

## Dependencies

### Require

| Package | Constraint |
|---|---|
| magento/framework | * |
| monolog/monolog | ^3.6 |
| php | >=7.3.0 |

### Require (dev)

| Package | Constraint |
|---|---|
| ampersand/magento-docker-test-instance | ^0.2 |
| bitexpert/phpstan-magento | ^0.11 |
| friendsofphp/php-cs-fixer | ^3.4 |
| magento/magento-coding-standard | ^38.0 |
| magento/magento2-base | * |
| phpstan/phpstan | ^1.5 |
| phpunit/phpunit | ^9.5 |

## Quality

Latest release (2.0.1) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 1 | 1 | – | – |
| 2.4.8 | – | 1 | 1 | – |
| 2.4.9 | – | – | 1 | 1 |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Fail | 18 | 8 errors, 10 warnings (ruleset: Magento2) |
| PHPMD | Warning | 12 | 12 rule violations (MissingImport:6, UnusedFormalParameter:3, ErrorControlOperator:1, EmptyCatchBlock:1, NPathComplexity:1) |
| Cpd | Pass | 0 |  |
| Composer validate | Info | 2 | valid; 2 advisory notes (composer validate --strict) |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 3 | 3 | – | – |
| 2.4.8 | – | 3 | 3 | – |
| 2.4.9 | – | – | 3 | 3 |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Error | Error | – | – |
| 2.4.8 | – | 1 | not tested | – |
| 2.4.9 | – | – | 2 | 2 |

#### Integration Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Error | Error | – | – |
| 2.4.8 | – | Error | Error | – |
| 2.4.9 | – | – | Error | not tested |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | Pass | 0 |  |
| Malware scan | Pass | 0 |  |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["ampersand/magento2-log-correlation-id"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

ampersand is a Magento 2 vendor on Packagento. See https://packagento.com/ampersand.md for their full catalogue.