Ever pushed a shiny new feature or a critical bug fix to production, only to find your application’s performance graph suddenly spike (or dip, for the wrong reasons) a few minutes later? It’s that familiar pang of dread, isn’t it? You know something changed, but pinning down exactly what deployment caused the shift can feel like a high-stakes game of ‘guess who’ in a maze of logs and Git history.
Enter New Relic, a true hero in the realm of application performance monitoring (APM). It gives us unparalleled visibility into our applications’ health. But here’s a secret: its power isn’t fully unleashed until you can correlate those performance metrics directly with your code deployments. Imagine seeing a precise marker on your New Relic charts every single time new code goes live. No more guessing, just immediate, data-driven insight.
This isn’t just a “nice-to-have”; it’s a fundamental shift in how you diagnose issues and understand the impact of your work. And if you’re working with Laravel, achieving this level of deployment tracking is surprisingly straightforward, thanks to the elegant simplicity of custom Laravel commands. Let’s dive into how you can make your CI/CD pipeline and New Relic sing in harmony.
The Undeniable Value of Linking Deployments to Performance
Why bother with this extra step? Isn’t New Relic already telling you if your app is slow? Absolutely. But generic performance data without context is like a doctor telling you you have a fever without knowing if you just ran a marathon or have the flu. The “why” is crucial.
When you track code deployments in New Relic, you’re not just adding a dot to a graph; you’re creating a powerful anchor point. Did CPU usage jump after deployment A? Was the error rate higher after deployment B? These insights become immediately visible. This direct correlation empowers your team to:
- Diagnose Issues Faster: Pinpoint the exact deployment responsible for a performance regression, error spike, or even an unexpected improvement. No more digging through multiple systems; the answer is right there on your New Relic dashboard.
- Assess Impact Accurately: Understand the real-world performance implications of new features or infrastructure changes. Did that caching improvement actually make a difference? Now you’ll know for sure.
- Improve Rollback Decisions: If a deployment goes south, identifying it quickly allows for a faster, more confident rollback, minimizing downtime and user impact.
- Foster a Culture of Accountability (the good kind): Teams can see the immediate impact of their code changes, encouraging careful development and a data-driven approach to releasing software.
In essence, integrating deployment tracking transforms your monitoring from reactive observation to proactive, insightful analysis. It’s about moving from “what happened?” to “what happened, and which specific code change caused it?”
Crafting Your Custom Laravel Command for New Relic
The core of our solution lies in a custom Laravel command. Laravel’s artisan console commands are incredibly versatile, allowing us to encapsulate complex logic into simple, reusable CLI tools. Our goal here is to create a command that, when run, makes an API call to New Relic’s Deployment API, telling it that a new version of our application has just gone live.
Step 1: Generate the Command Skeleton
First things first, let’s create our command. Open your terminal in your Laravel project root and run:
php artisan make:command NewRelicDeploymentCommandThis will generate a new file at `app/Console/Commands/NewRelicDeploymentCommand.php`. Inside this file, you’ll find a basic structure. We’ll focus on the `handle()` method, which is where our logic will reside.
// Inside app/Console/Commands/NewRelicDeploymentCommand.php protected $signature = 'newrelic:deploy {--revision=} {--user=} {--changelog=}'; protected $description = 'Notifies New Relic of a new deployment.'; public function handle()
{ // ... our logic goes here ...
}
Notice the `$signature` property. We’ve defined three optional arguments: `revision`, `user`, and `changelog`. These are crucial pieces of information for New Relic to display alongside your deployment marker.
Step 2: Making the API Call to New Relic
New Relic provides a straightforward REST API for recording deployments. You’ll need an Admin API key (not your License Key) and your application’s name as configured in New Relic. The API endpoint is typically `https://api.newrelic.com/v2/applications/{APP_ID}/deployments.json` or `https://api.newrelic.com/v2/applications/{APP_NAME}/deployments.json` (using the application name directly is often simpler if you ensure it’s unique).
Inside your `handle()` method, you’ll use a HTTP client to send a POST request. Laravel’s built-in `Http` facade (powered by Guzzle) is perfect for this. First, ensure you have Guzzle installed:
composer require guzzlehttp/guzzleNow, let’s flesh out the `handle()` method:
// Inside app/Console/Commands/NewRelicDeploymentCommand.php use Illuminate\Console\Command;
use Illuminate\Support\Facades\Http; class NewRelicDeploymentCommand extends Command
{ protected $signature = 'newrelic:deploy {--revision=} {--user=} {--changelog=}'; protected $description = 'Notifies New Relic of a new deployment.'; public function handle() { $newRelicApiKey = env('NEW_RELIC_ADMIN_API_KEY'); $newRelicAppName = env('NEW_RELIC_APP_NAME'); // Your app name in New Relic if (!$newRelicApiKey || !$newRelicAppName) { $this->error('NEW_RELIC_ADMIN_API_KEY or NEW_RELIC_APP_NAME not set in .env'); return Command::FAILURE; } $revision = $this->option('revision') ?? shell_exec('git rev-parse HEAD'); $user = $this->option('user') ?? get_current_user() ?? 'CI/CD System'; $changelog = $this->option('changelog') ?? 'Automated deployment via Laravel command.'; // Basic validation for revision if (empty($revision)) { $this->error('Could not determine revision. Please provide it via --revision option.'); return Command::FAILURE; } $deploymentData = [ 'deployment' => [ 'revision' => trim($revision), 'changelog' => $changelog, 'description' => 'Code deployed to production.', // You can customize this 'user' => $user, ] ]; try { $response = Http::withHeaders([ 'X-Api-Key' => $newRelicApiKey, 'Content-Type' => 'application/json', ])->post("https://api.newrelic.com/v2/applications/{$newRelicAppName}/deployments.json", $deploymentData); if ($response->successful()) { $this->info("Successfully notified New Relic of deployment for {$newRelicAppName}. Revision: {$revision}"); return Command::SUCCESS; } else { $this->error("Failed to notify New Relic: {$response->status()} - {$response->body()}"); return Command::FAILURE; } } catch (\Exception $e) { $this->error("An error occurred: " . $e->getMessage()); return Command::FAILURE; } }
}
A few crucial details in the code above:
- Environment Variables: We’re pulling `NEW_RELIC_ADMIN_API_KEY` and `NEW_RELIC_APP_NAME` from your `.env` file. This is vital for security and flexibility.
- Dynamic Data: We attempt to get the Git revision (`git rev-parse HEAD`), the current user, or provide sensible defaults if the options aren’t passed. This makes the command robust even if not all information is explicitly provided.
- Error Handling: Basic checks for missing environment variables and API call failures are included, giving you feedback if something goes wrong.
Step 3: Secure Your New Relic API Key
Never hardcode API keys! Add these to your `.env` file:
NEW_RELIC_ADMIN_API_KEY="YOUR_NEW_RELIC_ADMIN_API_KEY"
NEW_RELIC_APP_NAME="Your New Relic App Name"
Make sure this `.env` file is properly managed and not exposed in public repositories.
Integrating with Your CI/CD Pipeline
This is where your Laravel command truly shines. The goal is to automatically execute this command every time your application is successfully deployed. Most modern CI/CD platforms (GitHub Actions, GitLab CI, Buddy, Jenkins, etc.) can run arbitrary shell commands, making integration a breeze.
When to Run the Command
The best practice is to run the `newrelic:deploy` command *after* your application code has been successfully deployed to the server and is available, but ideally *before* it starts serving significant traffic (if your pipeline allows for blue/green or canary deployments). For simpler deployments, running it right at the end of the deployment script is perfectly fine.
Example: GitHub Actions Workflow Snippet
Let’s imagine a simplified GitHub Actions workflow for deploying to a server via SSH. You’d add a step similar to this:
# ... other deployment steps ... - name: Notify New Relic of Deployment uses: appleboy/ssh-action@master with: host: ${{ secrets.SSH_HOST }} username: ${{ secrets.SSH_USERNAME }} key: ${{ secrets.SSH_PRIVATE_KEY }} script: | cd /path/to/your/laravel/app php artisan newrelic:deploy \ --revision="${{ github.sha }}" \ --user="${{ github.actor }}" \ --changelog="Deployed by GitHub Actions - Commit: ${{ github.event.pull_request.title || github.event.head_commit.message }}" env: NEW_RELIC_ADMIN_API_KEY: ${{ secrets.NEW_RELIC_ADMIN_API_KEY }} NEW_RELIC_APP_NAME: "Your New Relic App Name"
Notice how we’re dynamically pulling in values like the Git commit SHA (`github.sha`), the committer’s username (`github.actor`), and the commit message/PR title for the changelog. These values make your New Relic deployment markers incredibly informative.
For `NEW_RELIC_ADMIN_API_KEY`, remember to store it as a secret in your CI/CD platform’s settings. The `NEW_RELIC_APP_NAME` can often be a direct environment variable or also a secret, depending on your setup.
Key Considerations for CI/CD Integration:
- Environment Setup: Ensure your CI/CD environment has PHP and Composer available to run `php artisan`.
- Secrets Management: Always use your CI/CD platform’s secrets management for the New Relic API key.
- Application Path: Make sure the `cd` command points to the correct root of your Laravel application on the deployed server.
- Robustness: Consider what happens if the New Relic API call fails. Should it halt the deployment? Probably not, but logging the error is important.
Conclusion: Empowering Your DevOps Workflow
Implementing New Relic deployment tracking with a custom Laravel command and integrating it into your CI/CD pipeline is a relatively small effort with a monumental payoff. You’re transforming your New Relic dashboards from mere monitoring screens into rich, contextualized narratives of your application’s evolution.
This approach empowers your developers to see the immediate impact of their code, helps your operations teams respond to incidents with surgical precision, and ultimately fosters a more efficient, data-driven culture throughout your software development lifecycle. Stop guessing and start knowing. Your future self, and your entire team, will thank you.
