日志记录

介绍

您可以打开额外的日志记录来诊断和解决 GoCD 服务器和代理的问题。

日志位置

若要更改 GoCD 服务器日志或 GoCD 代理日志的存储位置，请使用系统属性。gocd.server.log.dir和gocd.agent.log.dir分别参考系统属性文档以了解如何在 gocd 服务器或代理上设置系统属性。

注意：系统属性处理的是 GoCD 服务器或代理相关日志的日志位置配置，而不是插件日志。

GoCD 服务器

要在 GoCD 服务器上启用更多日志记录，您必须：

创建/编辑文件CONFIG_DIR/logback-include.xml。配置目录通常是/etc/go在 Linux 上，以及C:\Program Files\Go Server\config在 Windows 上。查看部分日志配置语法获取日志配置语法。

下表描述了可以与服务器配置的各种记录器：

记录器	可加性	描述
`com.thoughtworks.go.server.Rails`	`true`	这将启用调试 rails 应用程序服务器。
`org.springframework`	`true`	这将启用 spring 框架的调试。
`org.apache.velocity`	`true`	这将启用一些服务器视图模板的调试。
`org.eclipse.jetty.server.RequestLog`	`false`	这将启用 HTTP 请求日志记录，以帮助诊断和识别页面渲染时间过长的问题。
`PerformanceLogger`	`false`	这将输出三个关键后台任务（调度、材料更新、工作分配）的性能调试日志。建议您使用附加程序将这些日志发送到不同的文件中。
`com.microsoft.tfs.core`	`true`	这将为 GoCD 使用的基础 Microsoft Team Foundation Server 库启用调试。
`com.thoughtworks.go.tfssdk14`	`true`	这将为 GoCD 包装的 Microsoft TFS 库启用调试。
`com.thoughtworks.go.domain.materials.dependency`	`true`	为类型的材料启用日志记录`dependency`.
`com.thoughtworks.go.domain.materials.git`	`true`	为类型的材料启用日志记录`git`.
`com.thoughtworks.go.domain.materials.mercurial`	`true`	为类型的材料启用日志记录`mercurial`.
`com.thoughtworks.go.domain.materials.packagematerial`	`true`	为类型的材料启用日志记录`packagematerial`.
`com.thoughtworks.go.domain.materials.perforce`	`true`	为类型的材料启用日志记录`perforce`.
`com.thoughtworks.go.domain.materials.scm`	`true`	为类型的材料启用日志记录`scm`.
`com.thoughtworks.go.domain.materials.svn`	`true`	为类型的材料启用日志记录`svn`.
`com.thoughtworks.go.domain.materials.tfs`	`true`	为类型的材料启用日志记录`tfs`.

GoCD 代理

要在 GoCD 代理上启用更多日志记录，您必须：

创建/编辑文件CONFIG_DIR/agent-logback-include.xml。配置目录通常是/var/lib/go-agent/config在 Linux 上，以及C:\Program Files\Go Agent\config在 Windows 上。查看部分日志配置语法获取日志配置语法。

下表描述了可以与服务器配置的各种记录器：

记录器	可加性	描述
`org.springframework`	`true`	这将启用 spring 框架的调试。
`org.apache.http.wire`	`true`	这将启用代理和服务器之间 HTTP 连接的调试。
`com.microsoft.tfs.core`	`true`	这将为 GoCD 使用的基础 Microsoft Team Foundation Server 库启用调试。
`com.thoughtworks.go.tfssdk14`	`true`	这将为 GoCD 包装的 Microsoft TFS 库启用调试。
`com.thoughtworks.go.domain.materials.dependency`	`true`	为类型的材料启用日志记录`dependency`.
`com.thoughtworks.go.domain.materials.git`	`true`	为类型的材料启用日志记录`git`.
`com.thoughtworks.go.domain.materials.mercurial`	`true`	为类型的材料启用日志记录`mercurial`.
`com.thoughtworks.go.domain.materials.packagematerial`	`true`	为类型的材料启用日志记录`packagematerial`.
`com.thoughtworks.go.domain.materials.perforce`	`true`	为类型的材料启用日志记录`perforce`.
`com.thoughtworks.go.domain.materials.scm`	`true`	为类型的材料启用日志记录`scm`.
`com.thoughtworks.go.domain.materials.svn`	`true`	为类型的材料启用日志记录`svn`.
`com.thoughtworks.go.domain.materials.tfs`	`true`	为类型的材料启用日志记录`tfs`.

