ECMAScript 模块支持

Elastic APM Node.js 代理包括对 ECMAScript 模块 (ESM) 自动插桩的*有限且实验性*支持 — 即通过 import ... 语句或 import(...) 表达式加载的模块。此支持基于实验性的 Node.js 加载器 API (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 http://localhost: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 自动插桩需要使用 --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 代理的各种方法，请参见 启动代理。

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

ESM 自动插桩仅支持符合以下要求的 Node.js 版本：^12.20.0 || ^14.13.1 || ^16.0.0 || ^18.1.0 || >=20.2.0。在将 node --experimental-loader=elastic-apm-node/loader.mjs 用于更早的 Node.js 版本时的行为是未定义且不受支持的。

ES 模块的自动插桩目前受到此处所述的限制。请注意，支持的模块版本范围通常与 CommonJS (即 require()) 自动插桩不同。

如果您看到如下错误，则表示您尝试将 ESM 自动插桩支持用于过早的 Node.js 版本。请参见上方的支持的 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)