Next.js 入门

Elastic APM Node.js 代理可用于跟踪运行应用程序的 Next.js 服务器（next start 或 next dev），无需对应用程序进行代码更改。传入到服务器的 HTTP 请求的 APM 事务将以应用程序中的 页面 和 API 端点 命名，以及 Next.js 使用的内部路由。服务器上运行的代码中的错误将被报告，以便在 Kibana APM 应用程序中查看。

请注意，Node.js APM 代理只能检测 服务器端 代码。要监控 Next.js 应用程序的客户端部分，请参阅 Elastic RUM 代理。

先决条件编辑

您需要一个 APM 服务器来发送 APM 数据。如果您尚未设置，请按照 APM 快速入门 进行操作。您将需要您的 APM 服务器 URL 和一个 APM 服务器 密钥令牌（或 API 密钥）用于在下面配置 APM 代理。

您还需要一个要监控的 Next.js 应用程序。如果您没有现有的应用程序可以使用，您可以使用以下方法创建一个入门应用程序（有关更多信息，请参阅 Next.js 入门文档）

npx create-next-app@latest  # use the defaults
cd my-app

您也可以查看并使用此 Next.js + Elastic APM 示例应用程序。

步骤 1：添加 APM 代理依赖项编辑

将 elastic-apm-node 模块作为依赖项添加到您的应用程序中

npm install elastic-apm-node --save  # or 'yarn add elastic-apm-node'

步骤 2：启动 APM 代理编辑

要使 APM 代理检测 Next.js 服务器，它需要在加载 Next.js 服务器代码之前启动。最佳方法是使用 Node 的 --require 选项加载 "elastic-apm-node/start-next.js" 模块 - 这将启动代理（以及 Next.js 集成的更多内容）。

编辑 "package.json" 中的 "dev" 和 "start" 脚本，如下所示

{
  // ...
  "scripts": {
    "dev": "NODE_OPTIONS=--require=elastic-apm-node/start-next.js next dev",
    "build": "next build",
    "start": "NODE_OPTIONS=--require=elastic-apm-node/start-next.js next start",
    "lint": "next lint"
  },
  // ...
}

步骤 3：配置 APM 代理编辑

可以使用环境变量或当前工作目录中的 "elastic-apm-node.js" 模块来 配置 APM 代理。请注意，由于 APM 代理在加载 Next.js 服务器之前加载，因此 Next.js 支持的 ".env" 文件 无法 用于配置 APM 代理。我们将在此处使用 "elastic-apm-node.js" 文件。

在应用程序根目录中创建一个 "elastic-apm-node.js" 文件，其中包含来自上面 先决条件 部分的 APM 服务器 URL 和密钥令牌值

// elastic-apm-node.js
module.exports = {
  serverUrl: 'https://...',  // E.g. https://my-deployment-name.apm.us-west2.gcp.elastic-cloud.com
  secretToken: '...'
}

使用环境变量的等效方法是

export ELASTIC_APM_SERVER_URL='https://...'
export ELASTIC_APM_SECRET_TOKEN='...'

有关支持的配置变量的完整详细信息，请参阅 代理配置指南。

步骤 4：启动您的 Next.js 应用程序编辑

npm run dev  # or 'npm run build && npm start' for the production server

在浏览器中打开 https://127.0.0.1:3000 以加载您的 Next.js 应用程序。如果您使用了上面的 create-next-app 工具，它会定义一个 /api/hello API 端点。您可以在单独的终端中运行以下命令来提供一些人工负载

while true; do sleep 1; curl -i https://127.0.0.1:3000/api/hello; done

访问您的 Kibana APM 应用程序，几秒钟后，您应该会看到您的 Next.js 应用程序的服务条目。服务名称将从 "package.json" 中的 "name" 字段中提取。它可以使用 serviceName 覆盖。这是一个示例

限制和未来工作编辑

此 Next.js 检测有一些限制需要注意。

Next.js 构建工具捆绑了客户端 和 服务器端代码执行的依赖项（使用 Webpack）。Node.js APM 代理在捆绑时不起作用。有关详细信息，请参阅 捆绑器和 APM。对 Next.js 检测的影响是，您不能直接在代码中导入和使用 APM 代理。这意味着目前无法使用 Agent API 进行手动检测。

此检测支持为许多内部 Next.js 路由命名 APM 事务。例如，对于 服务器端渲染 (SSR)，Next.js 客户端代码将发出类似于 GET /next/_data/$buildId/$page.json 的请求，APM 代理为此命名事务 Next.js _next/data route $page。但是，Next.js "public 文件夹通配符" 路由存在限制。解析为 "public/" 目录中文件的 HTTP 请求（例如 GET /favicon.ico）将导致事务名为 GET unknown route。请参阅下面的 未知路由。

如果您发现其他限制或有任何建议，请在我们的 讨论论坛 上提供反馈。

性能监控编辑

Elastic APM 会自动测量 Next.js 应用程序的性能。它会记录数据库查询、外部 HTTP 请求和其他在请求 Next.js 应用程序期间发生的缓慢操作的跨度。跨度按事务分组 - 默认情况下，每个传入的 HTTP 请求一个。

未知路由编辑

在 Elastic APM 中查看应用程序的性能指标时，您可能会看到一些名为 "unknown route" 的事务。这表示代理检测到传入到应用程序的 HTTP 请求，但不知道该 HTTP 请求匹配了 Next.js 应用程序中的哪个路由。

这可能仅仅是 404 请求（根据定义，它们不匹配任何路由），或者可能是代理未正确安装的症状。如果您看到这种情况或无法显示任何有意义的指标，请按照 故障排除指南 进行操作。

过滤敏感信息编辑

默认情况下，Node.js 代理会在将错误和指标发送到 Elastic APM 服务器之前过滤常见的敏感信息。

您可以调整这些默认值或删除您不想发送到 Elastic APM 的任何信息

兼容性编辑

有关详细信息，请参阅 支持的技术。

故障排除编辑

如果您无法按预期使用 Node.js 代理，请遵循 故障排除指南。