日志配置语法

为了配置日志记录，您可以指定以下配置。您必须调整<logger />并且可选地<appender />以写入特定的日志文件。您可以在日志回滚配置文档中了解更多关于日志回滚配置的信息。此文件每 5 秒重新加载一次，因此无需重启 GoCD 服务器或代理。

注意：不建议长时间将日志级别设置为DEBUG或TRACE，因为这可能会显著影响性能。

<?xml version="1.0" encoding="UTF-8"?>

<!-- since this file is included in another file, use `<included />` and not `<configuration />`  -->
<included>
  <!-- send logs from `com.example.component-b` to the default log file (`go-agent.log` or `go-sever.log`) -->
  <logger name="com.example.component-b" level="DEBUG" />

  <!--
    Uncomment the lines below to redirect specific logs to a file different from the default log file (`go-agent.log` or `go-sever.log`)
    The configuration below will:
      - rollover daily;
      - each log will will be at most 10MB, keep 10 days worth of history, but at most 512 MB
  -->

  <!--
  <appender name="my-appender" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>logs/example.log</file>
    <encoder>
      <pattern>%date{ISO8601} %-5level [%thread] %logger{0}:%line - %msg%n</pattern>
    </encoder>

    <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
      <fileNamePattern>logs/example.log.%d{yyyy-MM-dd}.%i.gz</fileNamePattern>
      <maxFileSize>10 MB</maxFileSize>
      <maxHistory>10</maxHistory>
      <totalSizeCap>512 MB</totalSizeCap>
    </rollingPolicy>
  </appender>

  <logger name="com.example.component-a" level="DEBUG">
    <appender-ref ref="my-appender" />
  </logger>
  -->
</included>

示例：启用 web 请求日志

要启用 web 请求日志，请将以下内容添加到 logback-include.xml。

