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

Optional settings

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:

1. Runs Drupal cron and captures the result and any exceptions.
2. Measures wall-clock duration using hrtime().
3. Builds an event payload and stores last_run metadata in Drupal state.
4. Sends the event to New Relic (failures always; successes based on config).
5. 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:

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.