版权归属于 LangChat Team
官网：https://langchat.cn

15 - 日志

版本说明

本文档基于 LangChain4j 1.10.0 版本编写。

学习目标

通过本章节学习，你将能够：

理解 LangChain4j 日志的重要性
掌握日志级别和配置
学会使用 SLF4J 记录日志
理解请求和响应日志
掌握日志过滤和输出控制
实现一个完整的日志配置

前置知识

完成《01 - LangChain4j 简介》章节
完成《02 - 你的第一个 Chat 应用》章节
Java 日志框架基础知识（SLF4J, Logback）

核心概念

为什么需要日志？

日志是任何应用的重要组件，特别是与 LLM 交互的应用：

调试问题 - 追踪 API 请求和响应
性能监控 - 测量响应时间和吞吐量
合规审计 - 记录敏感操作和数据访问
错误追踪 - 捕获和分析错误模式
成本控制 - 监控 Token 使用量和 API 费用
用户行为分析 - 了解用户如何与 AI 交互

LangChain4j 日志功能

LangChain4j 提供了丰富的日志功能：

请求日志 - 记录发送给 LLM 的完整请求
响应日志 - 记录从 LLM 返回的完整响应
Token 使用日志 - 记录每个请求的 Token 消耗
错误日志 - 记录 API 错误和异常
性能日志 - 记录请求耗时和吞吐量

日志级别

ERROR   - 错误级别，应用程序无法继续运行
WARN    - 警告级别，潜在问题，但应用仍可运行
INFO    - 信息级别，重要的业务逻辑信息
DEBUG   - 调试级别，详细的诊断信息
TRACE   - 跟踪级别，最详细的信息

日志配置

基础日志配置

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

/**
 * 基础日志示例
 */
public class BasicLoggingExample {

    private static final Logger logger = LoggerFactory.getLogger(BasicLoggingExample.class);

    public void doSomething() {
        logger.info("开始执行任务");

        try {
            // 业务逻辑
            String result = processData("输入数据");
            logger.info("任务执行成功: {}", result);
        } catch (Exception e) {
            logger.error("任务执行失败", e);
            throw new RuntimeException("任务失败", e);
        }
    }

    private String processData(String data) {
        logger.debug("处理数据: {}", data);
        return "处理结果: " + data;
    }

    public static void main(String[] args) {
        BasicLoggingExample example = new BasicLoggingExample();
        example.doSomething();
    }
}

配置请求和响应日志

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.model.chat.request.ChatRequest;
import dev.langchain4j.model.chat.response.ChatResponse;
import dev.langchain4j.service.AiServices;

/**
 * 配置请求和响应日志
 */
public class RequestResponseLogging {

    private final ChatModel model;

    public RequestResponseLogging(String apiKey) {
        this.model = OpenAiChatModel.builder()
                .apiKey(apiKey)
                .modelName("gpt-4o-mini")
                .logRequests(true)   // 启用请求日志
                .logResponses(true)  // 启用响应日志
                .build();
    }

    public void generateChat() {
        ChatResponse response = model.chat("你好");

        // 日志已自动记录
        System.out.println("响应: " + response.aiMessage().text());
    }

    public static void main(String[] args) {
        RequestResponseLogging logging = new RequestResponseLogging(
            System.getenv("OPENAI_API_KEY")
        );

        logging.generateChat();
    }
}

日志格式化

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.fasterxml.jackson.databind.ObjectMapper;

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

/**
 * 日志格式化
 */
public class LoggingFormatter {

    private static final Logger logger = LoggerFactory.getLogger(LoggingFormatter.class);
    private static final ObjectMapper mapper = new ObjectMapper();

    /**
     * 结构化日志方法
     */
    public static void logStructuredEvent(String eventName, Object eventData) {
        try {
            String json = mapper.writeValueAsString(eventData);
            logger.info("[{}] {}", eventName, json);
        } catch (Exception e) {
            logger.warn("无法序列化事件数据", e);
        }
    }

