Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Node.js Added documentation and cross-link for Azure site extension #18896

Merged
Merged
Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
fd3f776
docs: Added documentation and cross-link for Azure site extension
mrickard Oct 8, 2024
1ad9c59
docs: Corrected partial edit
mrickard Oct 9, 2024
41fd624
docs: Updated Node Docker instructions
mrickard Oct 10, 2024
4949bca
docs: Deleted site extension doc; consolidated with existing Azure doc
mrickard Oct 11, 2024
30f3288
docs: Updated cross-link for Azure Site Extension
mrickard Oct 11, 2024
c562615
chore: Changed heading size and added anchor
mrickard Oct 11, 2024
9902a20
Update src/content/docs/apm/agents/nodejs-agent/getting-started/monit…
mrickard Oct 14, 2024
73cedd2
Update src/content/docs/apm/agents/nodejs-agent/hosting-services/node…
mrickard Oct 14, 2024
ac6d70b
Update src/content/docs/apm/agents/nodejs-agent/hosting-services/node…
mrickard Oct 14, 2024
3afd5b9
Update src/content/docs/apm/agents/nodejs-agent/hosting-services/node…
mrickard Oct 14, 2024
ad74781
Update src/content/docs/apm/agents/nodejs-agent/hosting-services/node…
mrickard Oct 14, 2024
d528a3a
Update src/content/docs/apm/agents/nodejs-agent/hosting-services/node…
mrickard Oct 14, 2024
070a59e
Update src/content/docs/apm/agents/nodejs-agent/hosting-services/node…
mrickard Oct 14, 2024
e49f708
Update src/content/docs/apm/agents/nodejs-agent/installation-configur…
mrickard Oct 14, 2024
6abbaa4
Update src/content/docs/apm/agents/nodejs-agent/installation-configur…
mrickard Oct 14, 2024
0234668
Update src/content/docs/apm/agents/nodejs-agent/installation-configur…
mrickard Oct 14, 2024
c477376
Update src/content/docs/apm/agents/nodejs-agent/installation-configur…
mrickard Oct 14, 2024
00dd6d7
Update src/content/docs/apm/agents/nodejs-agent/installation-configur…
mrickard Oct 14, 2024
15a8d82
Update src/content/docs/apm/agents/nodejs-agent/installation-configur…
mrickard Oct 14, 2024
59fbc36
chore: Restored separate Azure install doc, added to nav, incorporate…
mrickard Oct 14, 2024
5d93c49
Update src/content/docs/apm/agents/nodejs-agent/getting-started/monit…
mrickard Oct 14, 2024
0033ac1
Update src/content/docs/apm/agents/nodejs-agent/hosting-services/node…
mrickard Oct 14, 2024
4387d9e
Update src/content/docs/apm/agents/nodejs-agent/hosting-services/node…
mrickard Oct 14, 2024
d753131
Update src/content/docs/apm/agents/nodejs-agent/hosting-services/node…
mrickard Oct 14, 2024
2c919bd
Update src/content/docs/apm/agents/nodejs-agent/installation-configur…
mrickard Oct 14, 2024
b268fa3
Update src/content/docs/apm/agents/nodejs-agent/installation-configur…
mrickard Oct 14, 2024
cbbbc6b
Update src/content/docs/apm/agents/nodejs-agent/installation-configur…
mrickard Oct 14, 2024
ce7bbfb
chore: Edited Node Docker instructions
mrickard Oct 14, 2024
6cb12f8
Update src/content/docs/apm/agents/nodejs-agent/installation-configur…
mrickard Oct 14, 2024
4265e78
feat(node): some indentation fixes
akristen Oct 14, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,14 @@ We have a few paths to install the Node.js agent, depending on what you're monit

