How to monitor your Netlify Dusty Domain deployment

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 devDependencies:

Then add the plugin to your netlify.toml file:

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:

My example has these steps:

1. Install the plugin
2. 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.
3. Enable both deployment marking and deployment marking for deploy previews.
4. Set the New Relic App ID and API key, which are required to create deployment markers.
5. 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 plugins.inputs.skipEvent section.
6. Set a New Relic Account ID and ingest license key, which are required to create custom events.
7. 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.
8. Set a New Relic browser license key, which New Relic’s Browser Monitor requires.
9. Configure the plugin to skip the onPreBuild, onPostBuild, and onEnd events 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 onBuild, onSuccess, and onError events 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:

A complete list of the available configuration options and their default values is available in the plugin README. 

After you add the plugin to devDependencies and 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 DEPLOY_ID.
• <build id> is the last 6 digits of the Netlify BUILD_ID.

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 onBuild, onSuccess, and onError. An example is Netlify:onPostBuild.
• siteId: Netlify SITE_ID
• siteName: Netlify SITE_NAME
• commitRef: Last commit SHA
• buildId: Netlify BUILD_ID
• deployId: Netlify DEPLOY_ID
• branch: Git branch name
• context: Netlify deployment context
• deployUrl: Netlify DEPLOY_URL
• repositoryUrl: Git repository URL
• netlifyBuildVersion: NETLIFY_BUILD_VERSION

I would really appreciate any feedback on attributes that you’d find helpful with custom events. Please open an issue with any suggestions.

Browser monitoring

See the docs to get an introduction to browser monitoring.

New Relic's APM agents can automatically add the Browser Monitor for you in many cases. However, if your Netlify site contains static HTML pages, the New Relic Netlify plugin can automatically inject the JavaScript snippet for you so you don’t have to manually add it yourself.

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 <body> tag. According to the HTML specification, body tags can be omitted under certain conditions, but this is a good smoke test to make sure the JavaScript snippet can be injected. If the test doesn't pass, the process can be aborted.

2. Check for a content-disposition meta tag that specifies the HTML file should be saved as a file. If so, the browser monitor isn’t injected because the file is meant to be downloaded, not rendered by the browser. After all the checks are complete, the Browser Monitor is added to the page. Next, the plugin determines where it should inject the JavaScript snippet.

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 <head>.

5. As a final option, if the document doesn't contain a head tag, the plugin will insert the JavaScript snippet before the opening <body> tag.

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 <body> tag.

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 failBuildOnPluginError to 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.toml file. Examples include:
  1. Error: Browser monitoring is enabled, but NEWRELIC_ACCOUNT_ID is not set
  2. Error: Recording onBuild event enabled, but NEWRELIC_ACCOUNT_ID is not set
  3. 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:
  1. 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.
  2. 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:
  1. Error: Could not record onSuccess event
  2. 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.