    /**
     * 格式化 Token 使用日志
     */
    public static void logTokenUsage(
            String modelId,
            int inputTokens,
            int outputTokens,
            int totalTokens
    ) {
        try {
            String json = mapper.writeValueAsString(Map.of(
                "timestamp", LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME),
                "model_id", modelId,
                "input_tokens", inputTokens,
                "output_tokens", outputTokens,
                "total_tokens", totalTokens,
                "estimated_cost", calculateCost(totalTokens, modelId)
            ));
            
            logger.info("Token 使用: {}", json);
        } catch (Exception e) {
            logger.warn("无法记录 Token 使用", e);
        }
    }

    /**
     * 计算成本
     */
    private static double calculateCost(int totalTokens, String modelId) {
        // 简化：假设每 1000 tokens $0.01
        return (double) totalTokens / 100000.0;
    }

    public static void main(String[] args) {
        // 记录 Token 使用
        logTokenUsage("gpt-4o-mini", 1500, 3000, 4500);

        // 记录结构化事件
        Map<String, Object> eventData = Map.of(
            "event_type", "chat",
            "user_id", "user123",
            "message_length", 100,
            "model", "gpt-4o-mini"
        );

        logStructuredEvent("user_chat", eventData);
    }
}

日志过滤和输出控制

配置日志级别

<!-- logback.xml -->
<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- 控制台日志级别 -->
    <root level="INFO">
        <appender-ref ref="CONSOLE" />
    </root>

    <!-- LangChain4j 日志级别 -->
    <logger name="dev.langchain4j" level="DEBUG" />

    <!-- 只记录警告和错误 -->
    <logger name="dev.langchain4j.model.chat.ChatModel" level="WARN" />
</configuration>

动态日志级别

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.event.Level;

/**
 * 动态日志级别
 */
public class DynamicLogLevel {

    private static final Logger logger = LoggerFactory.getLogger(DynamicLogLevel.class);

    /**
     * 根据配置设置日志级别
     */
    public static void setLogLevel(String loggerName, String level) {
        ch.qos.logback.classic.LoggerContext loggerContext = 
            (ch.qos.logback.classic.LoggerContext) LoggerFactory.getLogger(loggerName);

        Level targetLevel = Level.valueOf(level);
        loggerContext.setLevel(targetLevel);

        logger.info("已设置 {} 的日志级别为 {}", loggerName, level);
    }

    /**
     * 临时降低日志级别
     */
    public static void setTempLogLevel(String loggerName, String level, Runnable runnable) {
        ch.qos.logback.classic.LoggerContext loggerContext = 
            (ch.qos.logback.classic.LoggerContext) LoggerFactory.getLogger(loggerName);

        Level originalLevel = loggerContext.getLevel();
        Level targetLevel = Level.valueOf(level);

        try {
            loggerContext.setLevel(targetLevel);
            logger.info("临时降低 {} 的日志级别到 {}", loggerName, level);
            
            runnable.run();
        } finally {
            loggerContext.setLevel(originalLevel);
            logger.info("恢复 {} 的日志级别到 {}", loggerName, originalLevel);
        }
    }

    /**
     * 查询当前日志级别
     */
    public static String getLogLevel(String loggerName) {
        ch.qos.logback.classic.LoggerContext loggerContext = 
            (ch.qos.logback.classic.LoggerContext) LoggerFactory.getLogger(loggerName);

        return loggerContext.getLevel().toString();
    }

    public static void main(String[] args) {
        // 查询当前日志级别
        System.out.println("当前日志级别: " + getLogLevel("dev.langchain4j.model.chat"));

        // 设置新的日志级别
        setLogLevel("dev.langchain4j.model.chat", "TRACE");

        // 临时调试
        setTempLogLevel("dev.langchain4j", "DEBUG", () -> {
            logger.info("这是调试信息");
            logger.debug("这是调试信息");
        });
    }
}

日志与监控

性能监控日志

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.time.Duration;
import java.time.Instant;

/**
 * 性能监控日志
 */
public class PerformanceMonitor {

    private static final Logger logger = LoggerFactory.getLogger(PerformanceMonitor.class);