<?xml version="1.0" encoding="UTF-8"?>
<included>

  <appender name="web-request-appender" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>logs/web-requests.log</file>
    <!-- Use `C:\Program Files\Go Server\logs\` on windows and `~/Library/Application Support/Go Server/logs/` on MacOS for log directory path. -->
    <encoder>
      <pattern>%date{ISO8601} %-5level [%thread] %logger{0}:%line - %msg%n</pattern>
    </encoder>

    <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
      <fileNamePattern>logs/web-requests.log.%d{yyyy-MM-dd}.%i.gz</fileNamePattern>
      <!-- Use `C:\Program Files\Go Server\logs\` on windows and `~/Library/Application Support/Go Server/logs/` on MacOS for log directory path. -->
      <maxFileSize>10 MB</maxFileSize>
      <maxHistory>10</maxHistory>
      <totalSizeCap>512 MB</totalSizeCap>
    </rollingPolicy>
  </appender>

  <logger name="org.eclipse.jetty.server.RequestLog" level="DEBUG" additivity="false">
    <appender-ref ref="web-request-appender" />
  </logger>
</included>

高级日志记录功能

如果您想将日志事件发送到您选择的日志聚合服务（如 logstash、graylog、splunk），可能需要进行其他配置：

确保相关的 Java 库及其依赖项存在于libs目录中，相对于 GoCD 服务器或代理进程的工作目录。工作目录通常是/var/lib/go-{server,agent}在 Linux 上，以及C:\Program Files\Go {Server,Agent}在 Windows 上。
在相关的logback-include.xml文件中配置追加程序和编码器，用于您的代理或服务器。

示例 Logstash 配置

例如，要将日志发送到 logstash（使用logstash-logback-encoder），需要执行以下操作：

将所有 logstash-logback-encoder jar 和依赖项下载到libs目录：
- logstash-logback-encoder-*.jar
- jackson-databind-*.jar
- jackson-annotations-*.jar
- jackson-core-*.jar

然后按照README中的说明配置您的logback-include.xml设置相关的追加程序和编码器：

<?xml version="1.0" encoding="UTF-8"?>
<included>

  <!-- see https://github.com/logstash/logstash-logback-encoder for more examples and configuration -->
  <appender name="stash" class="net.logstash.logback.appender.LogstashTcpSocketAppender">
      <destination>127.0.0.1:4560</destination>
      <encoder class="net.logstash.logback.encoder.LogstashEncoder" />
  </appender>

  <root level="info">
    <appender-ref ref="stash" />
  </root>
</included>

覆盖现有的 logback.xml

如果您想完全覆盖打包的logback.xml，请创建一个CONFIG_DIR\logback.xml文件。如果存在这样的文件，GoCD 将使用文件中提供的记录器和文件追加程序进行日志记录。您可以在日志回滚配置文档

以下是示例logback.xml用户可以用来覆盖 GoCD 根记录器的日志记录。该示例使用用户定义的目录来写入日志。

<?xml version="1.0" encoding="UTF-8"?>
<configuration>

  <appender name="CustomFileAppender" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>logs/production_server/gocd-server.log</file>
    <encoder>
      <pattern>
        %date{ISO8601} %-5level [%thread] %logger{0}:%line - %msg%n
      </pattern>
    </encoder>

    <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
      <fileNamePattern>logs/production_server/gocd-server.log.%d{yyyy-MM-dd}.%i.gz</fileNamePattern>
      <maxFileSize>10 MB</maxFileSize>
      <maxHistory>50</maxHistory>
      <totalSizeCap>512 MB</totalSizeCap>
    </rollingPolicy>
  </appender>

  <root level="WARN">
    <appender-ref ref="CustomFileAppender"/>
  </root>

</configuration>

请注意，在覆盖 GoCD 服务器的日志记录时，将所有日志重定向到适当的文件，以避免任何日志丢失。

示例 GELF 配置

另一个使用 GELF（Graylog 扩展日志格式）的示例设置，使用logback-gelf:

下载logback-gelf-1.1.0.jar并将其放在libs目录中。在典型的 Linux 服务器上，可以通过

wget "https://repo1.maven.org/maven2/de/siegmar/logback-gelf/1.1.0/logback-gelf-1.1.0.jar" -O /var/lib/go-server/libs/logback-gelf-1.1.0.jar

配置logback-include.xml使用 gelf 追加程序中的任何一个，如在项目文档中定义。一个通过 UDP 的日志示例可能如下所示：

<included>
    <appender name="GELF" class="de.siegmar.logbackgelf.GelfUdpAppender">
        <graylogHost>graylog.mycompany.com</graylogHost>
        <graylogPort>12201</graylogPort>
        <layout class="de.siegmar.logbackgelf.GelfLayout">
            <includeRawMessage>false</includeRawMessage>
            <includeMarker>true</includeMarker>
            <includeMdcData>true</includeMdcData>
            <includeCallerData>false</includeCallerData>
            <includeRootCauseData>false</includeRootCauseData>
            <includeLevelName>false</includeLevelName>
            <shortPatternLayout class="ch.qos.logback.classic.PatternLayout">
                <pattern>%m%nopex</pattern>
            </shortPatternLayout>
            <fullPatternLayout class="ch.qos.logback.classic.PatternLayout">
                <pattern>%m</pattern>
            </fullPatternLayout>
            <staticField>application:go-server</staticField>
            <staticField>environment:production</staticField>
        </layout>
    </appender>

    <root>
        <appender-ref ref="GELF"/>
    </root>
</included>