PHPackages                             oxid-support/heartbeat - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. oxid-support/heartbeat

ActiveOxideshop-module[Logging & Monitoring](/categories/logging)

oxid-support/heartbeat
======================

OXID eShop Heartbeat module with detailed request logging, correlation ID tracking, symbol monitoring, and GraphQL remote configuration

3.0.1(1mo ago)031[1 issues](https://github.com/oxid-support/heartbeat-module/issues)[3 PRs](https://github.com/oxid-support/heartbeat-module/pulls)proprietaryPHPCI passing

Since Sep 11Pushed 1w agoCompare

[ Source](https://github.com/oxid-support/heartbeat-module)[ Packagist](https://packagist.org/packages/oxid-support/heartbeat)[ RSS](/packages/oxid-support-heartbeat/feed)WikiDiscussions b-7.1.x Synced today

READMEChangelog (9)Dependencies (33)Versions (40)Used By (0)

OXS :: Heartbeat
================

[](#oxs--heartbeat)

> **You are on branch `b-7.1.x`** (Heartbeat 2.x, for OXID eShop 7.1 to 7.5).
>
> Other supported lines:
>
> - **OXID 6.5** → branch [`b-6.5.x`](https://github.com/oxid-support/heartbeat-module/tree/b-6.5.x) (Heartbeat 1.x)
> - **OXID 7.0** → branch [`b-7.0.x`](https://github.com/oxid-support/heartbeat-module/tree/b-7.0.x) (Heartbeat 3.x)
>
> Customers installing via `composer require oxid-support/heartbeat` get the matching version automatically; this switcher is for source browsing and contributors.

**OXS Heartbeat** is an OXID eShop module that enables **remote monitoring and support** for OXID shops.

It provides:

- **Request Logger**: Detailed request logging with correlation ID tracking
- **Log Sender**: Collect and provide log files to external monitoring systems
- **Diagnostics Provider**: Shop diagnostic information (modules, PHP, server)
- **API User**: Secure GraphQL API access for OXID Support

All components are accessible via GraphQL API, allowing OXID Support to remotely analyze shop issues without direct server access.

> **Full Control**: Remote access is **completely optional**. Each component can be enabled/disabled independently by the shop operator. No data is transmitted unless explicitly activated. Access can be revoked at any time.

---

Installation
------------

[](#installation)

### Step 1: Install via Composer

[](#step-1-install-via-composer)

```
composer require oxid-support/heartbeat
```

Composer automatically selects the version that matches your OXID installation. No version constraint or repository configuration required.

#### For local development

[](#for-local-development)

```
git clone https://github.com/oxid-support/heartbeat-module.git repo/oxs/heartbeat
composer config repositories.oxid-support/heartbeat path repo/oxs/heartbeat
composer require oxid-support/heartbeat:@dev
```

> **Note**: The OXID GraphQL Base and GraphQL Configuration Access modules are installed automatically as dependencies.

### Step 2: Run Database Migrations

[](#step-2-run-database-migrations)

```
./vendor/bin/oe-eshop-doctrine_migration migrations:migrate oe_graphql_base
./vendor/bin/oe-eshop-doctrine_migration migrations:migrate oxsheartbeat
```

### Step 3: Clear Shop Cache

[](#step-3-clear-shop-cache)

```
./vendor/bin/oe-console oe:cache:clear
```

### Step 4: Activate Modules

[](#step-4-activate-modules)

**Important**: The GraphQL modules must be activated **before** activating the Heartbeat module.

```
./vendor/bin/oe-console oe:module:activate oe_graphql_base
./vendor/bin/oe-console oe:module:activate oe_graphql_configuration_access
./vendor/bin/oe-console oe:module:activate oxsheartbeat
```

For more details on OXID GraphQL installation, see the [official documentation](https://docs.oxid-esales.com/interfaces/graphql/en/latest/install.html).

---

Compatibility
-------------

[](#compatibility)

- **Module 2.x**: OXID 7.1 to 7.5.x
- **Module 3.x**: OXID 7.0.x
- **Module 1.x**: OXID 6.5

Composer picks the right module version based on the installed OXID core. Customers never need to specify a module version manually.

Branch structure
----------------

[](#branch-structure)

This repo follows a Symfony / Doctrine style stabilization-branch layout. One long-lived branch per supported OXID line, no `main`:

- **`b-7.1.x`** (default) active development for the OXID 7.1 to 7.5 line, Heartbeat 2.x
- **`b-7.0.x`** maintenance branch for the OXID 7.0 line, Heartbeat 3.x
- **`b-6.5.x`** maintenance branch for the OXID 6.5 line, Heartbeat 1.x

When OXID introduces a new line that needs separate maintenance, a new `b-.x` branch is cut from the current default.

Where to open your PR:

- Bug or feature for OXID 7.1 to 7.5 → `b-7.1.x`
- Bug for OXID 7.0 only → `b-7.0.x`
- Bug for OXID 6.5 only → `b-6.5.x`

Updating an existing installation
---------------------------------

[](#updating-an-existing-installation)

When a new module version is released:

```
composer update --no-dev
./vendor/bin/oe-eshop-doctrine_migration migrations:migrate oxsheartbeat
./vendor/bin/oe-console oe:cache:clear
```

When upgrading OXID itself, bump OXID and Heartbeat together in a single resolve:

```
composer require \
  oxid-esales/oxideshop-metapackage-ee:vX.Y.Z \
  oxid-support/heartbeat \
  --with-all-dependencies
```

Two outcomes:

- **Compatible Heartbeat version exists**: Composer installs it automatically.
- **No matching Heartbeat yet**: Composer fails before any change is written. Wait for the next release or temporarily remove the module before the OXID upgrade.

---

Components
----------

[](#components)

All four components are optional and can be enabled or disabled independently by the customer in the Admin interface under **OXS :: Heartbeat**.

### 1. API User

[](#1-api-user)

Additional option to grant OXID Support extended access to the module's GraphQL endpoints, so logs and diagnostics can be evaluated externally. Through this access, Support can also enable or disable other components of this module on demand to improve the data basis for support cases. Enable only if you want Support to read Request Logger configuration, retrieve logs or query diagnostics remotely.

### 2. Request Logger

[](#2-request-logger)

Records controller actions, request parameters and the classes loaded during the lifecycle of a request to local log files. Provides a GraphQL API for remote configuration when API User is enabled.

### 3. Log Sender

[](#3-log-sender)

Collects log files from various sources and provides them via GraphQL API for remote retrieval when API User is enabled.

### 4. Diagnostics Provider

[](#4-diagnostics-provider)

Provides shop diagnostic information (modules, PHP config, server info) via GraphQL API when API User is enabled.

---

Features
--------

[](#features)

### Request Logger Features

[](#request-logger-features)

- **Request Route Logging**

    - Records controller (`cl`) and action (`fnc`)
    - Logs referer, user agent, GET and POST parameters
    - **Configurable redaction**: Choose between redacting all values (default) or selective redaction of sensitive parameters
    - Keys always remain visible for diagnostics
    - Arrays/objects converted to JSON (no length limits)
    - Scalar values logged unchanged when selective redaction is enabled
- **Correlation ID Tracking**

    - Unique ID assigned to each request for tracing across multiple requests
    - Correlation ID transmitted via HTTP header (`X-Correlation-Id`) and cookie
    - Cookie TTL: 30 days (2592000 seconds)
    - Allows tracking user sessions and multi-step flows
    - Each log file named by correlation ID for easy request grouping
- **Symbol Tracking**

    - Tracks all classes, interfaces, and traits **declared during the request**
    - Preserves the **exact load order**
    - Filters:
        - Removes OXID module aliases (`*_parent`)
        - Removes legacy lowercase aliases (`oxuser`, `oxdb`, …)
        - Removes aliases without a file (`class_alias`, eval)
    - Produces a **raw list of FQCNs** (fully-qualified class names)
- **Request Finish Logging**

    - Duration in ms (`durationMs`)
    - Memory usage in MB (`memoryMb`)
- **Security & Privacy**

    - **Default maximum privacy**: All parameter values redacted by default
    - **Optional selective redaction**: Configure specific sensitive parameters (passwords, tokens, IDs) to mask
    - No session secrets or authentication data in logs
    - All logs stored locally on server filesystem only
    - No data transmission to external services

### Remote Configuration (via GraphQL API)

[](#remote-configuration-via-graphql-api)

- Query and modify all Request Logger settings remotely
- Activate/deactivate logging via API
- Authenticate via JWT with dedicated API user
- Requires API User setup

---

Module Configuration
--------------------

[](#module-configuration)

The module provides configurable settings accessible via OXID Admin under **OXS :: Heartbeat**.

### API User Setup (Required First)

[](#api-user-setup-required-first)

Navigate to: **OXS :: Heartbeat → API User → Setup**

The API User is required for all components that need remote access. Follow the setup workflow:

1. **Migrations**: Ensure database migrations are executed
2. **GraphQL Base**: Ensure GraphQL Base module is activated
3. **Setup Token**: Copy the setup token and send it to OXID Support
4. **Activation**: Wait for OXID Support to set the API password

Once complete, the API User status shows "Active" and other components can be enabled.

### Request Logger Settings

[](#request-logger-settings)

Navigate to: **OXS :: Heartbeat → Request Logger → Settings**

**Note**: Requires API User setup to be complete.

#### 1. Component Activation

[](#1-component-activation)

- Toggle to enable/disable the Request Logger component

#### 2. Log Frontend Requests

[](#2-log-frontend-requests)

- **Default**: `false` (disabled)
- Enable logging for frontend (shop) requests

#### 3. Log Admin Requests

[](#3-log-admin-requests)

- **Default**: `false` (disabled)
- Enable logging for admin panel requests

#### 4. Detailed Logging

[](#4-detailed-logging)

- **Default**: `false` (disabled)
- When enabled, additionally logs symbol tracking (request.symbols) showing all classes/interfaces/traits loaded during the request

#### 5. Redact all values

[](#5-redact-all-values)

- **Default**: `true` (enabled)
- When enabled, redacts ALL request parameter values (GET/POST) in logs, showing only parameter keys
- When disabled, only parameters listed in the "Redact Fields" setting are masked

#### 6. Redact Fields

[](#6-redact-fields)

- **Default**: `['pwd', 'lgn_pwd', 'lgn_pwd2', 'newPassword']`
- List of parameter names (case-insensitive) whose values should be masked as `[redacted]` in logs
- Only applies when "Redact all values" is disabled

### Log Sender Settings

[](#log-sender-settings)

Navigate to: **OXS :: Heartbeat → Log Sender → Manage**

**Note**: Requires API User setup to be complete.

- **Component Activation**: Toggle to enable/disable the Log Sender
- **Log Sources**: View all recognized log sources with availability status
- **Source Toggle**: Enable/disable individual log sources for sending
- **Static Paths**: Configure additional log files or directories to monitor

Log sources can be registered via:

- **DI Tag Provider**: Services implementing `LogPathProviderInterface` with tag `oxs.logsender.provider`
- **Static Paths**: Manual configuration in the admin interface

### Diagnostics Provider Settings

[](#diagnostics-provider-settings)

Navigate to: **OXS :: Heartbeat → Diagnostics Provider → Manage**

**Note**: Requires API User setup to be complete.

- **Component Activation**: Toggle to enable/disable the Diagnostics Provider

Provides the following information via GraphQL API:

- Shop details (URL, edition, version, statistics)
- Installed modules
- System information
- PHP configuration
- Server information

---

Correlation ID System
---------------------

[](#correlation-id-system)

The module implements a sophisticated correlation ID system that tracks requests across multiple page loads and API calls.

### How It Works

[](#how-it-works)

1. **ID Resolution**: The system attempts to resolve an existing correlation ID from:
    - HTTP Header `X-Correlation-Id`
    - Cookie `X-Correlation-Id`
    - If neither exists: Generate new UUID v4
2. **ID Emission**: The correlation ID is returned to the client via:
    - HTTP Response Header: `X-Correlation-Id: `
    - Cookie: `X-Correlation-Id=; Max-Age=2592000; Path=/; HttpOnly; SameSite=Lax`
3. **Log Association**: All log entries include the correlation ID in the `context` field

### Use Cases

[](#use-cases)

- **Multi-step User Flows**: Track a user's journey from product page → cart → checkout → order completion
- **Error Debugging**: When a user reports an error, search logs by their correlation ID to see all recent actions
- **Session Analysis**: Group logs by correlation ID to analyze complete user sessions (up to 30 days)

---

Log Events
----------

[](#log-events)

A request usually emits three entries:

### 1. `request.start`

[](#1-requeststart)

**Content:**

- HTTP method, URI, referer, user agent
- Redacted GET/POST parameters (sensitive values masked)
- Shop context: version, edition, shopId, shopUrl, language
- Session/user info: sessionId, userId, username
- Request metadata: IP address, PHP version
- Correlation ID for tracing

### 2. `request.symbols`

[](#2-requestsymbols)

- Array of all newly declared FQCNs (fully-qualified class names) in load order
- Only logged when "Detailed Logging" is enabled
- Useful for diagnosing template/render paths and module extension chains

### 3. `request.finish`

[](#3-requestfinish)

- Request duration in milliseconds (`durationMs`)
- Peak memory usage in megabytes (`memoryMb`)

---

Output Location & Format
----------------------------

[](#output-location--format)

### File Location

[](#file-location)

Logs are written to:

```
OX_BASE_PATH/log/oxs-heartbeat/oxs-heartbeat-.log

```

### File Organization

[](#file-organization)

- **One file per correlation ID** - All requests sharing the same correlation ID write to the same file
- **Multiple entries per file** - Each request typically creates 2-3 entries: `request.start`, `request.symbols` (if detailed), `request.finish`
- **Monolog Line Format** - Each log entry follows Monolog's standard format: `[timestamp] channel.LEVEL: message {json_context}`

Each `.log` file contains newline-separated log entries in Monolog's format. The context data is JSON-encoded, making it parseable by log analysis tools.

---

GraphQL API
-----------

[](#graphql-api)

The Heartbeat module provides GraphQL APIs for remote management of all components.

### Authentication

[](#authentication)

1. During module activation, an API user (`heartbeat-api@oxid-esales.com`) is created
2. To enable remote access, use the setup token from the Admin interface to set the API user password (via OXID Support: ) Note: The API user is only used for remote access of the Heartbeats data through the OXID Support and access can be revoked at any time.

### Available Operations

[](#available-operations)

**Request Logger:**

- Query and modify logging settings
- Activate/deactivate the Request Logger component

**Log Sender:**

- Query available log sources
- Read log file contents

**Diagnostics Provider:**

- Query shop diagnostics (modules, PHP config, server info)

---

Testing
-------

[](#testing)

Tests run standalone without requiring a full OXID shop installation. The module uses `oxideshop-ce` as a dev dependency to provide the necessary framework interfaces.

### Setup

[](#setup)

```
cd repo/oxs/heartbeat
composer install
```

### Run Tests

[](#run-tests)

```
./vendor/bin/phpunit --configuration tests/phpunit.xml
```

### Test Coverage

[](#test-coverage)

The test suite includes unit tests for all components. Some integration tests (e.g., `ModuleEvents`) are skipped in standalone mode as they require a full shop context.

---

License
-------

[](#license)

See [LICENSE](LICENSE) file for details.

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance96

Actively maintained with recent releases

Popularity9

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 53.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~16 days

Recently: every ~1 days

Total

17

Last Release

31d ago

Major Versions

1.x-dev → 2.0.02026-05-21

1.0.1 → 2.0.12026-05-27

2.0.2 → 3.0.02026-05-27

2.0.3 → 3.0.12026-06-02

PHP version history (4 changes)1.0.0-beta.3PHP ^7.4 || ^8.0 || ^8.1 || ^8.2 || ^8.3

1.x-devPHP ^8.0 || ^8.1

2.0.0PHP ^8.2 || ^8.3 || ^8.4

3.0.0PHP ^8.0 || ^8.1 || ^8.2 || ^8.3 || ^8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/555b104d3da0a94ea1ccc07f2bbd8ac197c915a84df5ffec7beec4b64ff8748d?d=identicon)[OXID Support](/maintainers/OXID%20Support)

---

Top Contributors

[![michaelkeiluweit](https://avatars.githubusercontent.com/u/2961521?v=4)](https://github.com/michaelkeiluweit "michaelkeiluweit (71 commits)")[![oxidsimongassenschmidt](https://avatars.githubusercontent.com/u/57358516?v=4)](https://github.com/oxidsimongassenschmidt "oxidsimongassenschmidt (57 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (5 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/oxid-support-heartbeat/health.svg)

```
[![Health](https://phpackages.com/badges/oxid-support-heartbeat/health.svg)](https://phpackages.com/packages/oxid-support-heartbeat)
```

###  Alternatives

[psr/log

Common interface for logging libraries

10.4k1.2B11.5k](/packages/psr-log)[open-telemetry/api

API for OpenTelemetry PHP.

1941.5M276](/packages/open-telemetry-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)