    /**
     * 性能计时器
     */
    public static class PerformanceTimer {
        private final String operationName;
        private final Instant startTime;
        private final Logger logger;
        private final boolean logDuration;
        private final long thresholdMs;

        public PerformanceTimer(String operationName, Logger logger, boolean logDuration, long thresholdMs) {
            this.operationName = operationName;
            this.logger = logger;
            this.logDuration = logDuration;
            this.thresholdMs = thresholdMs;
            this.startTime = Instant.now();
        }

        public void close() {
            Duration duration = Duration.between(startTime, Instant.now());
            long durationMs = duration.toMillis();

            if (logDuration) {
                if (durationMs > thresholdMs) {
                    logger.warn("操作 {} 耗时 {}ms (超过阈值 {}ms)", 
                            operationName, durationMs, thresholdMs);
                } else {
                    logger.info("操作 {} 耗时 {}ms", operationName, durationMs);
                }
            }

            logger.debug("操作 {} 开始时间: {}, 结束时间: {}", 
                        operationName, startTime, Instant.now());
        }
    }

    /**
     * 记录性能指标
     */
    public static void logMetrics(
            String operation,
            long durationMs,
            int tokenCount,
            int tokensPerSecond
    ) {
        logger.info("性能指标 - 操作: {}, 耗时: {}ms, Token 数: {}, TPS: {}", 
                    operation, durationMs, tokenCount, tokensPerSecond);
    }

    /**
     * 记录慢查询
     */
    public static void logSlowQuery(
            String query,
            long durationMs,
            long thresholdMs
    ) {
        if (durationMs > thresholdMs) {
            logger.warn("慢查询检测 - 查询: {}, 耗时: {}ms (阈值: {}ms), SQL: {}", 
                        query.substring(0, Math.min(100, query.length())), 
                        durationMs, thresholdMs, query);
        }
    }

    public static void main(String[] args) throws Exception {
        // 使用性能计时器
        try (PerformanceTimer timer = new PerformanceTimer("generateChat", logger, true, 1000)) {
            // 模拟耗时操作
            Thread.sleep(500);
            logger.info("生成聊天响应...");
        }

        // 记录性能指标
        logMetrics("generateChat", 500, 1000, 2);

        // 慢查询警告
        String query = "SELECT * FROM users WHERE name LIKE '%Java%'";
        logSlowQuery(query, 2000, 1000);
    }
}

Token 使用监控

import dev.langchain4j.data.message.*;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.data.message.tool.ToolExecutionRequest;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.atomic.AtomicLong;

/**
 * Token 使用监控
 */
public class TokenUsageMonitor {

    private static final Logger logger = LoggerFactory.getLogger(TokenUsageMonitor.class);
    private static final DateTimeFormatter formatter = DateTimeFormatter.of("yyyy-MM-dd HH:mm:ss");

    // 统计数据
    private static final AtomicInteger totalInputTokens = new AtomicInteger(0);
    private static final AtomicInteger totalOutputTokens = new AtomicInteger(0);
    private static final AtomicLong totalCost = new AtomicLong(0);
    private static final ConcurrentHashMap<String, ModelStats> modelStats = new ConcurrentHashMap<>();

    /**
     * 记录 Token 使用
     */
    public static void recordTokenUsage(
            String modelId,
            int inputTokens,
            int outputTokens
    ) {
        totalInputTokens.addAndGet(inputTokens);
        totalOutputTokens.addAndGet(outputTokens);
        int totalTokens = inputTokens + outputTokens;
        
        double cost = calculateCost(totalTokens, modelId);
        totalCost.addAndGet((long) (cost * 100));  // 转换为分

        // 记录详细日志
        logger.info("Token 使用 - 模型: {}, 输入: {}, 输出: {}, 总计: {}, 成本: ${}", 
                    modelId, inputTokens, outputTokens, totalTokens, String.format("%.4f", cost));

        // 更新模型统计
        modelStats.compute(modelId, (id, stats) -> {
            if (stats == null) {
                stats = new ModelStats();
            }
            stats.addUsage(inputTokens, outputTokens);
            return stats;
        });
    }

