MS RFC 28：重新设计日志/调试输出机制

日期

2007-06-14

作者

丹尼尔·莫里塞特

联系

在mapgears.com的dmorissette

最后编辑

2007-08-24

状态

通过（2007-06-29）-完成实施（2007/07/06）

版本

MAPServer 5

概述

MapServer 4.10及更旧版本以前有多个日志/调试输出机制，但它们不能很好地协同工作。为了提高软件的可用性，此RFC提出了一种新的日志/调试输出机制，该机制对输出位置（日志文件或stderr）具有更多的控制，并且在所有受支持的Web服务器下工作。

现有机制清单

MapServer 4.10及更低版本支持以下日志/调试系统：

  • 在Web对象中记录[文件名]：

    从文档：“文件到日志中的mapserver活动。必须可由运行Web服务器的用户写入。“

    更具体地说，mapserv.c中的函数writelog（）在执行结束时记录有关mapserv cgi请求结果的信息。此选项对mapscript无效。

  • MS-ErrorFile环境变量：

    如果设置，则所有对mssterror（）的调用都将记录到此文件中。

  • msdebug（）在映射和层级别上打开/关闭调试：

    在代码的各个区域中都有msdebug（）调用，这些调用生成的信息可能对应用程序的调优和故障排除很有用。map和layer对象中的debug on/off语句用于启用/禁用msdebug（）调用。msdebug（）机制在默认情况下也被禁用，并且仅由-denable_stderr_debug编译时选项启用。用户可以从更容易地访问这些信息和更多的调试信息中获益。

    msdebug（）的输出被发送到stderr，无法重定向。除了不太灵活之外，这也是在IIS下的一个问题，其中stderr输出转到stdout，msdebug（）输出损坏了mapserver的输出。

问题

  • 问：是否有人真正使用了特定于mapserv的日志选项？我们需要维护它吗，我们应该摆脱它，还是应该扩展它？至少应更好地记录该选项，以避免与本RFC中描述的其他机制混淆。

    答：日志选项不会被这个RFC影响。

技术解决方案

我们将基本上合并ms_错误文件和debug/ms debug（）机制。变量ms_errorfile将指定输出的位置，可能的值为磁盘上的文件路径或“stderr”或“stdout”之一。

控制msdebug（）输出的当前调试开/关机制也将得到扩展，以支持多个调试级别。

为了保持实现相对简单和高效，输出文件句柄将在当前请求上下文中的全局变量中通过引用保持打开，并且仅在mscleanup（）中关闭。这意味着，如果在同一请求中使用不同的ms-errorfile设置加载了两个映射文件，那么这两个映射文件的错误/调试语句将转到同一个文件（当读取第二个映射文件时，输出文件将更改）。

注意：输出文件句柄只在当前请求的上下文中是全局的，而不是跨线程的全局的，这将使用maperror.c中msgetErrorObj（）当前使用的相同机制来完成。

设置MS错误文件

变量ms_errorfile将指定输出的位置，可能的值为磁盘上的文件路径或以下特殊值之一：

  • “stderr”将输出发送到标准错误。apache stderr下是apache错误日志文件。在IIS中，stderr将转到stdout，因此不鼓励使用它。对于IIS，建议将输出定向到磁盘上的文件。

  • “stdout”将输出发送到标准输出，并与mapserver的其余输出相结合。

  • “WindowsDebug”将输出发送到Windows OutputDebugString API，允许使用外部程序（如SysInternals DebugView）显示调试输出。

可以将ms-errorfile指定为环境变量或通过mapfile内的config指令：

CONFIG  "MS_ERRORFILE" "/tmp/mapserver.log"

或

CONFIG  "MS_ERRORFILE" "stderr"

如果同时设置了ms-errorfile环境变量，并且还设置了config-ms-errorfile，则config指令优先。

如果未设置ms_错误文件，则禁用错误/调试日志记录。在分析映射文件期间，错误/调试日志可能仅可用 after 已分析ms-errorfile指令。

调试级别

当前的调试开/关机制（在层和映射级别）将被扩展以支持多个调试级别，如下所示。默认值为Debug Off（0级）：

  • 级别0:仅限错误（debug off或debug 0）

    在级别0中，只有mssterror（）调用被记录到ms-erorfile。根本没有msdebug（）输出。这是默认值，与mapserver 4.x中ms_错误文件的原始行为相对应。

  • 级别1:错误和通知（调试打开或调试1）

    级别1包括来自级别0的所有输出加上msdebug（）有关常见陷阱、失败断言或非致命错误情况的警告（例如，某些参数的值丢失或无效、tileindex中缺少形状文件、来自远程WMS/WFS服务器的超时错误等）。

  • 级别2:映射优化（调试2）

    级别2包括级别1的所有输出以及对优化映射文件和应用程序有用的通知和时间信息

  • 级别3:详细调试（调试3）

    所有的2级加上一些调试输出，在排除诸如正在调用的WMS连接URL、数据库连接调用等问题时很有用。

  • 级别4:非常详细的调试（调试4）

    3级，更详细…

  • 第5级：非常详细的调试（调试5）

    级别4加上任何msdebug（）输出，对开发人员可能比对用户更有用。

ms_debuglevel环境变量

也可以使用（可选）ms_debug level环境变量设置调试级别。

设置后，该值将用作所有映射和层对象在映射文件分析器加载时的默认调试级别值。此选项还为位于映射或层对象上下文之外的任何msdebug（）调用设置调试级别，例如，为与加载映射之前的初始化相关的调试语句设置调试级别。如果在某些映射或图层对象的映射文件中也指定了调试值，则本地值（在映射文件中）优先于环境变量的值。

例如，当通过在加载映射之前启用计时/调试输出来优化应用程序时，此选项非常有用，以捕获完整的进程初始化和映射加载时间。

MapScript含义

没有直接的暗示。设置ms_错误文件也将在mapscript中启用调试输出。

请注意，在某些脚本环境中，对stderr或stdout的输出可能无法按预期工作，并且我们不打算做出任何特殊的努力来支持这些特殊情况，因为它们是这个RFC的一部分。但是，记录到磁盘上的文件将使用所有mapscript风格。

受影响的文件

map.h
mapfile.c
maperror.c

可能还需要编辑其中包含msdebug（）调用的几个源文件，以调整各种msdebug（）调用的调试级别。

向后兼容性问题

  • 默认情况下，mapserver 4.x和更早版本的ms_错误文件将继续工作。

  • 调试开/关机制和以前一样继续工作。但是，来自MapServer早期版本的某些msdebug（）输出可能需要更高的调试级别才能启用。

臭虫识别码

投票历史

投票于2007年6月29日完成：

+1来自丹尼尔姆、汤克、法兰克、塔马斯、杰夫姆、史蒂文和阿塞菲。

审查期间的问题/意见

  • 问：我们是否可以捕捉到ogr/gdal的cpldebug调用的输出，也许当map级别的调试级别大于等于3时？

    答：弗兰克建议我们把这个留到下一个阶段。