当无法在本地重现生产环境中出现的问题时，该如何进行诊断呢？

每个开发者最终都会遇到同样的令人沮丧的问题。

有客户报告称，你的应用程序在生产环境中出现了故障。你在开发机器上使用完全相同的工作流程进行测试，但一切运行得都非常正常。你的团队成员也无法重现这个问题。自动化测试也通过了，代码中也没有任何明显的变动能够解释这种故障现象。

然而，客户们仍然在遇到这个bug。

这类问题是最难解决的，因为问题的根源往往并不在于代码本身，而在于代码运行的环境。配置差异、基础设施问题、流量模式的变化、操作系统不同、依赖关系的差异，或者生产环境中的数据差异，都可能导致那些在开发阶段根本不会出现的问题。

事实是：这些困难大多是我们自己造成的。你管理的每一台服务器、你搭建的每一个日志处理流程、以及你手动维护的每一份配置文件，都在无形中增加了系统的复杂性。而当你面临生产环境中的问题时，这种复杂性就会带来巨大的麻烦——尤其是在系统出现故障、客户正在等待解决方案的时候。

幸运的是，那些仅在生产环境中才会出现的bug是可以被系统地排查出来的。在这篇文章中，你将学习如何利用日志、指标、分布式追踪以及环境分析等方法来解决这些问题。同时，你也会了解到：当应用程序运行在平台即服务（PaaS）环境下时，出问题时进行调试会变得容易得多，因为这些问题的“代价”其实是由其他人来承担的。

我们将涵盖的内容：

• 为什么生产环境中的表现会不同？

• 以事实为依据，而非凭假设开始分析

• 日志能告诉你发生了什么

• 指标可以帮助你发现趋势

• 分布式追踪能够连接所有的服务

• 尽可能准确地重现生产环境中的问题

• 隔离各种环境变量对系统的影响

• 一个简单的、仅在生产环境中才会出现的bug示例

• 验证部署过程本身是否正确

• 你真的需要平台即服务吗？

• 为什么在PaaS环境下调试会更容易

• 构建易于调试的应用程序

为什么生产环境中的表现会不同？

许多开发者认为，生产环境只不过是他们本地开发环境的放大版而已。

实际上，生产环境往往存在很大的差异。

一个生产环境中的应用程序可能会运行在多台服务器或容器上，并且这些服务器或容器会通过负载均衡器进行连接。该应用程序可能需要访问包含数百万条记录的数据库，与第三方API进行交互，使用分布式缓存系统，处理后台任务，同时还要为数千名并发用户提供服务。

即使是一些看似微小的差异，也可能会引发意想不到的问题。

想象一下，在本地测试API时，你使用了像“John Smith”这样的简单英文名称，一切都很顺利。但在生产环境中，如果客户输入了一个包含表情符号或带重音字符的名称，就会导致编码问题，而这种问题在之前的测试中根本没有被发现。

或者，你的应用程序可能认为某个环境变量总是存在的，因为所有开发人员的机器上都配置了这个变量。但在部署过程中，这个变量被意外遗漏了，从而导致生产环境中的请求失败。

代码本身并没有发生变化，变化发生在环境配置上。

注意这些故障的共同点：它们都不是业务逻辑方面的问题，而是环境配置导致的问题。你们团队自己管理并手动配置的每一项基础设施，都可能成为环境设置与代码预期出现差异的根源。你管理的基础设施越多，这类问题出现的可能性就越大。

认识到生产环境与开发环境的差异，是诊断这些问题的第一步。

以事实为依据，而非凭猜测开始行动

当生产环境出现问题时，人们往往会立刻想要去修改代码。

但请抵制这种冲动。

解决复杂问题的最快方法是在进行任何修改之前先收集足够的证据。

首先可以尝试回答以下这些问题：

• 这个问题是什么时候开始的？

• 它是在部署之后立刻出现的吗？

• 它是影响所有客户，还是只影响一小部分用户？

• 是不是所有的应用程序实例都会出现这个问题？

• 在问题出现的同时，基础设施的监控数据有没有发生变化？

每一个问题的答案都能帮助缩小排查范围。

但有一点很少有人会告诉你：你回答这些问题的速度，在很大程度上取决于你的基础设施配置，而不是你的调试技巧。

如果部署相关的信息存储在不同的系统中，日志数据又在另一个系统里，而监控数据又储存在第三个系统中，那么即使只是回答第一个问题，也需要登录三个工具并手动比对时间戳。这样的排查过程可能会在开始之前就陷入停滞，原因并不是因为问题本身难以解决，而是因为你的工具使用起来非常不便。

与其猜测可能出什么问题，不如先整理出一套事件发展的时间线，这样就能更快地找到问题的根源。

良好的调试工作实际上是一种调查过程，而不是实验。而调查的效率高低，完全取决于你是否能够方便地获取所需的证据。

日志能告诉你发生了什么

在发生故障时，应用程序日志通常是获取信息的首选来源。

遗憾的是，许多应用程序生成的日志几乎不包含任何有用的信息。