    /**
     * 获取统计摘要
     */
    public static String getStatsSummary() {
        int totalTokens = totalInputTokens.get() + totalOutputTokens.get();
        double totalCostDollars = totalCost.get() / 100.0;

        StringBuilder sb = new StringBuilder();
        sb.append("╔═══════════════════════════════════════════╗\n");
        sb.append("║           Token 使用统计                      ║\n");
        sb.append("╠═══════════════════════════════════════════╣\n");
        sb.append(String.format("║ 总输入 Token: %,10d                    ║\n", totalInputTokens.get()));
        sb.append(String.format("║ 总输出 Token: %,10d                    ║\n", totalOutputTokens.get()));
        sb.append(String.format("║ 总 Token: %,10d                            ║\n", totalTokens));
        sb.append(String.format("║ 总成本: $%.2f                           ║\n", totalCostDollars));
        sb.append("╠═══════════════════════════════════════════╣\n");

        // 按模型分组
        sb.append("║ 按模型统计:                                     ║\n");
        sb.append("╠═══════════════════════════════════════════╣\n");
        
        modelStats.forEach((modelId, stats) -> {
            sb.append(String.format("║ %s: %,10d tokens, $%.2f           ║\n",
                    modelId, stats.getTotalTokens(), stats.getCost()));
        });

        sb.append("╚═══════════════════════════════════════════╝\n");

        return sb.toString();
    }

    /**
     * 重置统计
     */
    public static void resetStats() {
        totalInputTokens.set(0);
        totalOutputTokens.set(0);
        totalCost.set(0);
        modelStats.clear();
        logger.info("Token 使用统计已重置");
    }

    /**
     * 导出统计数据
     */
    public static void exportStatsAsJson() {
        // 使用 JSON 处理将统计导出为 JSON
        // 这里简化实现
        logger.info("导出统计数据为 JSON");
    }

    /**
     * 计算成本
     */
    private static double calculateCost(int totalTokens, String modelId) {
        // 简化成本计算
        double pricePer1kTokens;

        if (modelId.contains("gpt-4")) {
            pricePer1kTokens = 0.03;  // $0.03 per 1K tokens
        } else if (modelId.contains("gpt-3.5")) {
            pricePer1kTokens = 0.002;  // $0.002 per 1K tokens
        } else {
            pricePer1kTokens = 0.001;  // 默认价格
        }

        return (totalTokens / 1000.0) * pricePer1kTokens;
    }

    /**
     * 模型统计
     */
    public static class ModelStats {
        private final AtomicInteger requestCount;
        private final AtomicInteger inputTokens;
        private final AtomicInteger outputTokens;

        public ModelStats() {
            this.requestCount = new AtomicInteger(0);
            this.inputTokens = new AtomicInteger(0);
            this.outputTokens = new AtomicInteger(0);
        }

        public void addUsage(int input, int output) {
            requestCount.incrementAndGet();
            inputTokens.addAndGet(input);
            outputTokens.addAndGet(output);
        }

        public int getRequestCount() { return requestCount.get(); }
        public int getInputTokens() { return inputTokens.get(); }
        public int getOutputTokens() { return outputTokens.get(); }
        public int getTotalTokens() { return getInputTokens() + getOutputTokens(); }
        public double getCost() {
            return calculateCost(getTotalTokens(), "gpt-4o");
        }
    }

    public static void main(String[] args) {
        // 模拟一些 Token 使用
        recordTokenUsage("gpt-4o-mini", 500, 300);
        recordTokenUsage("gpt-4o-mini", 800, 500);
        recordTokenUsage("gpt-3.5-turbo", 2000, 1500);

        // 显示统计
        System.out.println(getStatsSummary());

        // 定期输出统计
        logger.info("定期 Token 使用统计:\n{}", getStatsSummary());
    }
}

日志最佳实践

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

/**
 * 日志最佳实践
 */
public class LoggingBestPractices {

    private static final Logger logger = LoggerFactory.getLogger(LoggingBestPractices.class);

