Table of Contents
Are you managing your Drupal site on Acquia Cloud? If yes, then Drupal Acquia Connector is your go-to module for deeper visibility, smoother workflows, and smarter performance tracking. It links your site directly to Acquia’s cloud platform, helping you monitor health, stream logs, and get proactive alerts—all in one place.
Whether you’re handling staging, development, or production environments, this connector keeps everything in sync. You can spot issues faster, push updates confidently, and centralize your monitoring process. That’s why many Drupal development experts rely on the Acquia Connector to automate monitoring and reduce risks across large-scale deployments.
In this blog, we will explore methods to integrate Acquia Connector with your Drupal site, how to configure it, and how to troubleshoot some common issues. So, let’s get started!
Methods to Integrate Drupal Acquia Connector
Integrating your Drupal site with Acquia Cloud can be done in a couple of effective ways, each depending on how much control or flexibility you need. Whether you’re looking for a plug-and-play solution or a more tailored integration, these methods cover both.
Method 1: Using the Acquia Connector Module (Recommended)
This is the most straightforward and widely used approach. The Acquia Connector module is developed by Acquia and provides native integration with Acquia Cloud. Here are the steps to install and enable the module:
composer require acquia/acquia-connector
drush en acquia_connector -y
After installation, you can either connect your site via the admin UI or configure credentials directly in your settings.php file.
Example configuration:
$settings['acquia_connector_settings']['identifier'] = 'your-site-id';
$settings['acquia_connector_settings']['key'] = 'your-api-key';
This method automatically enables services like Insight, log streaming, and environment detection with minimal setup.
Method 2: Using Acquia Cloud API (Advanced Use)
For developers or teams who prefer to automate and customize their workflows, the Acquia Cloud API offers a powerful alternative.
Use cases for the API include:
- Automating backups
- Deploying code between environments
- Cloning databases or files
- Downloading logs programmatically
Example of a simple API call (using curl):
curl -u username:apikey \\
https://cloudapi.acquia.com/v1/sites/example.com/envs/prod/dbs
This method is ideal when you want to integrate Acquia tasks into CI/CD pipelines or build custom management tools around your Drupal environment.
Both methods are valid–the module works great for most use cases, while the API offers more flexibility for automation-heavy or enterprise-level setups. Choose what fits your project needs best.
Step-by-Step Implementation Guide
Once you’ve chosen your integration method, setting up the Acquia Connector is a straightforward process.
Prerequisites
Before you begin, make sure the following are in place:
- A Drupal 9 or 10 site installed and running
- Access to Composer and Drush
- An active Acquia Cloud account with a provisioned site
- Acquia Cloud API credentials (site identifier and API key)
Installing the Acquia Connector Module
Use Composer to install the module and Drush to enable it:
composer require acquia/acquia-connector
drush en acquia_connector -y
This pulls in the latest version of the module and activates it on your site.
Connecting Your Site to Acquia Cloud
You have two main ways to link your Drupal site to Acquia Cloud:
Option 1: Through the Drupal Admin UI
- Go to Configuration → System → Acquia Connector
- Enter your Acquia subscription credentials
- Save the configuration
This is quick and works well for most setups.
Option 2: Via settings.php (for version-controlled or scripted environments)
Add your site identifier and API key securely:
$settings['acquia_connector_settings']['identifier'] = 'your-site-id';
$settings['acquia_connector_settings']['key'] = 'your-api-key';
This method is preferred in enterprise or multi-environment setups where credentials are stored securely in configuration files or secrets management systems.
Once your site is connected, you can begin using Acquia tools like Insight, log streaming, and environment detection immediately.
How to Customize and Extend the Connector
While the Acquia Connector module works well out of the box, it also gives developers flexibility to tailor it for specific use cases. Whether you’re working on a large-scale deployment or need tighter integration with other systems, the module offers ways to extend its capabilities through configuration and code.
Adjusting Behavior with Settings
You can override the default behaviors of the connector by modifying the settings in settings.php. This is especially useful in multi-environment setups or CI/CD pipelines.
Example: Disable Acquia Insight data collection in development:
if (getenv('AH_SITE_ENVIRONMENT') === 'dev') {
$settings['acquia_connector_settings']['hide_messages'] = TRUE;
}
This prevents unnecessary clutter in dev environments where you might not want to stream logs or display connector-related messages.
Other configurable options include:
- hide_messages: Hide Acquia system messages
- insight_api_key and insight_api_identifier: Manually define credentials
- allow_non_production: Force connection outside Acquia Cloud (not recommended)
Writing Custom Hooks
Drupal allows you to hook into core and contributed module functionality, including the Acquia Connector. You can write custom logic to trigger events or alter how the module behaves.
Example: Log when Acquia Insight refreshes:
function mymodule_acquia_connector_insight_refreshed($site_id) {
\Drupal::logger('custom')->notice('Acquia Insight refreshed for Site ID: ' . $site_id);
}
This hook can be used to send notifications, write to logs, or trigger additional automation whenever a site scan is complete.
Using with Other Acquia Services
The connector can work alongside other Acquia services like BLT (Build and Launch Tool) or Acquia Pipelines to create a more integrated DevOps workflow.
Use case:
Triggering log forwarding or environment-specific scripts post-deploy using Acquia Pipelines while keeping the Acquia Connector as the monitoring bridge.
By taking advantage of these customization options, you can make the Acquia Connector fit naturally into your workflow, whether you’re running a single site or managing an enterprise platform. Small tweaks go a long way in making the integration smarter and more adaptable.
Troubleshooting Common Issues
Even though the Drupal Acquia Connector is stable and widely used, setup and integration don’t always go perfectly. Minor misconfigurations or overlooked settings can lead to unexpected behavior. Below are the most common issues developers run into, along with practical ways to resolve them fast.
Authentication Failures
Connection errors are often related to incorrect credentials or misplacement of configuration settings.
Symptoms:
- “Invalid API Key or Identifier” error
- Connection not established even after saving settings
Fix:
Make sure you’re using the correct API key and site identifier from your Acquia Cloud dashboard. These values must be accurate and entered exactly as provided.
If you’re setting them via settings.php, the placement matters. They should appear before the $settings[‘config_sync_directory’] line to be recognized properly during bootstrap.
Example:
$settings['acquia_connector_settings']['identifier'] = 'your-site-id';
$settings['acquia_connector_settings']['key'] = 'your-api-key';
Tip: Both the identifier and key are case-sensitive. Always copy-paste them carefully and avoid extra spaces or line breaks.
Insight Score Not Updating
Insight scores give you a clear view of site performance and best practice alignment. But sometimes, the score may appear stale or not show up at all.
Symptoms:
- The score is outdated or not visible in the Acquia dashboard
- Recent changes aren’t reflected in Insight
Fix:
Run the following Drush command to manually sync Insight data with Acquia:
drush acquia-connector-refresh
Also, ensure that cron is running regularly. Acquia Insight depends on Drupal cron jobs to fetch the latest metrics and update the dashboard.
Reminder: If you’ve recently disabled cron or made heavy site changes, triggering it manually can fix delayed updates.
Log Stream Not Appearing in Acquia Cloud
Streaming logs to Acquia Cloud is useful for real-time debugging and error tracking. If they don’t show up, it usually comes down to a missing configuration.
Symptoms:
- No logs are showing up in the Acquia logging UI
- Log levels appear inconsistent
Fix:
First, verify that log streaming is enabled in the admin UI under the Acquia Connector settings. Then, check the current log level in your settings.php or configuration files. It controls how much detail gets streamed:
$config['system.logging']['error_level'] = 'all'; // Or 'some' / 'hide'
Tip: Some environments or modules may suppress certain log levels. Adjust logging granularity based on what you need to monitor.
Connector Not Detecting Environment
Environment detection is critical for conditionally enabling features like logging, debugging, or feature flags based on whether you’re on dev, test, or prod.
Symptoms:
- Acquia tools behave the same across all environments
- Features like log suppression aren’t environment-aware
Fix:
Check if the AH_SITE_ENVIRONMENT environment variable is available. This variable tells Acquia what environment the site is running in. You can test its availability using this quick line in your code or with the Devel module:
dpm(getenv('AH_SITE_ENVIRONMENT'));
If it returns FALSE, the environment isn’t being detected correctly. This may indicate a hosting or deployment config issue. In such cases, it’s best to review your hosting setup or contact Acquia support.
Tip: Some CI/CD setups or local environments may strip environment variables. Always test on Acquia-hosted servers for accurate results.
Let’s Conclude
The Drupal Acquia Connector brings a powerful layer of integration between your Drupal site and the Acquia Cloud platform. From real-time health monitoring and log streaming to environment detection and security alerts, it’s built to enhance visibility, control, and performance.
By setting it up correctly and customizing it to your needs, you can streamline your site management while minimizing risk and manual effort. It’s especially useful for teams managing complex workflows or multiple environments.
If you need help implementing or customizing the Acquia Connector, our Drupal development agency is here to guide you through every step.