If you have a preference for manual installation via the command line, we currently have the option for [Legacy instrumentation for Lambda monitoring](/docs/serverless-function-monitoring/aws-lambda-monitoring/enable-lambda-monitoring/enable-serverless-monitoring-aws-lambda-legacy/#node).
</Collapser>

<Collapser
id="azure"
title="Azure web app on Windows"
>
If you'd like to instrument an Azure Web App (provided that it's on Windows and deployed as code), you can easily install and configure the New Relic Node Agent with the [Azure Node Agent Site Extension](/docs/agents/nodejs-agent/hosting-services/nodejs-agent-microsoft-azure).
mrickard marked this conversation as resolved.
Show resolved Hide resolved

</Collapser>
</CollapserGroup>

## What's next? [#next]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,59 @@ tags:
- Agents
- Nodejs agent
- Hosting services
- Azure
- Azure Site Extension
metaDescription: How to install APM for Node.js on Microsoft Azure Web Apps.
redirects:
- /docs/agents/nodejs-agent/hosting-services/nodejs-agent-microsoft-azure
- /docs/agents/nodejs-agent/installation-configuration/install-nodejs-agent-azure-site-extension
- /docs/nodejs/nodejs-agent-on-microsoft-azure
translate:
- jp
- kr
freshnessValidatedDate: never
---
## Easy Install with the New Relic Azure Site Extension for Node [#site-extension-install]

You can install the Node.js agent onto your Azure-managed web apps with the New Relic Azure Site Extension for Node. This doc walks you through compatibility, installation, and configuration to get your Azure web app data into New Relic.

## Compatibility and requirements [#compatibility-requirements]

Azure Site Extensions are only available for Windows-based App Service apps that are deployed as code. For applications running on Windows 32, full Code Level Metrics support (file path, line, column) is not available. Profiling falls back to function name only.

## Install the Node.js agent with Azure Site Extension

To install the New Relic Azure Site Extension, add the `NewRelic.Azure.WebSites.Extension.NodeAgent` site extension from the Azure home page. Follow these steps:

1. From the Azure Home page, click the App Services tile, then select the target application in the displayed list.
2. Scroll down to <DNT>**Extensions**</DNT> in the options listed on the left under the <DNT>**Development Tools**</DNT> category.
3. Click on <DNT>**+ Add**</DNT> at the top of the page to toggle the extension drop down, then select <DNT>**New Relic Node Agent**</DNT>. Check the box for accepting the legal terms
4. Click <DNT>**Add**</DNT> on the bottom of the page to start installing the extension.

Once installed, the extension creates the following artifacts:

- Folder: `C:\home\SiteExtensions\NewRelic.Azure.Websites.Extension.NodeAgent`
mrickard marked this conversation as resolved.
Show resolved Hide resolved
- XDT: `applicationHost.xdt` that will add the necessary `NODE_OPTIONS` environment variable on application startup
mrickard marked this conversation as resolved.
Show resolved Hide resolved
- The New Relic Node agent and dependencies will be installed into `C:\home\site\wwwroot\node_modules`
mrickard marked this conversation as resolved.
Show resolved Hide resolved

If the New Relic agent has been installed successfully and logging has been enabled, the agent will append its logs to a file at `C:\home\site\wwwroot\newrelic_agent.log`. If the extension fails to install, a log file is created at `C:\home\SiteExtensions\NewRelic.Azure.Websites.Extension.NodeAgent\install.log`.
mrickard marked this conversation as resolved.
Show resolved Hide resolved

## Configure the Node.js agent [#configure-agent]

The New Relic Node agent is configured with the `newrelic.js` file, or via environment variables. [See our documentation for more detailed configuration](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration/).
mrickard marked this conversation as resolved.
Show resolved Hide resolved

Once the site extension is installed, you'll need to manually enter one configuration item before restarting your application.
Copy link
Contributor

@akristen akristen Oct 11, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lines 48-50 is hard to parse. Typically we want to reserve bulleted lists with child (and grand child lists) to follow this kind of pattern:

Sentence goes here:

  • Child item 1
  • Child item 2
    • gchild item 1
    • gchild item 2

