This December, Netlify launched an incredibly fun and public-spirited project: Dusty Domains. It's a bit of a trope that whenever anyone has an idea for a project, they immediately register a domain name for it. It makes sense in some ways. Coming up with a name for a project is hard. If I were to make a list of the three things I find most challenging about programming, naming things would be right at the top.
1. Naming things
3. Race conditions
2. Character encoding đź¤¬
4. Off-by-one errors
If I find a name I like and the domain is still available, of course I will want to register it before someone else does.
But many of these projects never get past the idea phase, and the registered domains collect virtual dust. Often we may not even think about them again, until of course we receive the annual domain renewal notification, a guilty reminder of our abandoned projects.
Dusty Domains is attempting to put these dormant domains to good use. For each domain dusted off and deployed to Netlify in December, Netlify will donate $50 to some fantastic charities. New Relic is matching Netlify's pledge, along with a few other companies.
Together, these companies have pledged a total of $100,000. Instead of $50, the charities will now receive $500 per project deployed!
Getting started with Netlify
I am a major culprit of registering domain names for projects that I don’t complete or even start in some cases. For example, I have one domain which I've renewed every year since 2004. It’s supposed to be a promotional website for a book that I have not even begun to write! So, when I heard about Dusty Domains, I thought this would be the ideal opportunity to finally finish one of my projects and learn more about deploying to Netlify in the process.
I am already familiar with Git and different CI/CD pipelines, so making my first deployment on Netlify was reasonably straightforward. Their documentation is good, they have step-by-step tutorials on their blog, and they even have a selection of templates to help you get a jump start.
But, because Netlify is a serverless platform, adding instrumentation to the build and deployment process is more complex than usual. I wrote about serverless monitoring in Monitoring your AWS Lambda functions inside and out. With AWS Lambda, installation is much easier thanks to serverless-newrelic-lambda-layers, a plugin for Serverless.com. Unfortunately, no such plugin existed for New Relic and Netlify. So, I created one.
The New Relic Netlify plugin
I wanted the plugin to be highly configurable but with sensible defaults so that it takes as little effort as possible to begin using it with Netlify.
To install the plugin, first add it to your application’s
npm install -D @aaronbassett/newrelic-netlify-plugin
Then add the plugin to your
[[plugins]] package = "@aaronbassett/newrelic-netlify-plugin"
You can also set a few configuration values within your
netlify.toml, or you can add them later as environment variables. Here is an example configuration:
[[plugins]] package = "@aaronbassett/newrelic-netlify-plugin" [plugins.inputs] failBuildOnPluginError = false setDeploymentMarkers = true setDeploymentMarkersForPreviews = true newrelicAppId = "123456789" newrelicApiKey = "1234567890QWERTYUIOP" recordEventsForPreviews = true newrelicAccountId = "123456" newrelicLicenseKey = "12345678901234567890" enableBrowserMonitoring = true enableBrowserMonitoringForPreviews = true newrelicBrowserLicenseKey = "ABCD-0987654321" [plugins.inputs.skipEvent] onPreBuild = true onPostBuild = true onEnd = true
My example has these steps:
- Install the plugin
- Ensure that the build/deployment will continue if the plugin has an error (such as an invalid New Relic API key. This way, your deployments won’t be blocked if you can’t access the New Relic APIs.
- Enable both deployment marking and deployment marking for deploy previews.
- Set the New Relic App ID and API key, which are required to create deployment markers.
- Enable custom event recording for deploy previews. There is no setting to enable/disable event tracking like there is for deployment markers (
setDeploymentMarkers). Instead, you can disable individual events, as we’ll see later in the
- Set a New Relic Account ID and ingest license key, which are required to create custom events.
- Enable browser monitoring as well as browser monitoring for deploy previews. This automatically injects the New Relic Browser Monitor into any HTML files within my publish directory.
- Set a New Relic browser license key, which New Relic’s Browser Monitor requires.
- Configure the plugin to skip the
onEndevents in the
[plugins.inputs.skipEvent]section. This means no custom event will be recorded for these Netlify build events. However, recording will still be enabled for the
onErrorevents so I can track when a build starts and whether it succeeds or fails.
This is a detailed example and most of the time, you won't need to customize everything. All you need to add is your New Relic IDs and keys. You can leave the rest of the settings on the defaults. Here’s an example:
[[plugins]] package = "@aaronbassett/newrelic-netlify-plugin" [plugins.inputs] newrelicAppId = "123456789" newrelicApiKey = "1234567890QWERTYUIOP" newrelicAccountId = "123456" newrelicLicenseKey = "12345678901234567890"
A complete list of the available configuration options and their default values is available in the plugin README.
After you add the plugin to
netlify.toml, you are ready to deploy to Netlify.
Viewing plugin actions in Netlify
After a successful deployment, the plugin will add an entry to the deploy summary:
This entry gives you a summary of what the plugin did along with any relevant UUIDs. Let's look at the different types of actions it can perform.
Creating deployment markers
See the docs to learn more about recording and monitoring deployments.
Creating deployment markers for each Netlify deployment makes it easier to correlate changes in your application's performance to an individual deployment. Each deployment marker must have a unique identifier called a revision.
By default, the plugin constructs the revision string in this following way:
<message>-<context>-<commit ref>-<deploy id>-<build id>
<message>is the last commit message, truncated to 25 characters. This value isn't always available to the plugin at build time, and could be blank.
<context>is the Netlify deployment context.
<commit ref>is the first 7 characters of the last commit SHA.
<deploy id>is the last 6 digits of the Netlify
<build id>is the last 6 digits of the Netlify
You can also specify your own structure for the revision string by setting
deployMarkerRevisionTemplate to an EJS template. When rendered, this template can access inputs, constants, git, netlifyConfig, packageJson, and the local environment via
process.env. The plugin
manifest.yml contains the default template for reference.
Recording custom events
During the build-deploy lifecycle, Netlify may trigger several events. A complete list is available in the Netlify Plug into events documentation.
The plugin can record each of these as custom events within New Relic One.
The plugin sends the same attributes for each custom event:
eventType: Event name combines
Netlify:with the event types such as
onError. An example is
commitRef: Last commit SHA
branch: Git branch name
context: Netlify deployment context
repositoryUrl: Git repository URL
I would really appreciate any feedback on attributes that you’d find helpful with custom events. Please open an issue with any suggestions.
See the docs to get an introduction to browser monitoring.
The plugin will look for any files with a
.html extension in your publish directory and any sub-directories. For each matching file, it will:
1. Ensure the file contains a
3. If the file contains any X-UA or charset meta tags, the plugin will insert the snippet after the last X-UA or charset meta tag.
4. If there are no X-UA or charset meta tags, the plugin will attempt to inject the snippet at the beginning of the document
In the deployment summary, the plugin lists all files containing the Browser Monitor in the Pages injected section. If the plugin couldn't install the Browser Monitor in a particular HTML file, it is listed in the Pages not injected section. If a file appears in the Pages not injected section, but you think the Browser Monitor should have been installed on that page, make sure you have not omitted the
Viewing plugin errors in Netlify
The plugin contains robust error checking, which can help you diagnose any configuration issues. By default, the plugin will fail the entire build if it encounters an error, and your application won’t be deployed. If you don’t want plugin errors to block builds, set
false. If you do this, you may have deployments that don't have corresponding deployment markers in New Relic One.
Here are some common plugin errors you might encounter:
- Missing New Relic ID or key. Different plugin capabilities require different New Relic values. Ensure you have the required values set in your environment or
netlify.tomlfile. Examples include:
Error: Browser monitoring is enabled, but NEWRELIC_ACCOUNT_ID is not set
Error: Recording onBuild event enabled, but NEWRELIC_ACCOUNT_ID is not set
Error: Recording onError event enabled, but NEWRELIC_INGEST_LICENSE_KEY is not set
- The New Relic API has returned an error response. Check the HTTP status and error message returned to identify the issue. Examples include:
Error: Could not create deployment marker "production-4e219c4-b98f97-6a7fcd" New Relic API responded with 401 Invalid API key. Contact your account admin to generate a new one, or see our API docs.
Error: Could not create deployment marker "production-4e219c4-b98f97-6a7fcd" New Relic API responded with 404 Invalid API key. We didn't find an application with the given ID.
- Other unexplained errors take the form of "Could not <action which could not be performed>". These normally indicate that the plugin can’t reach the New Relic servers. Possible causes include a network issue or timeout. Check the deploy log for the exception details. Examples include:
Error: Could not record onSuccess event
Error: Could not create deployment marker "production-4e219c4-b98f97-6a7fcd"
My Dusty Domains deployment
Unfortunately, I became a little distracted with creating the New Relic Netlify Plugin and haven't yet dusted off any of my domains. However, my bikeshedding in this case was very productive! I still have time to submit my application and earn another $500 for the chosen charities. Keep your fingers crossed for me, and follow me on Twitter to see if I can submit before the deadline.
The New Relic Netlify Plugin is public. You can install it today, but keep in mind that it is an unofficial plugin and still very early in its development. If you find any issues or have suggestions for improvements, please open an issue or PR. To monitor your applications with New Relic, sign up for a forever free account.
You can find more information on installing Netlify plugins or creating your own plugins in Netlify’s docs.
And if you do have a domain that you’re not using, why not create an application for Dusty Domains yourself? It is for a good cause, after all!
The views expressed on this blog are those of the author and do not necessarily reflect the views of New Relic. Any solutions offered by the author are environment-specific and not part of the commercial solutions or support offered by New Relic. Please join us exclusively at the Explorers Hub (discuss.newrelic.com) for questions and support related to this blog post. This blog may contain links to content on third-party sites. By providing such links, New Relic does not adopt, guarantee, approve or endorse the information, views or products available on such sites.