newrelic/node-newrelic-mysql

New Relic MySQL instrumentation for the Node Agent

This is repository is no longer maintained. This functionality was merged into the New Relic Node agent with newrelic/node-newrelic#1136.

New Relic MySQL instrumentation

New Relic's offical MySQL instrumentation for use with the New Relic Node.js agent.

Installation and Getting Started

This module is a dependency of the agent and is installed with it by running:

npm install newrelic

Alternatively, it can be installed and loaded independently based on specific versioning needs:

npm install @newrelic/mysql

// index.js
require('@newrelic/mysql')

Supported modules

• mysql
• mysql2

For more information, please see the agent installation guide and the agent compatibility and requirements.

Our API and developer documentation for writing instrumentation will be of help. We particularly recommend the tutorials and various "shim" API documentation.

Testing

The module includes a suite of functional tests which should be used to verify that your changes don't break existing functionality.

These tests rely on a Docker container being setup via scripts in the Node.js agent. This container can be setup by running npm run services in the main agent repo.

All tests are stored in tests/ and are written using Tap with the extension .tap.js.

To run the full suite, run: npm test.

Support

Should you need assistance with New Relic products, you are in good hands with several support channels.

Support Channels

• New Relic Documentation: Comprehensive guidance for using our platform
• New Relic Community: The best place to engage in troubleshooting questions
• New Relic Developer: Resources for building a custom observability applications
• New Relic University: A range of online training for New Relic users of every level

Privacy

At New Relic we take your privacy and the security of your information seriously, and are committed to protecting your information. We must emphasize the importance of not sharing personal data in public forums, and ask all users to scrub logs and diagnostic information for sensitive information, whether personal, proprietary, or otherwise.

We define "Personal Data" as any information relating to an identified or identifiable individual, including, for example, your name, phone number, post code or zip code, Device ID, IP address and email address.

For more information, review New Relic’s General Data Privacy Notice.

Roadmap

See our roadmap, to learn more about our product vision, understand our plans, and provide us valuable feedback. Remove this section if it’s not needed.

Contribute

We encourage your contributions to improve New Relic MySQL instrumentation! Keep in mind when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project.

If you have any questions, or to execute our corporate CLA, required if your contribution is on behalf of a company, please drop us an email at [email protected].

A note about vulnerabilities

As noted in our security policy, New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals.

If you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through HackerOne.

If you would like to contribute to this project, please review these guidelines.

To all contributors,we thank you! Without your contribution, this project would not be what it is today. We also host a community project page dedicated to the New Relic MySql Instrumentation package.

License

New Relic MySQL instrumentation is licensed under the Apache 2.0 License.

New Relic MySQL instrumentation also uses source code from third-party libraries. You can find full details on which libraries are used and the terms under which they are licensed in the third-party notices document.

node-newrelic-mysql's Issues

Bump node-test-utilities to ^4.0.0

mysql: add node 20

Is your feature request related to a problem? Please describe.

• Add Node 20 to CI and drop 14

Add standard code of conduct

Can grab from NR open source repo template

Minimal code cleanup

We are already in decent shape but do a pass for general things outlined in the Engineering Plan.

Helpful regex (ripgrep):

rg --pcre2 '(?<!SELECT)(// |^ *\*(?!/))(?! Copyright|.*Apache|.*eslint)'

Make Third Party Notices updateable via standard CLI tool

• Make updateable by the standard CLI tool to make easier and help prevent misses.
• Ensure current notices up to date. (expect at least the agent to update). We may want to set the minimum to the latest as we converge these on open source.
• Add required footer to third party notices. See bottom SuperAgent as an example: https://github.com/newrelic/node-newrelic-superagent/blob/open-source-main/THIRD_PARTY_NOTICES.md

https://github.com/newrelic/newrelic-oss-cli#third-party-notice-generation-for-npm-based-projects

-----

