README

A Drupal 10.3+ / 11 module that instruments cron execution and sends results to the New Relic Event API for alerting on cron failures, slow runs, and missing runs.

Features

Drush command (bt:newrelic-cron / btnrc) wraps \Drupal::cron()->run() with precise timing via hrtime().
Connection testing — validate your API credentials before enabling with drush bt:newrelic-test or the admin UI "Test Connection" button.
New Relic Event API integration — sends custom events to US or EU data centers.
Acquia Cloud Platform auto-detection — reads AH_SITE_ENVIRONMENT and AH_SITE_NAME environment variables automatically.
Admin settings form at /admin/config/system/newrelic-cron for full GUI configuration.
Failure isolation — New Relic transport errors never affect the cron exit code.
Success event suppression — optionally send events only on failures to reduce event volume.

Requirements

Drupal 10.3+ or 11.x
Drush 12+ or 13
PHP 8.1+
A New Relic account with an Insert API key (NRII-...)

Installation

Via Composer (recommended)

composer require drupal-mods/newrelic_cron
drush en newrelic_cron

Manual

Place the module directory at web/modules/custom/newrelic_cron/ and enable:

drush en newrelic_cron

Configuration

Navigate to Administration > Configuration > System > New Relic Cron (/admin/config/system/newrelic-cron).

Required settings

Setting	Description
Enabled	Toggle event reporting on/off
Account ID	Your New Relic account ID
Insert API key	A New Relic Insert API key (NRII-…)
Region	US or EU data center

Optional settings

Setting	Default	Description
Event type	`CronJobExecution`	Custom event type name in New Relic
Job name	`drupal-cron`	Job identifier in events
Environment label	(auto-detected)	Fallback if `AH_SITE_ENVIRONMENT` not set
Site URI		Site URI included in events
Send success events	Yes	Whether to send events for successful runs
Max message length	2000	Truncates error messages at this length
HTTP timeout	5	Timeout in seconds for the API call

Securing the Insert API key

For production, override the key in settings.php instead of storing it in config:

$config['newrelic_cron.settings']['insert_key'] = getenv('NEWRELIC_INSERT_KEY');

Usage

Drush command

# Run instrumented cron
drush bt:newrelic-cron

# Short alias
drush btnrc

The command:

Runs Drupal cron and captures the result and any exceptions.
Measures wall-clock duration using hrtime().
Builds an event payload and stores last_run metadata in Drupal state.
Sends the event to New Relic (failures always; successes based on config).
Returns 0 on success, 1 on failure.

Testing the connection

Before enabling cron reporting, validate your configuration:

# Test New Relic API connection
drush bt:newrelic-test

# Short alias
drush btnrc:test

This sends a test event to New Relic and reports success or failure with actionable hints:

✅ Connection successful! Test event sent to New Relic (HTTP 200).
❌ Authentication failed. Check your Insert API key.
❌ Account not found. Check your Account ID.

You can also test the connection from the admin UI using the Test Connection button at /admin/config/system/newrelic-cron.

Acquia Cloud cron job

/usr/local/bin/cron-wrapper.sh /var/www/html/mysite/vendor/bin/drush --root=/var/www/html/mysite/docroot -l https://mysite.com btnrc

Scheduler (non-Acquia)

*/15 * * * * cd /var/www/mysite && vendor/bin/drush btnrc 2>&1 | logger -t drupal-cron

Event payload

Each event sent to New Relic contains:

Field	Type	Example
`eventType`	string	`CronJobExecution`
`jobName`	string	`drupal-cron`
`status`	string	`success` or `failed`
`timestamp`	int	`1711929600`
`durationMs`	float	`4523.17`
`environment`	string	`prod`
`siteName`	string	`mysite`
`siteUri`	string	`https://mysite.com`
`exitCode`	int	`0`
`message`	string	(empty on success)

Example NRQL queries

Recent cron executions

SELECT * FROM CronJobExecution
  SINCE 1 day ago
  LIMIT 100

Failure count by environment

SELECT count(*) FROM CronJobExecution
  WHERE status = 'failed'
  FACET environment
  SINCE 7 days ago

Average duration over time

SELECT average(durationMs) FROM CronJobExecution
  TIMESERIES AUTO
  SINCE 24 hours ago

Slow cron runs (> 60 seconds)

SELECT timestamp, environment, siteName, durationMs, message
  FROM CronJobExecution
  WHERE durationMs > 60000
  SINCE 7 days ago

Missing cron alert (NRQL condition)

SELECT count(*) FROM CronJobExecution
  WHERE environment = 'prod'
  SINCE 30 minutes ago

Set the alert threshold to count < 1 to fire when no cron event arrives within the expected window.

Architecture

NewRelicCronCommands (Drush command)
  ├── CronInterface::run()       — executes Drupal cron
  ├── CronExecutionRecorder      — builds payload, records state
  └── NewRelicEventClient        — HTTP POST to New Relic Event API

NewRelicEventClient — Posts JSON to the NR Event API with the configured Insert key. Supports US and EU endpoints.
CronExecutionRecorder — Builds event payloads with environment/site metadata, stores last_run in Drupal state, controls success-event gating.
NewRelicCronCommands — Drush command that orchestrates cron execution, timing, and event dispatch.

Development

Install dev dependencies

composer install

Run tests

vendor/bin/phpunit

Static analysis

vendor/bin/phpstan analyse

Coding standards

vendor/bin/phpcs
vendor/bin/phpcbf  # auto-fix

Future enhancements

Per-hook instrumentation (report individual hook_cron implementations).
Queue worker monitoring.
Dashboard integration with pre-built New Relic dashboards.
Drush command to send a test event for validating configuration.

License

This project is licensed under the GPL-2.0-or-later license.

drupal-mods / newrelic_cron

Maintainers

Package info

Statistics

Security