Rather than a bunch of single bullets after single bullets. I think we can both make it readable and remove the lists so it looks something like this:

Once the site extension is installed, you'll need to manually enter one configuration item before restarting your application. From the Azure portal on the options listed on the left, find Settings and scroll down to Environment variables. Add the NEW_RELIC_LICENSE_KEY variable with your license key value.

The Node agent automatically adds the NODE_OPTIONS environment variable with a value of -r newrelic. This key-value pair starts the agent. Any previously defined NODE_OPTIONS will be removed and reset with -r newrelic.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I definitely prefer the rewrite, though there's a slight tweak for accuracy that I'll add in the next commit.

- On the options listed on the left, scroll down to "Environment variables" located under the "Settings" category and add the following:
- `NEW_RELIC_LICENSE_KEY` - Your New Relic license key value

The Node agent automatically adds the `NODE_OPTIONS` environment variable with a value of `-r newrelic` which starts the agent.
- Note: Any previously defined `NODE_OPTIONS` will be removed and reset with `-r newrelic`.

<Callout variant="important">
mrickard marked this conversation as resolved.
Show resolved Hide resolved
We recommend installing or removing this Azure site extension while your web application is stopped.
</Callout>

## Manual Installation
mrickard marked this conversation as resolved.
Show resolved Hide resolved

Learn about special considerations for using Microsoft Azure Web Apps as a hosting service with New Relic's Node.js agent.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,12 @@ With just a few additions your existing Dockerfile can be used with our Node.js

