chore: clarify the latest major version of the instrumentation module for some instrumentations (#4837)

In docs, instrumentation, and tests, the major version of the target
module being instrumented was not specified. There should be no functional
change for any current releases of modules with this change. In other
words, any changes to actual instrumentations is capping the major version
supported at the *currently released* major version.

Closes: #4803

Author: trentm

.tav.yml

@@ -255,7 +255,9 @@ koa-router:
     commands: node test/instrumentation/modules/koa-router/new-name.test.js
 
 elasticsearch:
-  versions: '>=8.0.0'
+  versions:
+    mode: max-5
+    include: '>=8.0.0 <17'
   commands: node test/instrumentation/modules/elasticsearch.test.js
 
 # @elastic/elasticsearch
@@ -308,7 +310,7 @@ handlebars:
 pug:
   - versions: '0.1.0 || >2.0.0 <3.0.0'
     commands: node test/instrumentation/modules/pug.test.js
-  - versions: '>=3.0.0'
+  - versions: '>=3.0.0 <4'
     node: '>8'
     commands: node test/instrumentation/modules/pug.test.js
 
@@ -483,7 +485,7 @@ finalhandler:
     commands: node test/instrumentation/modules/finalhandler.test.js
 
 memcached:
-  versions: '>=2.2.0'
+  versions: '>=2.2.0 <3'
   commands: node test/instrumentation/modules/memcached.test.js
 
 aws-sdk:

docs/reference/supported-technologies.md

@@ -49,7 +49,7 @@ Though you can use Elastic APM [with any Node.js framework](/reference/custom-st
 | [AWS Lambda](/reference/lambda.md) | N/A |  |
 | [Azure Functions](/reference/azure-functions.md) | v3, v4 | [Node.js programming model v3 and v4](https://learn.microsoft.com/en-us/azure/azure-functions/functions-node-upgrade-v4) |
 | [Express](/reference/express.md) | >=4.0.0 <6.0.0 |  |
-| [Fastify](/reference/fastify.md) | >=2.0.0 | See also [Fastify’s own LTS documentation](https://www.fastify.io/docs/latest/Reference/LTS/) |
+| [Fastify](/reference/fastify.md) | >=2.0.0 <6 | See also [Fastify’s own LTS documentation](https://www.fastify.io/docs/latest/Reference/LTS/) |
 | [@hapi/hapi](/reference/hapi.md) | >=17.9.0 <22.0.0 |  |
 | [Koa](/reference/koa.md) via koa-router or @koa/router | >=5.2.0 <14.0.0 | Koa doesn’t have a built in router, so we can’t support Koa directly since we rely on router information for full support. We currently support the most popular Koa router called [koa-router](https://github.com/koajs/koa-router). |
 | [Restify](/reference/restify.md) | >=5.2.0 <12.0.0 |  |
@@ -88,21 +88,21 @@ The Node.js agent will automatically instrument the following modules to give yo
 | [@aws-sdk/client-sqs](https://www.npmjs.com/package/@aws-sdk/client-s3) | >=3.15.0 <4 | Will instrument SQS send/receive/delete messages |
 | [@aws-sdk/client-dynamodb](https://www.npmjs.com/package/@aws-sdk/client-dynamodb) | >=3.15.0 <4 | Will instrument all DynamoDB methods |
 | [cassandra-driver](https://www.npmjs.com/package/cassandra-driver) | >=3.0.0 <5 | Will instrument all queries |
-| [elasticsearch](https://www.npmjs.com/package/elasticsearch) | >=8.0.0 | Will instrument all queries |
-| [@elastic/elasticsearch](https://www.npmjs.com/package/@elastic/elasticsearch) | >=7.0.0 <9.0.0 | Will instrument all queries |
+| [elasticsearch](https://www.npmjs.com/package/elasticsearch) | >=8.0.0 <17 | Will instrument all queries |
+| [@elastic/elasticsearch](https://www.npmjs.com/package/@elastic/elasticsearch) | >=7.0.0 <10.0.0 | Will instrument all queries |
 | [graphql](https://www.npmjs.com/package/graphql) | >=0.7.0 <17 | Will instrument all queries |
-| [handlebars](https://www.npmjs.com/package/handlebars) | * | Will instrument compile and render calls |
-| [jade](https://www.npmjs.com/package/jade) | >=0.5.6 | Will instrument compile and render calls; Deprecated. No longer tested. Use pug. |
-| [pug](https://www.npmjs.com/package/pug) | >=0.1.0 | Will instrument compile and render calls |
+| [handlebars](https://www.npmjs.com/package/handlebars) | >=1 <5 | Will instrument compile and render calls |
+| [jade](https://www.npmjs.com/package/jade) | >=0.5.6 <2 | Will instrument compile and render calls; Deprecated. No longer tested. Use pug. |
+| [pug](https://www.npmjs.com/package/pug) | >=0.1.0 <4 | Will instrument compile and render calls |
 | [ioredis](https://www.npmjs.com/package/ioredis) | >=2.0.0 <6.0.0 | Will instrument all queries |
-| [memcached](https://www.npmjs.com/package/memcached) | >=2.2.0 | Will instrument all commands. |
+| [memcached](https://www.npmjs.com/package/memcached) | >=2.2.0 <3 | Will instrument all commands. |
 | [mongodb-core](https://www.npmjs.com/package/mongodb-core) | >=1.2.19 <4 | Will instrument all queries.A lot of higher level MongoDB modules use mongodb-core,so those should be supported as well. |
 | [mongodb](https://www.npmjs.com/package/mongodb) | >=2.0.0 <3.3.0 | Supported via mongodb-core |
 | [mongodb](https://www.npmjs.com/package/mongodb) | >=3.3.0 <7 | Will instrument all queries |
 | [mongojs](https://www.npmjs.com/package/mongojs) | >=1.0.0 <2.7.0 | Supported via mongodb-core |
 | [mongoose](https://www.npmjs.com/package/mongoose) | >=4.0.0 <5.7.0 | Supported via mongodb-core |
 | [mongoose](https://www.npmjs.com/package/mongoose) | >=5.7.0 <8 | Supported via mongodb |
-| [mysql](https://www.npmjs.com/package/mysql) | ^2.0.0 | Will instrument all queries |
+| [mysql](https://www.npmjs.com/package/mysql) | >=2.0.0 <3 | Will instrument all queries |
 | [mysql2](https://www.npmjs.com/package/mysql2) | >=1.0.0 <4.0.0 | Will instrument all queries |
 | [pg](https://www.npmjs.com/package/pg) | >=4.0.0 <9.0.0 | Will instrument all queries |
 | [redis](https://www.npmjs.com/package/redis) | >=2.0.0 <5.0.0 | Will instrument all queries |

lib/instrumentation/modules/elasticsearch.js

@@ -7,6 +7,7 @@
 'use strict';
 
 const { URL, URLSearchParams } = require('url');
+const semver = require('semver');
 
 var shimmer = require('../shimmer');
 var { getDBDestination } = require('../context');
@@ -63,9 +64,17 @@ function getTargetUrlFromTransportConfig(config) {
   return null;
 }
 
-module.exports = function (elasticsearch, agent, { enabled }) {
+module.exports = function (elasticsearch, agent, { version, enabled }) {
   if (!enabled) return elasticsearch;
 
+  if (!semver.satisfies(version, '>=8.0.0 <17')) {
+    agent.logger.debug(
+      'cannot instrument elasticsearch version %s, skipping elasticsearch instrumentation',
+      version,
+    );
+    return elasticsearch;
+  }
+
   const ins = agent._instrumentation;
   const elasticsearchCaptureBodyUrlsRegExp =
     agent._conf.elasticsearchCaptureBodyUrlsRegExp;

lib/instrumentation/modules/fastify.js

@@ -44,6 +44,13 @@ module.exports = function (
   if (!enabled) {
     return modExports;
   }
+  if (!semver.satisfies(version, '>=2.0.0 <6')) {
+    agent.logger.debug(
+      'cannot instrument fastify version %s, skipping fastify instrumentation',
+      version,
+    );
+    return modExports;
+  }
   if (isImportMod && !semver.satisfies(version, '>=3.5.0')) {
     // https://github.com/fastify/fastify/pull/2590
     agent.logger.debug(

lib/instrumentation/modules/handlebars.js

@@ -6,11 +6,22 @@
 
 'use strict';
 
+var semver = require('semver');
+
 var shimmer = require('../shimmer');
 var templateShared = require('../template-shared');
 
-module.exports = function (handlebars, agent, { enabled }) {
+module.exports = function (handlebars, agent, { version, enabled }) {
   if (!enabled) return handlebars;
+
+  if (!semver.satisfies(version, '>=1 <5')) {
+    agent.logger.debug(
+      'cannot instrument handlebars version %s, skipping handlebars instrumentation',
+      version,
+    );
+    return handlebars;
+  }
+
   agent.logger.debug('shimming handlebars.compile');
   shimmer.wrap(
     handlebars,

lib/instrumentation/modules/jade.js

@@ -6,11 +6,22 @@
 
 'use strict';
 
+var semver = require('semver');
+
 var shimmer = require('../shimmer');
 var templateShared = require('../template-shared');
 
-module.exports = function (jade, agent, { enabled }) {
+module.exports = function (jade, agent, { version, enabled }) {
   if (!enabled) return jade;
+
+  if (!semver.satisfies(version, '>=0.5.6 <2')) {
+    agent.logger.debug(
+      'cannot instrument jade version %s, skipping jade instrumentation',
+      version,
+    );
+    return jade;
+  }
+
   agent.logger.debug('shimming jade.compile');
   shimmer.wrap(jade, 'compile', templateShared.wrapCompile(agent, 'jade'));
 

lib/instrumentation/modules/memcached.js

@@ -15,9 +15,10 @@ module.exports = function (memcached, agent, { version, enabled }) {
   if (!enabled) {
     return memcached;
   }
-  if (!semver.satisfies(version, '>=2.2.0')) {
+
+  if (!semver.satisfies(version, '>=2.2.0 <3')) {
     agent.logger.debug(
-      'Memcached version %s not supported - aborting...',
+      'memcached version %s not supported, skipping memcached instrumentation',
       version,
     );
     return memcached;

lib/instrumentation/modules/pug.js

@@ -6,11 +6,22 @@
 
 'use strict';
 
+var semver = require('semver');
+
 var shimmer = require('../shimmer');
 var templateShared = require('../template-shared');
 
-module.exports = function (pug, agent, { enabled }) {
+module.exports = function (pug, agent, { version, enabled }) {
   if (!enabled) return pug;
+
+  if (!semver.satisfies(version, '>=0.1.0 <4')) {
+    agent.logger.debug(
+      'cannot instrument pug version %s, skipping pug instrumentation',
+      version,
+    );
+    return pug;
+  }
+
   agent.logger.debug('shimming pug.compile');
   shimmer.wrap(pug, 'compile', templateShared.wrapCompile(agent, 'pug'));