    /**
     * 最佳实践 1: 使用参数化日志
     */
    public void parameterizedLogging(String userId, String action, Object result) {
        // ✅ 好的做法
        logger.info("用户 {} 执行了操作 {}, 结果: {}", userId, action, result);

        // ❌ 不好的做法
        // logger.info("用户 " + userId + " 执行了操作 " + action + ", 结果: " + result);
    }

    /**
     * 最佳实践 2: 避免在循环中过度记录
     */
    public void loggingInLoops(List<String> items) {
        // ✅ 好的做法：记录汇总信息
        logger.info("处理 {} 个项目", items.size());
        
        for (String item : items) {
            processItem(item);
            // ❌ 不好的做法：每个循环都记录
            // logger.info("处理项目: " + item);
        }
        
        logger.info("所有项目处理完成");
    }

    /**
     * 最佳实践 3: 使用适当的日志级别
     */
    public void appropriateLogLevel(String message, Throwable error) {
        // ✅ 好的做法：根据情况选择级别
        if (error instanceof IllegalArgumentException) {
            logger.warn("参数错误: {}", message, error);
        } else if (error instanceof RuntimeException) {
            logger.error("运行时错误: {}", message, error);
        } else {
            logger.error("未知错误: {}", message, error);
        }
    }

    /**
     * 最佳实践 4: 结构化日志输出
     */
    public void structuredLogging(String eventType, String eventId, Object payload) {
        logger.info("{} | {} | {}", eventType, eventId, payload);
        // 输出: CHAT | 12345 | {"user": "张三", "message": "你好"}
    }

    /**
     * 最佳实践 5: 异常堆栈的合理使用
     */
    public void exceptionHandling(String context, Exception e) {
        // ✅ 好的做法：先记录消息，再记录异常
        logger.error("操作失败: {}", context, e);

        // ❌ 不好的做法：只记录异常
        // logger.error("操作失败", e);
    }

    /**
     * 最佳实践 6: 敏感信息的保护
     */
    public void sensitiveDataHandling(String password, String creditCard) {
        // ✅ 好的做法：不记录敏感信息
        logger.info("处理用户认证请求");
        // logger.info("密码: {}, 卡号: {}", password, creditCard);  // ❌

        // 如果必须记录，使用哈希
        logger.info("密码哈希: {}, 卡号哈希: {}", 
                    hashValue(password), hashValue(creditCard));
    }

    /**
     * 最佳实践 7: 性能关键路径
     */
    public void performanceCriticalPath(String operation) {
        long startTime = System.currentTimeMillis();
        
        // 执行操作
        String result = performOperation(operation);
        
        long duration = System.currentTimeMillis() - startTime;
        
        // 性能关键路径使用 DEBUG 或 INFO
        if (duration > 1000) {
            logger.warn("操作 {} 耗时 {}ms (性能警告)", operation, duration);
        } else {
            logger.debug("操作 {} 耗时 {}ms", operation, duration);
        }
    }

    /**
     * 最佳实践 8: 上下文信息
     */
    public void contextualLogging(String userId, String sessionId, String action) {
        // ✅ 好的做法：提供上下文
        logger.info("[用户: {}, 会话: {}] {}", userId, sessionId, action);
    }

    /**
     * 最佳实践 9: 审计日志
     */
    public void auditLogging(String action, String actor, String target, String result) {
        logger.info("审计日志 - 动作: {}, 执行者: {}, 目标: {}, 结果: {}", 
                    action, actor, target, result);
    }

    private String processItem(String item) {
        // 模拟处理
        return "处理结果: " + item;
    }

    private String performOperation(String operation) {
        // 模拟操作
        return "操作完成: " + operation;
    }

    private String hashValue(String value) {
        return "HASH_" + value.hashCode();
    }

