配置基于代理的 Node.js 监控

如果您的 Node.js 应用程序在 Kubernetes 和 Red Hat OpenShift 环境中运行，您可以按照以下步骤自动或手动安装 Instana Node.js 收集器：

• 自动安装收集器（推荐）：要自动安装收集器，请完成以下步骤：

  1. 安装 Instana AutoTrace 的 webhook。

     注意： 如果您计划使用 Instana Node.js SDK，请参阅 “将 API 与 AutoTrace webhook 结合使用 ”一节。

  2. 如果您的 Node.js 应用程序和 Instana 代理在 Kubernetes 集群中运行，请为受监控的应用程序配置网络访问权限。 如需了解更多信息，请参阅 Kubernetes network access。

• 手动安装收集器：如需手动安装收集器，请参阅 《手动安装 Node.js 收集器》。 仅在无法进行自动安装时才使用手动安装方法。

在只读系统中，针对预定义的 Node.js 版本编译的原生插件可能会与其他 Node.js 版本产生兼容性问题。 垃圾回收器无法解压预编译的二进制文件，导致某些原生模块无法加载。 因此，某些指标（例如垃圾回收数据和特定的事件循环统计数据）不会被收集。 不过，常规的追踪功能不受影响。 如需更多信息，请参阅 “故障排除 ”部分。

要在 Cloud Foundry 上安装 Instana Node.js 收集器，请选择以下选项之一：

• 自动收集器安装（推荐）：对于 Tile 1.177.0 及更高版本，请使用 Instana 构建包安装 Node.js 收集器，以在 Cloud Foundry 上自动配置 Node.js 应用程序。

• 手动安装收集器：如需手动安装收集器，请参阅 《手动安装 Node.js 收集器》。 仅在无法进行自动安装时才使用手动安装方法。

若要将 Instana Node.js 收集器包与 Apigee Microgateway （也称为 edgemicro ） 配合使用，请按照《使用 Instana Node.js 收集器监控 Apigee Microgateway》中的说明进行操作。

要使用 Instana Node.js 收集器来监控 Next.js 应用程序，请完成以下步骤：

1. 将收集器安装为全局或本地。
2. 使用加载标志来激活收集器。

要安装 Instana Node.js 收集器，请通过运行以下命令在您的应用程序中安装 npm@instana/collector 包：

npm install --save @instana/collector@latest

安装收集器后，请激活收集器以设置监控。 有关操作说明，请参阅 “激活 Node.js 收集器”。

作为另一种方法，您可以通过完成以下步骤，全局安装 Node.js 收集器：

1. 在目标系统上安装软件包 @instana/collector :

   • 如果您使用的是 npm ，请运行以下命令：

     npm install -g @instana/collector@latest
     

   • 如果使用 yarn ，请运行以下命令:

     yarn global add @instana/collector@latest
     

   如果要将收集器安装到容器化应用程序中，那么可以将上述语句添加到 Dockerfile。

2. 确定该软件包的安装位置。 位置取决于操作系统。 有关 npm 将已安装的软件包放置在何处的更多信息，请参阅 Node.js 文档中关于文件夹的部分。

3. 确保包 @instana/collector 及其所有依赖关系在目标系统上的已知位置可用，例如 /path/to/instana/node_modules/@instana/collector。

安装收集器后，请激活收集器以设置监控。 有关操作说明，请参阅 “激活 Node.js 收集器”。

要手动下载 Instana Node.js 收集器的预编译压缩包，请点击 Instana Node.js collector download。

要设置监控，请按照 《激活 Node.js 收集器》 中的说明激活收集器。

对于使用 CommonJS 模块的应用程序，请通过以下任一方法启用 Node.js 收集器：

• 请使用 --require load 标志进行激活。
• 请在应用程序的首个语句中引入并初始化 Node.js 收集器。

这些方法会在应用程序代码执行之前加载并初始化 Node.js 收集器。

如果您的应用程序使用 ECMAScript 以及作为依赖项安装的 @instana/collector 收集器，您可以通过使用 Node.js 加载标志来加载 Instana Node.js 收集器，从而激活该收集器。

如果应用程序使用 ECMAScript 模块，请在启动节点可执行文件时完成以下任一步骤。 设置 NODE_OPTIONS 或使用该 --import 参数会在应用程序代码执行之前初始化 Node.js 收集器。 有关 ECMAScript 模块的更多信息，请参阅 Node.js 上的官方文档。

• 在开始 Node.js 激活流程之前，请设置该 NODE_OPTIONS 变量：

  如果您使用 Docker 构建应用程序，请 NODE_OPTIONS 通过在您的 Dockerfile 文件中添加以下行来设置（位于最后一个 FROM 语句之后，且在启动 进程 nodeENTRYPOINT 的最终 CMD 或 之前）：

  • 请使用以下命令导入 Instana 收集器（适用于 Node.js18.19 及更高版本）：

    ENV NODE_OPTIONS="--import /path/to/instana/node_modules/@instana/collector/esm-register.mjs"
     

• 或者，在启动 Node.js 时添加 参数 --import 。如果您使用 启动应用程序 node app/index.js，请在 --import 命令后附加。

  • 请使用以下命令导入 Instana 收集器（适用于 Node.js18.19 及更高版本）：

    node --import /path/to/instana/node_modules/@instana/collector/esm-register.mjs app/index.js
     

  加载器会自动初始化 Instana Node.js 收集器。

使用 Webpack 或 Rollup 等捆绑程序预处理Node.js服务器应用程序时，请确保只捆绑您的代码，而不是 "node_modules文件夹中的依赖程序代码。

由于以下原因，必须排除依赖关系:

• 模块 @instana/collector 不支持使用 Webpack 预先处理。 除其他问题外，未正确解决代码中使用的动态 require 语句。
• 为了对第三方库进行插桩， npm 包会 @instana/collector 拦截 Node.js 的 require 执行过程。但如果这些库不是在运行时加载的，而是已在构建时与您的代码打包在一起，则不会执行 require 该过程，因此也不会应用插桩。 因此， Instana 的追踪功能无法正常工作或仅部分有效，也就是说，追踪功能仅对 Node.js 核心模块（如）有效 http ，因为这些模块默认不包含在打包范围内。

因此，必须使用模块 webpack-node-externals 来配置捆绑程序，以便从所有代码变换中排除 node_modules 中的所有内容:

// your webpack.config.js:

const nodeExternals = require('webpack-node-externals');

module.exports = {
  ...
  // externals: nodeModules,
  externals: [nodeExternals()],
  ...
};
 

如果您使用 Angular CLI（尤其是配合 Angular Universal 或 SSR 使用），则需要在您的 angular.json 文件中添加 "externalDependencies": ["@instana/collector"] （以及可能包含其他被 @instana/collector 监控的库），以将其从打包中排除。

如果使用TypeScript或 Babel 等转译器，请确保转译器生成的是CommonJS或 ECMAScript dist 代码。

通过CommonJS和ECMAScript 的加载标志初始化跟踪器。

有关在代码中访问 SDK 的更多信息，请参阅ECMAScript 模块。