分析网络服务器错误

错误计数表明出现了问题。结构化上下文（路由、状态代码、发布和请求 ID）可帮助您识别出现问题的内容并将其与部署关联起来。

将 5xx 峰值与版本和 POST 结帐路由关联起来的 Web 服务器错误仪表板 — 最有用的错误事件会保留事件期间所需的维度。

在现代 Web 开发中，监控和日志记录是维护健壮且可靠的应用程序的关键方面。 Telemetry 允许开发人员跟踪各种事件和系统指标，这对于调试和改善用户体验至关重要。在这篇文章中，我们将探讨如何使用 Telemetry API 捕获并记录 Express.js Web 服务器中的所有错误。虽然本指南仅涵盖 Express，但这些想法适用于所有 Web 服务器，从 Rails 到 Elixir 等。

设置Telemetry

在记录任何数据之前，我们需要设置 Telemetry。在此示例中，我们将使用 Telemetry JavaScript SDK。

首先，在您的项目中安装 Telemetry SDK：

npm install telemetry-sh

然后，使用 API 密钥在应用程序中初始化 Telemetry 客户端：

const telemetry = require("telemetry-sh");

telemetry.init(process.env.TELEMETRY_API_KEY);

在服务器环境中设置 TELEMETRY_API_KEY。不要把密钥放进浏览器代码或提交到代码仓库。

创建 Express 应用程序

接下来，让我们设置一个基本的 Express 应用程序。如果您尚未安装 Express，可以使用以下命令将其添加到您的项目中：

npm install express

现在，创建一个简单的 Express 服务器：

const express = require('express');
const app = express();
const port = 3000;

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`);
});

添加结构化错误中间件

错误处理程序属于所有路由之后。捕获安全类别和操作上下文，而不是可能包含私有值的原始主体、凭据、堆栈跟踪或异常消息。

// Add this after the real routes in your existing Express app.
app.use((err, req, res, next) => {
  if (res.headersSent) return next(err);
  const statusCode = Number(err.statusCode) || 500;
  const rawCode = typeof err.code === "string" ? err.code : "";
  const errorCode = /^[A-Z0-9_]{1,40}$/.test(rawCode)
    ? rawCode
    : "UNCLASSIFIED_ERROR";

  res.status(statusCode).json({ error: "Request failed" });

  void Promise.resolve()
    .then(() => telemetry.log("api_request_failed", {
      route_template: req.route?.path ?? "unmatched_route",
      method: req.method,
      status_code: statusCode,
      status: "error",
      error_type: err.constructor?.name ?? "Error",
      error_code: errorCode,
      request_id: res.locals.requestId ?? "missing",
      release: process.env.APP_RELEASE ?? "unknown",
    }))
    .catch(() => console.warn("Telemetry error event was not sent"));
});

将此处理程序添加到处理真实路由的 Express 应用中。上面的 Hello World 示例不会产生错误事件。执行一次真实的失败请求，再查询 api_request_failed，确认该事件已存储。如果应用生成可信的请求 ID，请在此处理程序之前将其放入 res.locals.requestId。示例先返回响应，再异步发送 Telemetry 事件；在无服务器环境中，请使用平台支持的后台任务或刷新机制，而不要依赖未等待的 Promise。

使用 /api/projects/:id 等路由模板，而不是包含客户标识符的原始路径。当这些失败对工作流程很重要时，请保持处理的 4xx 和 5xx 响应的事件架构相同。

查询并可视化错误

先按路由和版本统计失败次数，再保留最近的事件表用于排查：

SELECT
  route_template,
  release,
  status_code,
  error_code,
  COUNT(*) AS failures,
  MAX(timestamp_utc) AS last_seen_at
FROM api_request_failed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route_template, release, status_code, error_code
ORDER BY failures DESC, last_seen_at DESC;

为了获得真实的错误率，请使用共享的 status 或 status_code 字段将成功和失败的请求记录到同一个表中。仅故障表可以对错误进行排名，但无法提供分母。

后续步骤

使用 API 路由配方错误率进行分母安全查询、示例可视化、仪表板布局和告警指导。将其与 API 延迟百分位配对，以便事件视图涵盖正确性和速度。

让编程智能体使用这篇文档