ECMAScript 模块支持

Elastic APM Node.js 代理包含对 ECMAScript 模块 (ESM) 的有限且实验性自动检测支持，即通过 import ... 语句或 import(...) 表达式加载的模块。支持基于实验性的 Node.js 加载器 API，这需要将 --experimental-loader 选项传递给 node。

作为第一个示例，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://127.0.0.1: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 支持有限，仅实现了 支持的技术 中列出的一部分模块。后续版本将添加更多模块。有关完整详细信息，请参见下文。

ESM 限制仅影响代理的自动检测。其他功能（例如指标收集、手动检测和错误捕获）在使用 ES 模块时仍然有效。

启用 ESM 自动检测编辑

启用 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 代理的各种方法，请参见 启动代理。

支持的 Node.js 版本编辑

ES 模块的自动检测基于实验性的 Node.js 加载器 API。Elastic APM Node.js 代理中的 ESM 支持将在加载器 API 处于实验阶段时保持实验性。

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()）自动检测的范围不同。

ESM 支持故障排除编辑

如果您看到以下错误，则您尝试使用过早版本的 Node.js 来使用 ESM 自动检测支持。请参见上面的 支持的 Node.js 版本。

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)