那么，这些日志分别是如何生成的呢？第一种日志是开发者在编写代码时为了快速处理异常而添加的，通常是这样写的：catch (Exception) { logger.LogError("处理请求时出现错误."); } 虽然异常被捕获了，但关于这个异常的所有有用信息都被忽略了。日志中只记录了“发生了故障”，却没有说明“发生了什么故障”、“在哪个地方发生的”或“是哪位客户遇到了问题”。

{
  "message": "在尝试通过POST请求访问/orders接口为客户48291创建订单时，操作在3.2秒后失败",
  "CustomerId": 48291,
  "Endpoint": "POST /orders",
  "Duration": 3.2,
  "Exception": "TimeoutException"
}

结构化日志带来的最大好处就是便于搜索。对于纯文本日志来说，要查找某个客户的所有失败记录，就需要进行模糊匹配，而且这完全取决于运气；而使用结构化日志，监控系统就可以执行像`CustomerId = 48291 AND Exception = TimeoutException`这样的精确查询，从而在几秒钟内从数百万条记录中筛选出所需信息。Serilog这类库，以及.NET中的内置`ILogger`，都支持这种功能。

记录错误的目的并不仅仅是为了保存日志本身，而是要提供足够的上下文信息，这样那些负责调查问题的人就能立即开始提出正确的问题。

不过，这里也有一个需要注意的地方：如果无法找到这些日志，那么再好的日志也毫无用处。

在自我管理的环境中，日志往往分散在不同的服务器上，因此各团队不得不自行构建和维护数据汇总机制，才能让这些日志具备可搜索性。这样就会浪费大量的工程资源，而这些资源本应该被用于开发产品本身。

如果你的团队一直在维护自己的日志传输系统，那么就有必要思考这样一个问题：为什么我们还要自己来做这件事呢？

指标能揭示趋势

日志可以记录单个事件的具体情况，而指标则能够反映整个系统的运行状况。

但通过指标仪表板，就能立刻看到CPU使用率在下午时分会飙升至90%以上，内存消耗量会持续增加，数据库响应延迟会在午餐后翻倍，而在流量高峰期HTTP错误率也会急剧上升。

这个流程分为三个步骤。首先，你的应用程序需要暴露自己的指标数据。大多数开发框架都提供了相应的功能。在ASP.NET Core中，只需添加prometheus-net包并配置一行代码，就能生成一个//metrics接口，用于报告请求总数、响应耗时以及错误数量等指标。

其次，Prometheus服务器会每隔几秒读取一次这些指标数据，并将其存储为时间序列数据。

最后，Grafana会将这些时间序列数据转化为可视化的仪表板。

一旦这样的系统建立起来，对于“每天下午应用程序变慢”这一问题的调查就不再需要靠猜测了。你只需打开Grafana，设置时间范围为过去三天，然后针对Prometheus执行如下查询：

rate(http_request_duration_seconds_sum[5m])
/ rate(http_request_duration_seconds_count[5m])

这个查询就能显示出你的应用程序的平均响应耗时变化情况。如果图表显示从下午1点开始到4点期间，延迟值一直在不断上升，那么你几乎可以在一分钟内确认这一规律的存在。如果再添加一个面板，在同一时间轴上展示CPU使用率或数据库连接数的变化情况，就能判断出是哪种资源首先出现了问题，从而找出问题的根源。

这些观察结果立刻为你的调查指明了方向。你不再需要思考从哪里开始，而是清楚地知道问题发生在什么时候，以及是哪个组件处于高压状态。

各种指标能将零散的故障转化为可识别的模式。

但是，这个监控面板并不是自动搭建起来的。必须有人来安装相关工具、配置数据输出模块、确定时间序列数据库的大小，并确保整个监控系统能够正常运行。

在许多团队中，监控系统本身也变成了另一个需要维护和调试的生产系统。对监控系统进行进一步的监控，实际上就是一种极其荒谬的“基础设施维护工作”；而这种情况也清楚地表明，你的团队承担了本不必承担的运营负担。

分布式追踪连接了所有服务

现代应用程序很少是由单一应用与单一数据库构成的。

一个客户请求在得到响应之前，可能会经过API网关、认证服务、订单处理服务、支付系统、库存管理系统、缓存系统、消息队列以及数据库等环节。

当出现问题时，究竟是哪个服务导致了延迟呢？

分布式追踪能够解答这个问题。一条追踪记录会完整地展现某个请求在系统中流动的整个过程。追踪中的每一個处理步骤——比如一次服务调用或一次数据库查询——都被称为跨度，每个跨度都会记录其开始时间以及耗时长度。

以下是在Jaeger或Zipkin等工具中查看追踪记录的实际示例：假设有客户反映结账流程超时了，你根据他们的请求ID查找追踪记录，就会看到如下这样的信息：

Trace 8f3ac21 — POST /checkout — total: 4.61s

api-gateway            ████                                    45ms
auth-service         ██                                      38ms
order-service        ████████████████████████████████  4.51s
    inventory-db query ██████████████████████████████████    4.29s  ⚠
payment-api        ███                                    210ms
response             █                                       12ms

