ECMAScript 模块支持

Elastic APM Node.js 探针包含对 ECMAScript 模块 (ESM) 自动插桩（auto-instrumentation）的有限且实验性的支持——即通过 import ... 语句或 import(...) 表达式加载的模块。此支持基于实验性的 Node.js Loaders API，这需要向 node 传递 --experimental-loader 选项。

作为第一个示例，APM 探针可以为以下 Express 服务器提供 HTTP 追踪

// server.mjs
import bodyParser from 'body-parser'
import express from 'express'

const app = express()
app.use(bodyParser.json())
app.get('/hello/:name', function (request, reply) {
  reply.send({ hello: request.params.name })
})

app.listen({ port: 3000}, () => {
  console.log('Server is listening. Try:\n  curl -i https://:3000/hello/grace')
})
		

当按如下方式调用时

export ELASTIC_APM_SERVER_URL='https://...apm...cloud.es.io:443'
export ELASTIC_APM_SECRET_TOKEN='...'
node -r elastic-apm-node/start.js \
  --experimental-loader=elastic-apm-node/loader.mjs \
  node server.mjs
		

当前的 ESM 支持是有限的——仅实现了 Supported technologies 中列出的模块的一个子集。更多模块将在后续版本中添加。有关完整的详细信息，请参阅下文。

ESM 的局限性仅影响探针的自动插桩。其他功能——例如指标收集、手动插桩和错误捕获——在使用 ES 模块时仍然正常工作。

启用 ESM 自动插桩需要使用 --experimental-loader=elastic-apm-node/loader.mjs 选项启动 Node.js。这可以通过在命令行中传递该参数或设置 NODE_OPTIONS 环境变量来完成。

node --experimental-loader=elastic-apm-node/loader.mjs server.mjs

# or

NODE_OPTIONS='--experimental-loader=elastic-apm-node/loader.mjs'
node server.mjs
		

此外，APM 探针也必须单独启动——例如通过 --require=elastic-apm-node/start.js。有关启动 APM 探针的各种方法，请参阅 Starting the agent。

ES 模块的自动插桩基于实验性的 Node.js Loaders API。只要 Loaders API 处于实验阶段，Elastic APM Node.js 探针中的 ESM 支持将一直保持实验性。

ESM 自动插桩仅支持满足 ^12.20.0 || ^14.13.1 || ^16.0.0 || ^18.1.0 || >=20.2.0 的 Node.js 版本。在较早的 Node.js 版本中使用 node --experimental-loader=elastic-apm-node/loader.mjs，其行为是未定义的且不受支持。

如本文所述，当前对 ES 模块的自动插桩是有限的。请注意，支持的模块版本范围通常与 CommonJS（即 require()）自动插桩的版本范围不同。

如果您看到类似以下的错误，则说明您正试图在过低版本的 Node.js 中使用 ESM 自动插桩支持。请参阅上文的 Supported Node.js versions。

file:///.../node_modules/import-in-the-middle/hook.mjs:6
import { createHook } from './hook.js'
         ^^^^^^^^^^
SyntaxError: The requested module './hook.js' is expected to be of type CommonJS, which does not support named exports. CommonJS modules can be imported by importing the default export.
For example:
import pkg from './hook.js';
const { createHook } = pkg;
    at ModuleJob._instantiate (internal/modules/esm/module_job.js:98:21)
    at async ModuleJob.run (internal/modules/esm/module_job.js:137:5)
    at async Loader.import (internal/modules/esm/loader.js:165:24)
    at async internal/process/esm_loader.js:57:9
    at async Object.loadESM (internal/process/esm_loader.js:67:5)