    public static void main(String[] args) {
        LoggingBestPractices practices = new LoggingBestPractices();

        practices.parameterizedLogging("user123", "登录", "成功");
        System.out.println();

        practices.loggingInLoops(List.of("项目1", "项目2", "项目3", "项目4", "项目5"));
        System.out.println();

        try {
            practices.appropriateLogLevel("参数验证失败", new IllegalArgumentException("用户名不能为空"));
        } catch (IllegalArgumentException e) {
            logger.error("捕获异常: {}", e.getMessage());
        }
        System.out.println();

        practices.exceptionHandling("数据库连接", new RuntimeException("连接超时"));
        System.out.println();

        practices.sensitiveDataHandling("password123", "4111111111111111");
        System.out.println();

        practices.structuredLogging("CHAT", "event_123", Map.of(
            "user_id", "user123",
            "message", "你好"
        ));
        System.out.println();

        practices.auditLogging("删除用户", "admin", "user456", "成功");
    }
}

总结

本章要点

日志重要性
- 调试和问题排查
- 性能监控和优化
- 合规审计和成本控制
日志配置
- 请求和响应日志
- Token 使用监控
- 错误和警告日志
日志级别
- DEBUG - 详细诊断信息
- INFO - 重要业务逻辑
- WARN - 潜在问题
- ERROR - 应用错误
最佳实践
- 使用参数化日志
- 避免过度日志
- 使用适当的日志级别
- 保护敏感信息
监控
- 性能监控
- Token 使用统计
- 成本计算

下一步

在下一章节中，我们将学习：

可观测性配置
分布式追踪
性能分析和优化
错误处理和重试
生产环境部署建议

常见问题

Q1：如何启用 LangChain4j 的日志？ A：

配置 SLF4J 日志级别
在构建模型时设置 logRequests(true) 和 logResponses(true)
使用 -Dorg.slf4j.simpleLogger.logLevel=debug JVM 参数
配置 logback.xml 文件

Q2：如何减少日志的噪音？ A：

合理设置日志级别（生产环境使用 INFO 或 WARN）
避免在循环中过度记录
使用条件日志记录
配置日志过滤器

Q3：如何记录 Token 使用情况？ A：

启用响应日志（logResponses(true)）
从 ChatResponse 中获取 Token 使用量
创建自定义 Token 监控器
定期统计和报告

Q4：如何在生产环境中配置日志？ A：生产环境建议：

日志级别设置为 INFO 或 WARN
使用异步日志追加器
配置日志轮转和归档
避免敏感信息记录
集中日志到日志系统（如 ELK）

Q5：如何监控 API 成本？ A：

记录每个请求的 Token 使用量
计算每个模型的成本
设置成本告警阈值
定期生成成本报告
与预算进行比较和控制

参考资料

版权归属于 LangChat Team
官网：https://langchat.cn

关于

基础入门

核心概念

高级功能

工程实践

生产部署

高级主题

日志

15 - 日志

版本说明

学习目标

前置知识

核心概念

为什么需要日志？

LangChain4j 日志功能

日志级别

日志配置

基础日志配置

配置请求和响应日志

日志格式化

日志过滤和输出控制

配置日志级别

动态日志级别

日志与监控

性能监控日志

Token 使用监控

日志最佳实践

日志最佳实践

总结

本章要点

下一步

常见问题

参考资料

关于

基础入门

核心概念

高级功能

工程实践

生产部署

高级主题

​15 - 日志

​版本说明

​学习目标

​前置知识

​核心概念

​为什么需要日志？

​LangChain4j 日志功能

​日志级别

​日志配置

​基础日志配置

​配置请求和响应日志

​日志格式化

​日志过滤和输出控制

​配置日志级别

​动态日志级别

​日志与监控

​性能监控日志

​Token 使用监控

​日志最佳实践

​日志最佳实践

​总结

​本章要点

​下一步

​常见问题

​参考资料

15 - 日志

版本说明

学习目标

前置知识

核心概念

为什么需要日志？

LangChain4j 日志功能

日志级别

日志配置

基础日志配置

配置请求和响应日志

日志格式化

日志过滤和输出控制

配置日志级别

动态日志级别

日志与监控

性能监控日志

Token 使用监控

日志最佳实践

日志最佳实践

总结

本章要点

下一步

常见问题

参考资料