Install a specific version, or use any of the other options provided by the [`package.json` format](https://docs.npmjs.com/files/package.json#dependencies). Check [the Node.js agent release notes](/docs/release-notes/agent-release-notes/nodejs-release-notes) for information about past agent versions.
mrickard marked this conversation as resolved.
Show resolved Hide resolved

2. Depending on how your container is setup, you can edit the `ENTRYPOINT` to include `newrelic` module first with Node.js `-r`/`--require` flag by running `node -r newrelic YOUR_PROGRAM.js`. If you can't control how your program runs, you can load the `newrelic` module before any other module in your program by adding `require('newrelic')`.
2. Depending on how your container is set up, you can edit the `ENTRYPOINT` to include `newrelic` module first with Node.js `-r`/`--require` flag by running ```node -r newrelic YOUR_PROGRAM.js```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we provide an example console command they can run to do all of this so it's one code block instead of several snippets? It might read something like:

Depending on your container set-up, you can adjust where the Node.js flag appears. For example:

node -r newrelic YOUR_PROGRAM.js

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll rewrite this to note why you'd want to add the -r flag: it's to inject the agent before your application runs. Otherwise, you need to include the agent at the top of your entrypoint file, which is something people often overlook or have trouble with. The agent needs to be loaded before other dependencies run.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Step 2 with all the tips and notes can be adjusted with some tech writer copy edits. Is this step directing the agent to initialize when the container with app image spins up? I might rework it to read something like this:

  1. Depending on your container set-up, you can adjust where the Node.js flag appears. For example, you can initialize the agent when the container spins up by including the New Relic module ahead of your app code:
node -r newrelic YOUR_PROGRAM.js
ENTRYPOINT ['node', '-r', 'newrelic', 'YOUR_PROGRAM.js']

If you can't control how your program runs, load the New Relic module before any other modules within your program:

some example code or whatever
something something require('newrelic')

If an npm script like npm start runs your program, then modify this script by running this instead:

npm pkg set scripts.start="node -r newrelic your-program.js"

Keep in mind that if your Node.js agent is older than v7.2.0, you will need to add the environment variable NEW_RELIC_NO_CONFIG_FILE=true to your Dockerfile so the agent can run without a configuration file. More information on our configuration settings and order of precedence can be found here.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the two entry point examples, we can make those child options for the examples

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have a version I think is better for these; I'll be pushing that momentarily.


or ```ENTRYPOINT ['node', '-r', 'newrelic', 'YOUR_PROGRAM.js']```

If you can't control how your program runs, you can load the `newrelic` module before any other module in your program by adding `require('newrelic')`.
mrickard marked this conversation as resolved.
Show resolved Hide resolved


<Callout variant="tip">
Copy link
Contributor

@akristen akristen Oct 11, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment as before. we have 5 callouts in this doc. Let's choose one to prioritize and nest relevant information within procedure

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've also noticed that the first callout in this doc mixed up variant and tip. I'm in favor of one "tip," one "caution," and one "important."

If you have an npm script to run your program such as `npm start`, you can programmatically modify this script by running `npm pkg set scripts.start="node -r newrelic your-program.js"`.
mrickard marked this conversation as resolved.
Show resolved Hide resolved
Expand Down Expand Up @@ -57,19 +62,25 @@ With just a few additions your existing Dockerfile can be used with our Node.js
Don't include your license key in your Dockerfile or Docker image. For more information, see [our documentation on license key security](/docs/accounts/install-new-relic/account-setup/license-key#license-key-security).
mrickard marked this conversation as resolved.
Show resolved Hide resolved
</Callout>

In addition to setting your application name or license key, you can set [other configuration options](/docs/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration) by starting your container with the `-e` option. For example, to enable [distributed tracing](/docs/understand-dependencies/distributed-tracing/get-started/introduction-distributed-tracing), use:
<Callout variant="tip">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be changed to regular text, but we should keep the caution call out... I'm wondering if that needs to be bumped up sooner?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm moving it earlier; let me know what you think.

If your Node.js agent is older than [v8.3.0](/docs/release-notes/agent-release-notes/nodejs-release-notes/node-agent-8-3-0) and you want to use [distributed tracing](/docs/understand-dependencies/distributed-tracing/get-started/introduction-distributed-tracing), you'll need to enable it by setting the environment variable `NEW_RELIC_DISTRIBUTED_TRACING_ENABLED` to `true`.
mrickard marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These call outs about versioning makes me believe there should be a compatibility section with all of this content grouped together AHEAD of procedure. Having it dispersed throughout the doc can be confusing and break flow, and then customers can't go to one section for reference about versioning. Can we make these version callouts h2s with everything lumped together?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've moved these a bit--let me know how the next commit looks.

</Callout>


In addition to setting your application name or license key, you can set [other configuration options](/docs/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration) by starting your container with the `-e` option. For example, to enable a feature flag, use:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In addition to setting your application name or license key, you can set [other configuration options](/docs/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration) by starting your container with the `-e` option. For example, to enable a feature flag, use:
In addition to setting your application name or license key, you can set [other configuration options](/docs/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration) by starting your container with the `-e` option. You can enable a feature flag by replacing `FF` in the following snippet and running the following:

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've made a modified version of this to be more explicit about the naming: I could see some users just copying and pasting the NEW_RELIC_FF_ENABLED, though there's no guarantee that someone won't do that with the version I've just pushed.


```bash
docker run -e NEW_RELIC_LICENSE_KEY=YOUR_LICENSE_KEY \
-e NEW_RELIC_APP_NAME="YOUR_APP_NAME" \
-e NEW_RELIC_DISTRIBUTED_TRACING_ENABLED=true \
-e NEW_RELIC_FF_ENABLED=true \
YOUR_IMAGE_NAME:latest
```
(You'll replace `FF` with the name of the feature flag you want to enable.)
mrickard marked this conversation as resolved.
Show resolved Hide resolved

You can also set configuration options in your Dockerfile using `ENV` directives:

```dockerfile
ENV NEW_RELIC_DISTRIBUTED_TRACING_ENABLED=true \
ENV NEW_RELIC_FF_ENABLED=true \
NEW_RELIC_LOG=stdout
# etc.
```
Loading