阅读这样的追踪记录只需要几秒钟。在整个请求处理过程中，有4.29秒的时间被用于一次数据库查询操作。网关、认证服务和支付API都运行正常，因此没有人需要进一步调查它们，也不需要进行任何猜测。

从底层原理来看，这种机制之所以能够实现，是因为第一个服务会为请求分配一个唯一的追踪ID，并在后续的所有调用中都将这个ID作为头部信息传递下去。每个服务都会将自己对应的处理步骤记录在这个相同的ID下，这样追踪系统就能将整个请求的处理过程重新还原出来。

所有这些功能的开放标准是OpenTelemetry，它为各种主流编程语言提供了相应的开发工具包；在许多框架中，启用这一功能只需要编写几行配置代码，而无需进行繁琐的手动修改。

如果没有追踪功能，工程师们往往需要花费数小时来排查错误的服务。而有了追踪机制，那些运行速度最慢或出现故障的组件通常能在几秒钟内被识别出来。

问题在于，自行搭建追踪系统实际上是一项庞大的工程任务，而非简单的操作步骤。为每个服务添加追踪功能、部署数据收集工具以及存储追踪数据都需要投入大量的精力，正因如此，许多明知需要追踪功能的团队仍然没有实施这一措施。

当可观测性是需要通过人工构建才能实现的，而不是由平台直接提供的功能时，它往往就会长期被列在开发计划中，而各种问题却依然会如期出现。

尽可能真实地复现生产环境

有时候，日志和追踪数据并不足够。最终，你还是需要重新创建生产环境来进行测试。

这并不一定意味着要把生产环境的数据库复制到笔记本电脑上。相反，你需要找出不同环境之间的差异。

• 生产环境中使用的是Linux系统，而开发人员使用的却是Windows或macOS吗？

• 生产环境使用了Redis作为数据存储工具，而开发环境却没有使用它吗？

• 两种环境中安装的运行时版本是否不同？

请求是经过反向代理服务器转发的吗？

• 生产环境处理的数据量是否远大于开发环境？

• 生产环境会同时接收数百个请求，而开发环境却只接收一个请求吗？

每一个这样的差异都可能是导致问题的原因。

那么，该如何消除这些差异呢？有几种方法可以解决大部分问题：

将应用程序容器化

如果生产环境是使用容器来运行你的应用程序，那么在本地环境和测试环境中也应该使用相同的容器镜像。这样就可以一次性消除操作系统、运行时版本以及依赖项之间的差异，因为容器本身就会携带其运行环境。

将基础设施和配置定义为代码

像Redis、反向代理服务器这样的服务及其相关设置，应该通过配置文件（如`docker-compose.yml`、Kubernetes配置文件或Terraform脚本）来定义，而不是通过手动操作来进行配置。

当测试环境和生产环境都是根据相同的配置文件生成的时，它们就不可能出现不一致的情况。当你需要了解生产环境是否使用了反向代理服务器或什么运行时版本时，可以直接从配置文件中获取这些信息，而无需去询问负责设置服务器的人员。

使数据具有真实性

实际上，你很少需要使用真实的生产环境数据，而且出于隐私考虑，通常也不应该使用这类数据。你需要的是那些在“格式”上与生产环境数据相似的数据：数据量大致相同，数据结构也类似。

可以在测试环境中生成几百万条数据记录，并包括一些特殊的情况，比如带有重音符号的名称、表情符号、包含大量空值的记录以及非常长的字符串。

模拟生产环境下的流量

那种只有在上百个请求同时发起时才会出现的错误，如果你一次只测试一个请求，是永远无法发现的。像k6或JMeter这样的负载测试工具，可以通过简单的脚本在测试环境中模拟真实的并发场景，这样往往就能重现那些导致程序异常或连接池耗尽的问题。

你的测试环境越接近生产环境，就越有可能在客户遇到问题之前就发现那些仅在生产环境下才会出现的故障。

而对于那些使用相同配置生成所有环境的团队来说，他们一开始就需要处理的生产环境特有的错误自然也就更少。

隔离环境变量

最有效的调试方法之一就是一次只修改一个变量。

假设你的应用程序只在生产环境中会出现故障，那么可能导致这种差异的因素可能包括操作系统版本、数据库引擎、容器配置、环境变量、内存限制、网络延迟或基础设施设置等等。

# 测试1：只改变数据库版本
docker run -d -p 5432:5432 postgres:16
# → 运行会出现故障的请求。仍然可以正常运行吗？如果是这样，说明问题出在数据库版本上，将版本改回15即可。

# 测试2：只改变内存限制
docker run --memory=512m my-app
# → 运行会出现故障的请求。如果出现了OutOfMemoryError错误，那么问题就出在内存限制上。

app.MapGet("/discount", () =>
{
    string region = Environment.GetEnvironmentVariable("REGION");

    if (region.ToLower() == "eu")
        return Results.Ok("20%折扣");

    return Results.OK("10%折扣");
});

NullReferenceException

string region = Environment.GetEnvironmentVariable("REGION") ?? "US";

if (region.Equals("EU", StringComparison.OrdinalIgnoreCase))
    return Results.Ok("20%折扣");