TeamCity 10插件开发：如何向Build Log中添加消息

我之前开发TeamCity插件时也碰到过完全一样的问题——明明在Listener里调用了日志方法，但Build Log标签页就是没显示内容，折腾了好一阵才找到关键，给你几个实用的解决方向：

1. 使用官方推荐的BuildProgressLogger写入日志 #

这是TeamCity专门用来往Build Log标签页输出内容的工具，千万别用普通的Java Logger或者SLF4J，那些只会写到服务器的日志文件里，不会出现在Build Log中。

获取Logger的方式： #

根据你监听的事件类型，有两种常见获取路径：

• 针对服务器端构建事件（比如BuildStartListener）：从事件参数里拿到Build实例，再获取Logger

public class CustomBuildListener implements BuildStartListener {
    @Override
    public void buildStarted(BuildStartedEvent event) {
        // 获取BuildProgressLogger实例
        BuildProgressLogger logger = event.getBuild().getBuildLogger();
        
        // 写入普通日志消息
        logger.logMessage("✅ 自定义Listener已触发，这是写入Build Log的普通消息");
        // 写入错误日志（会以红色显示）
        logger.logError("❌ 这是写入Build Log的错误消息");
        // 还可以写入警告、成功等不同类型的日志
        logger.logWarning("⚠️ 这是写入Build Log的警告消息");
    }
}

• 针对Agent端构建事件（比如AgentLifeCycleListener）：从AgentRunningBuild实例中获取Logger

public class CustomAgentListener implements AgentLifeCycleListener {
    @Override
    public void buildStarted(AgentRunningBuild build) {
        BuildProgressLogger logger = build.getBuildLogger();
        logger.logMessage("🤖 Agent端Listener已触发，写入Build Log消息");
    }
}

2. 确保Listener在plugin.xml中正确注册 #

很多时候日志写不进去，根本原因是Listener没被TeamCity正确加载。检查你的plugin.xml是否正确声明了扩展：

<plugin xmlns="http://jetbrains.com/teamcity/schema/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://jetbrains.com/teamcity/schema/1.0 https://www.jetbrains.com/teamcity/schema/1.0/teamcity-plugin.xsd">
    <!-- 其他插件配置 -->
    <extensions>
        <!-- 注册服务器端Listener -->
        <listener class="com.yourcompany.plugin.listeners.CustomBuildListener" />
        <!-- 如果是Agent端Listener，需要指定agent="true" -->
        <listener class="com.yourcompany.plugin.listeners.CustomAgentListener" agent="true" />
    </extensions>
</plugin>

注意包路径要和你的类完全一致，并且类文件要打包到插件的jar包中。

3. 确认事件触发时机是否合适 #

有些早期的构建事件触发时，Build Log的Logger可能还没完全初始化，导致写入的内容无法显示。如果当前监听的事件不行，可以试试换一个更晚的事件，比如：

• BuildProgressListener的buildProgressStarted方法
• BuildFinishListener的buildFinished方法

4. 检查Logger的输出级别 #

TeamCity的Build Log有级别过滤，确保你写入的日志级别没有被过滤掉。比如如果用logMessage，默认是INFO级别，只要Build Log的过滤级别没设成WARN或更高，就能看到。

内容的提问来源于stack exchange，提问作者lukaszrys