Portions copyright Node.js contributors. Depending on your existing libraries and package management settings,
your systems may call externally maintained libraries in addition to those listed above.
See [here](https://nodejs.org/en/docs/meta/topics/dependencies/) and [here](https://github.com/nodejs/node/blob/v4.3.1/LICENSE)
for additional details regarding externally maintained libraries and certain related licenses and notices.”

'execute' is not supported in this standalone mysql module

It looks like when 'execute' support was added in 2019 to the main agent mysql instrumentation, this module was not updated and we didn't have an issue to capture.

As such, a couple recent attempts to use mysql2/promise by customers and internal folks have had issues because they are using this function.

Whether we keep this module or merge back into the main agent, we should ensure this functionality works with mysql2/promise usages.

Here's one instance: #47 (comment)

Main agent reference:
https://github.com/newrelic/node-newrelic/blob/main/lib/instrumentation/mysql.js#L134-L136
newrelic/node-newrelic@d64f7de

Effort: Small

Convert CI to GitHub Actions

• Users can run unit tests at a minimum.

Would aim for all tests functioning for external PR's (forked repos) with these efforts.

Add repo to opensource.newrelic.com

Basically just resurrecting project file from: newrelic/opensource-website#468.

NOTE: defaultBranch field is now required. See: newrelic/opensource-website#523

@newrelic/mysql: Update README to mark this package as EOLd

This package was experimental. All the functionality was folded into the agent in newrelic/node-newrelic#1136. We don't have any plans to add any functionality in this package. In fact it's causing us more headaches with snyk, and random CI updates.

A/C:

• Update the README to call that this is EOLd.
• Remove snyk, dependabot checks.
• Remove subscriptions in slack in #node-agent-dev

Update issue templates to current standards

See templates and decisions made in prior repos

Update Readme

Summary

• Should conform to new open source template.
  • See the internal repo template project.
• Clear instructions for development and "building".
• For Explorer's Hub... would point to main agent area... don't know what that is anymore. Perhaps via tags? Check with Corey
• Update any out of date information

Depending on the amount of content, may want to run by the docs team. They had a bit of consistency and branding changes to the main agent readme.

Automate third-party notice updates

• Automate third-party updates on commit.
• Add package.json script for manually running.
• Update existing notices.

The setup for the node-agent should be used as a guide:

• newrelic/node-newrelic#832
• newrelic/node-newrelic#837

Add copyright to all source files

Every source file in the repository should contain the copyright block heading on top:

/*
* Copyright 2020 New Relic Corporation. All rights reserved.
* SPDX-License-Identifier: Apache-2.0
*/

This includes bash scripts (slightly different commenting style) and code examples. Does not include copy-paste templates.

NOTE: we want the Apache-2.0 license to land first so these are consistent and that license is the current active for the commit(s) applying these changes.

---

Useful Script

• Does not update non-JS files.
• May break when there’s a code directive that needs to be at the top.
• May need additional modifications for a particular repository.
• Run git ls-files | grep '\.js$' | grep -Ev '(.eslintrc|^newrelic)' to see list of files

tmp=$(mktemp)   # Create a temporary file
trap "rm -f $tmp; exit 1" 0 1 2 3 13 15

header="/*
 * Copyright 2020 New Relic Corporation. All rights reserved.
 * SPDX-License-Identifier: Apache-2.0
 */
"

for file in $(git ls-files | grep '\.js$' | grep -Ev '(.eslintrc|^newrelic)')
do
    {
    echo -e "$header"
    cat $file
    } > $tmp
    mv $tmp $file
    echo $file
done

rm -f $tmp
trap 0

Unable to install Mysql , Nginx , Java agent in our aws cloud environment

1. As we configured our MySql RDS by using admin user , we're unable to deploy the agent since its asking for the Root credentials while deploying it ...
   We have tried with creating the newrelic user by using the comment in new relic site , even though it asking for the same root credentials .. Please look in to this and advise at high priority ...

2. Also we're facing the issue in deploying the nginx agent , we stuck in this step and no idea how to proceed further to fix it while installing the ngnix agent .
   NGINX status URL (default: http://127.0.0.1/status): http://127.0.0.1:8080/status
   NGINX HTTP status page should be set up with a locally accessible URL in the conf server block.
   See https://docs.newrelic.com/docs/integrations/host-integrations/host-integrations-list/nginx-monitoring-integration#config for more info.
   ==> Installing nginx-open-source-integration...failed.

One or more installations failed. Check the install log for more details: /home/ubuntu/.newrelic/newrelic-cli.log
New Relic installation complete!
Your data is available at https://one.newrelic.com/launcher/nr1-core.explorer?platform[filters]=&platform[accountId]=3271104
FATAL We encountered an error during the installation: exit status 2: See https://docs.newrelic.com/docs/integrations/host-integrations/host-integrations-list/nginx-monitoring-integration#config for more info.. If this problem persists please visit the documentation and support page for additional help here: https://one.newrelic.com/-/06vjAeZLKjP

3. While installing the Java agent we're facing the below error but java installed and configured in our environment in running status ....
   INFO Validating connectivity to the New Relic platform...
   ✅ Checking for data in New Relic (this may take a few minutes)...success.

FATAL We encountered an error during the installation: we couldn’t install the Java Agent Installer. Make sure Java is installed and running on this host and rerun the newrelic-cli command. If this problem persists please visit the documentation and support page for additional help here: https://one.newrelic.com/-/06vjAeZLKjP

Ensure PR template up to expectations/standard

Ensure PR template up to expectations/standards.

We've been doing a bit of our own thing, so far. See other repos.

Update tap to version 15

Attempt to update tap to version 15.0.9 caused test failures because of extensive use of done in before/after test setups. done is called throughout the setup process. We suggest converting the setup to something more promise based and compatible with the tap setup and get rid of the async usage.

Here's an example of the done being used as a callback in setup:
https://github.com/newrelic/node-newrelic-mysql/blob/main/tests/versioned/common/setup.js#L20-L42

Add Node 14 support / Drop Node 8

Is your feature request related to a problem? Please describe.

This experimental repo needs to be brought up to current support standards.

Update license to Apache 2.0

• Update license file
• Update package.json to be standard
• Other?

mysql2 promise support

Using mysql2 with promises is not instrumented and APM does not track SQL queries.

For instance, using knex or objectionjs causes the agent to simply not report any SQL queries.

This was asked last year, but as this is the official repo I thought creating the issue here would be better.
https://discuss.newrelic.com/t/feature-idea-any-plans-to-instrument-mysql2-promise-in-the-nodejs-agent/72101

Switch to 'main' as default branch

We've settled on main as the new default branch name.

This will involve creating and migrating to the new branch before deleting the prior. We'll also want to ensure we change the base of any existing PR's etc.

Hanselman has some helpful instructions on the blog: https://www.hanselman.com/blog/EasilyRenameYourGitDefaultBranchFromMasterToMain.aspx. I'm sure there are other useful resources out there as well.

• Change the base of all open PRs (do this first or risk auto-closing when change default)
• Change default branch in repo settings
• Copy master branch protection rules to main
• Setup Snyk to use main
• Edit any release documents to reference main instead of master (sometimes recommend doing via separate PR to exercise snyk/etc on new branch).
• Delete master branch once all good.

Update contributing guidelines

• Update to current template.
• Review/modify existing content.
• Add language similar to: "only accept PR's for version X or greater" with X being the version you OSS." See main agent repo: https://github.com/newrelic/node-newrelic/blob/main/CONTRIBUTING.md#pull-requests