版本：Next

LMES 流程日志规范

概述

本规范文档旨在为LMES系统的流程日志提供标准化的记录、存储和管理方案。通过规范化的日志体系,实现流程追溯、问题诊断、性能监控等核心功能。该规范涵盖了日志架构设计、分类体系、存储策略、格式定义、接口使用以及最佳实践等方面。

一、日志架构设计

1.1 整体架构

LMES流程日志系统采用清晰的分层架构设计，通过NLog框架实现高度灵活的日志路由和存储机制。该架构从业务发起层到最终存储层形成完整的日志处理链路，各层之间职责明确，耦合度低，便于扩展和维护。

1.1.1 分层架构说明

LMES流程日志系统的架构共分为五个核心层次，从业务操作到最终日志存储形成完整闭环：

架构层次	核心组件	主要职责	实现方式
业务层	BusinessActivity等业务组件	触发日志记录需求，提供业务上下文信息	业务代码中通过`Flow.Logger`接口调用
日志服务层	Flow.Logger接口	封装日志记录逻辑，统一日志格式	提供标准化的日志记录方法（Info/Warn/Error等）
日志框架层	NLog记录器	实现日志的路由、过滤和格式化	根据配置将日志分发到不同目标
配置层	NLog-Flow.config配置文件	定义日志的输出规则、路径和格式	XML格式的配置文件，支持动态调整
存储层	文件系统	按工序和工位组织存储日志文件	分层目录结构，支持日志文件轮转

1.1.2 日志流转过程

日志从产生到存储的完整流转过程如下：

业务层的Activity组件在执行过程中，通过Flow.Logger接口记录各类业务事件和状态信息
日志服务层接收这些日志请求，按照预定义的格式进行标准化处理
处理后的日志被传递给NLog框架层，根据配置的规则进行过滤和路由
NLog框架根据NLog-Flow.config中的配置，将日志分发到相应的存储目标
最终，日志以文件形式存储在文件系统中，按工序和工位进行分类管理

这种分层设计使得LMES流程日志系统既能够满足业务需求的灵活性，又能保证日志管理的规范性和可追溯性。

1.2 日志分类体系

1.2.1 类别命名规范

CategoryName:记录器生成的消息的类别名称

日志类别	CategoryName模式	说明	示例
流程日志	`CMS.Plugin.Processflow.`工序名称`_`工位名称	工序流程执行日志	`CMS.Plugin.Processflow.PLA_工序1_工位1`
跟踪日志	`CMS.Plugin.TraceLogger.`工序名称`_`工位名称	变量跟踪相关日志	`CMS.Plugin.TraceLogger.PLA_工序1_工位1`

默认工序流程日志消息类别格式:CMS.Plugin.Processflow.工序名称_工位名称,默认 LMES基座 ProductionProcessProvider 已经按约定初始化。如果想要自定义,可按下图自定义修改。

1.2.2 日志级别定义

级别	用途	使用场景
Trace	详细调试信息	开发阶段变量跟踪
Debug	调试信息	开发阶段流程分析
Info	一般信息	正常流程执行记录
Warn	警告信息	异常情况但不影响流程
Error	错误信息	流程执行失败
Fatal	严重错误	系统级故障

二、日志存储策略

2.1 存储路径设计

LMES插件会默认提供NLog-Flow.config文件,用于将工序的流程日志按 {工序名称}_{工位名称} 分文件夹存储。

logs根目录/
├── flow_logs/
    ├── 工序1_工位1/
    │   ├── flowlog_2024-01-01.log
    │   ├── tracelog_2024-01-01.log
    │   └── warnlog_2024-01-01.log
    ├── 工序1_工位2/
    │   ├── flowlog_2024-01-01.log
    │   ├── tracelog_2024-01-01.log
    │   └── warnlog_2024-01-01.log
    ├── 工序2_工位1/
    │   ├── flowlog_2024-01-01.log
    │   ├── tracelog_2024-01-01.log
    │   └── warnlog_2024-01-01.log
    └── ...

启用上述配置后,流程日志存储路径如下图。注意:其他业务日志不会按 {工序}_{工位} 分文件夹存储,如果想要按此路径存储,可参照第一部分,配置日志记录器。

2.2 文件转转规则

文件类型	最大文件大小	最大存档数量	文件命名模式
流程日志	20MB	100个	`flowlog_`shortdate`.log`
警告日志	20MB	10个	`warnlog_`date:yyyy-MM-dd`.log`
跟踪日志	20MB	50个	`tracelog_`shortdate`.log`

2.3 NLog配置集成

后续基座的版本会默认将该配置文件作为NLog的扩展配置文件,加载到基座中。如果当前使用的基座还没有这个配置,可手动修改 $(CMSRootPath)/host/NLog.config 文件,添加如下代码:

<include file="NLog-Extend.config" ignoreErrors="true" />

2.4 NLog配置文件详解

2.4.1 核心配置要素

NLog-Flow.config （$(CMSRootPath)/plugins/cms.plugin.messuite/Configs/NLog-Flow.config 文件）文件包含以下关键配置:

变量定义:

basedir: 日志根目录,默认为 ../logs
logDirectory: 流程日志目录,值为 flow_logs
flowLogDirectory: 动态工序工位路径,通过替换logger名称生成 {工序}_{工位}
traceLogDirectory: 跟踪日志动态路径 {工序}_{工位}

目标配置:

flowLogfile: 流程日志文件目标 (Info级别)
warnLogfile: 警告日志文件目标 (Warn级别)
traceLogfile: 跟踪日志文件目标
consoleLog: 控制台输出目标 (开发阶段使用)

规则配置:

跟踪日志: CMS.Plugin.TraceLogger.* → traceLogfile
流程警告: CMS.Plugin.Processflow.* (Warn级别) → warnLogfile
流程日志: CMS.Plugin.Processflow.* (Info级别) → flowLogfile
控制台输出: CMS.Plugin.Processflow.* (Trace/Debug级别) → consoleLog

2.4.2 配置文件包含关系

环境	配置文件位置	包含关系
基座	`$(CMSRootPath)/host/NLog.config`	包含NLog-Extend.config
扩展	`NLog-Extend.config`	包含各插件流程配置
LMES插件	`plugins/cms.plugin.messuite/Configs/NLog-Flow.config`	独立配置
WCS插件	`plugins/cms.plugin.wcs/Configs/NLog-Flow.config`	独立配置

三、日志格式规范

3.1 标准格式定义

3.1.1 NLog日志格式

[${longdate}] [${level}] [${threadid}] [${logger}] ${message} ${exception}

字段说明:

${longdate}: 时间戳 (格式: yyyy-MM-dd HH:mm:ss.ffff)
${level}: 日志级别 (Trace/Debug/Info/Warn/Error/Fatal)
${threadid}: 线程ID
${logger}: 日志记录器名称 (CategoryName)
${message}: 日志消息内容
${exception}: 异常信息(如有)

3.1.2 消息内容格式

${流程编号},${工位名称}_${流程名称},【实例=${流程实例Id}】->【${执行步骤名}】-> ${流程业务消息}

字段说明:

流程编号: 流程定义的编号
工位名称: 当前工位名称
流程名称: 流程实例名称
流程实例Id: 流程实例的唯一标识
执行步骤名: 当前执行的Activity名称
流程业务消息: 业务相关的详细信息

3.2 格式示例对照表

进站流程日志示例

[2024-06-05 14:24:34.7023] [Info] [49] [CMS.Plugin.Processflow.PLA_工序1] 10001,PLA_GX1_工位1_普通工序流程,【实例=717568446925】->【进站信号监听】->Enter

效果如下图:(普通工序进站流程日志)

四、日志接口使用

4.1 IFlowLogger接口规范

对于流程日志的输出,LMES已经封装好了对应的日志接口,开发人员只需在对应业务代码中获取该接口,输出业务日志即可,无需再拼接流程对应的字段。

4.1.1 核心方法定义

方法	用途	参数说明
`LogMessage(string message, string stepName)`	记录一般信息	message: 业务消息，stepName: 执行步骤名
`LogWarningMessage(string message, string stepName)`	记录警告信息	同上
`LogErrorMessage(string message, string stepName)`	记录错误信息	同上
`LogExceptionMessage(Exception ex, string stepName)`	记录异常信息	ex: 异常对象，stepName: 执行步骤名

4.1.2 使用方式

在继承自 ProcessBusinessActivity 的Activity中,可直接使用 Flow.Logger 进行日志记录:

// 示例 1: 记录一般信息
Flow.Logger.LogMessage($"配方加工判断,工单号={currentOrder?.Code},产品型号={currentProduct?.Model}", Name);

// 示例 2: 记录警告信息
Flow.Logger.LogWarningMessage($"物料条码:{materialCode} 为空", Name);

// 示例 3: 记录错误信息
Flow.Logger.LogErrorMessage($"配方加工判断异常:{e.Message}", Name);

// 示例 4: 记录异常
Flow.Logger.LogExceptionMessage(ex, Name);

4.2 Activity集成

4.2.1 典型使用场景

1. 流程信息记录

Flow.Logger.LogMessage($"配方应用信息:产品型号={formulaApplyModel.ProductModel},配方编号={formulaApplyModel.FormulaCode},配方版本={formulaApplyModel.FormulaVersionName}", Name);

2. 异常情况处理

try
{
    // 业务逻辑
}
catch (Exception e)
{
    canEnterStation = false;
    errorMsg = $"操作异常:{e.Message}";
    Flow.Logger.LogErrorMessage(errorMsg, Name);
}

3. 调试信息输出

Flow.Logger.LogMessage($"采集参数:{string.Join(",", parameterCollectVarNames)},【TraceId={traceId}】", Name);

日志输出效果图如下:

五、最佳实践指南

5.1 日志记录原则

信息完整性: 确保包含足够的上下文信息
- 包含关键业务数据(工单号、产品型号、物料码等)
- 记录操作结果和状态
- 对于异常情况,记录详细的错误信息
格式一致性: 遵循标准的消息格式
- 使用统一的字段分隔符(,)
- 使用统一的键值分隔符(=)
- TraceId使用统一格式: 【TraceId={traceId}】
性能考虑: 避免过于频繁的日志记录
- 不在循环中记录大量日志
- 合理设置日志级别
- 生产环境避免记录Trace/Debug级别日志
安全性: 避免记录敏感信息
- 不记录密码、密钥等敏感数据
- 注意个人信息保护

5.2 开发指导

6.2.1 推荐的日志记录模式

// 正确示例: 包含关键信息和TraceId
Flow.Logger.LogMessage($"操作描述,关键参数={value},【TraceId={traceId}】", Name);

// 避免的模式: 缺少关键信息
Flow.Logger.LogMessage("操作完成", Name); // 不推荐

5.2.2 异常处理模式

try
{
    // 业务逻辑
}
catch (Exception e)
{
    canEnterStation = false;
    errorMsg = $"操作异常:{e.Message}";
    Flow.Logger.LogErrorMessage(errorMsg, Name);
    // 或者使用
Flow.Logger.LogExceptionMessage(e, Name);
}

5.2.3 TraceId使用规范

对于需要进行关联分析的操作,应使用TraceId:

var traceId = Flow.Instance.GetTraceId();
Flow.Logger.LogMessage($"操作描述,【TraceId={traceId}】", Name);
// 执行业务操作时传入traceId
await service.WriteValueAsync(this, parameters, cancellationToken, retryCount, retryDelay, traceId);

5.3 环境配置建议

5.3.1 开发环境配置

启用控制台输出(Trace/Debug级别)
详细的异常堆栈信息
较短的日志转转周期

5.3.2 生产环境配置

禁用控制台输出
仅记录Info及以上级别
合理的文件大小和存档限制

5.4 运维监控建议

日志文件监控: 监控日志文件大小和转转情况
错误日志告警: 对Error级别日志设置告警
性能指标关联: 结合LmesMetrics进行性能分析
定期清理: 制定日志文件清理策略

六、性能监控集成

6.1 日志与指标关联

LMES流程日志系统与性能监控系统(LmesMetrics)集成,实现日志记录和性能指标收集的统一管理:

6.2 TraceId追踪机制

TraceId是进行问题追踪和性能分析的关键机制:

使用场景:

配方参数下发
变量值读写操作
分布式操作追踪
性能瓶颈分析

示例:

var traceId = Flow.Instance.GetTraceId();
Flow.Logger.LogMessage($"采集参数:{string.Join(",", parameterCollectVarNames)},【TraceId={traceId}】", Name);
await variableService.WriteValueAsync(this, parameters, cancellationToken, retryCount, retryDelay, traceId);

所有相关的日志记录都包含TraceId,便于问题追踪和性能分析。

6.3 性能指标类型

指标类型	用途	示例
Counter	计数器,用于统计事件发生次数	进站次数、出站次数
Histogram	直方图,用于统计数值分布	流程耗时分布
Gauge	仪表,用于记录当前值	当前进站产品数

七、故障诊断指南

7.1 常见问题排查

7.1.1 日志文件未按 `{工序}_{工位}` 分文件夹

原因分析:

NLog-Extend.config未正确包含
CategoryName设置不正确,未包含工位名称
NLog-Flow.config配置错误

解决方案:

检查基座NLog.config是否包含NLog-Extend.config
验证ProductionProcessProvider中CategoryName设置,确保格式为 {工序}_{工位}
检查NLog-Flow.config中的logger名称匹配规则

7.1.2 日志格式不正确

原因分析:

自定义Logger未遵循IFlowLogger接口
消息格式化逻辑错误
未使用Flow.Logger接口

解决方案:

使用Flow.Logger而非自定义Logger
确保传入正确的stepName参数
遵循标准的消息格式规范

7.1.3 日志文件未生成

原因分析:

日志级别设置过高
文件路径权限问题
NLog配置加载失败

解决方案:

检查NLog-Flow.config中的minlevel设置
验证日志目录的读写权限

7.2 日志分析工具

7.2.1 文本搜索

使用grep等工具快速定位:

# 搜索错误日志
grep "\[Error\]" flowlog_2024-01-01.log

# 搜索特定产品码
grep "SN001" flowlog_2024-01-01.log

# 搜索TraceId
grep "TraceId=12345" flowlog_2024-01-01.log

7.2.2 TraceId追踪

通过TraceId关联相关日志:

# 提取TraceId
grep -o "TraceId=[0-9]*" flowlog_2024-01-01.log | sort | uniq

# 查看特定TraceId的所有日志
grep "TraceId=12345" flowlog_2024-01-01.log

7.2.3 时间戳分析

分析流程执行时间分布:

# 提取时间戳
grep -o "\[20[0-9-: .]*\]" flowlog_2024-01-01.log

# 统计每小时日志数量
grep -o "\[20[0-9-]* [0-9]*:" flowlog_2024-01-01.log | cut -d' ' -f2 | cut -d':' -f1 | sort | uniq -c

7.2.4 错误统计

统计各类错误的发生频率:

# 统计错误级别日志
grep -c "\[Error\]" flowlog_2024-01-01.log
grep -c "\[Warn\]" flowlog_2024-01-01.log

# 统计具体错误类型
grep "\[Error\]" flowlog_2024-01-01.log | grep -o "异常.*" | sort | uniq -c | sort -rn

7.3 故障处理流程

7.3.1 日志排查步骤

确定问题范围
- 确认发生问题的工序和工位
- 确定问题发生时间
- 确认影响范围
查找相关日志
- 根据 {工序}_{工位} 定位日志文件夹
- 根据时间戳缩小范围
- 搜索关键字(产品码、工单号等)
分析日志内容
- 查看错误日志详情
- 分析异常堆栈信息
- 追踪TraceId相关操作
定位问题原因
- 对比正常和异常日志
- 检查配置和参数
- 验证业务逻辑
解决和验证
- 实施修复方案
- 验证问题是否解决
- 记录解决方案

7.4 预防性监控

实时监控
- 监控错误日志增长趋势
- 设置错误率阈值告警
- 监控日志文件增长速度
定期分析
- 每日日志摘要分析
- 每周趋势分析报告
- 每月问题总结和优化
容量规划
- 预估日志增长趋势
- 合理配置存储空间
- 制定清理策略

八、总结

本规范文档提供了LMES流程日志的全面指导,从架构设计到实际应用,从开发规范到运维监控。通过遵循本规范,可以:

提高日志质量: 统一的格式和完整的信息便于分析
加快问题定位: TraceId和结构化日志提高排查效率
保障系统稳定: 及时发现和解决问题
优化系统性能: 结合性能指标进行持续优化

建议开发人员在日常开发中严格遵循本规范,运维人员定期检查日志质量和系统运行状态,持续改进和完善日志系统。

概述​

一、日志架构设计​

1.1 整体架构​

1.1.1 分层架构说明​

1.1.2 日志流转过程​

1.2 日志分类体系​

1.2.1 类别命名规范​

1.2.2 日志级别定义​

二、日志存储策略​

2.1 存储路径设计​

2.2 文件转转规则​

2.3 NLog配置集成​

2.4 NLog配置文件详解​

2.4.1 核心配置要素​

2.4.2 配置文件包含关系​

三、日志格式规范​

3.1 标准格式定义​

3.1.1 NLog日志格式​

3.1.2 消息内容格式​

3.2 格式示例对照表​

四、日志接口使用​

4.1 IFlowLogger接口规范​

4.1.1 核心方法定义​

4.1.2 使用方式​

4.2 Activity集成​

4.2.1 典型使用场景​

五、最佳实践指南​

5.1 日志记录原则​

5.2 开发指导​

6.2.1 推荐的日志记录模式​

5.2.2 异常处理模式​

5.2.3 TraceId使用规范​

5.3 环境配置建议​

5.3.1 开发环境配置​

5.3.2 生产环境配置​

5.4 运维监控建议​

六、性能监控集成​

6.1 日志与指标关联​

6.2 TraceId追踪机制​

6.3 性能指标类型​

七、故障诊断指南​

7.1 常见问题排查​

7.1.1 日志文件未按 {工序}_{工位} 分文件夹​

7.1.2 日志格式不正确​

7.1.3 日志文件未生成​

7.2 日志分析工具​

7.2.1 文本搜索​

7.2.2 TraceId追踪​

7.2.3 时间戳分析​

7.2.4 错误统计​

7.3 故障处理流程​

7.3.1 日志排查步骤​

7.4 预防性监控​

八、总结​

概述

一、日志架构设计

1.1 整体架构

1.1.1 分层架构说明

1.1.2 日志流转过程

1.2 日志分类体系

1.2.1 类别命名规范

1.2.2 日志级别定义

二、日志存储策略

2.1 存储路径设计

2.2 文件转转规则

2.3 NLog配置集成

2.4 NLog配置文件详解

2.4.1 核心配置要素

2.4.2 配置文件包含关系

三、日志格式规范

3.1 标准格式定义

3.1.1 NLog日志格式

3.1.2 消息内容格式

3.2 格式示例对照表

四、日志接口使用

4.1 IFlowLogger接口规范

4.1.1 核心方法定义

4.1.2 使用方式

4.2 Activity集成

4.2.1 典型使用场景

五、最佳实践指南

5.1 日志记录原则

5.2 开发指导

6.2.1 推荐的日志记录模式

5.2.2 异常处理模式

5.2.3 TraceId使用规范

5.3 环境配置建议

5.3.1 开发环境配置

5.3.2 生产环境配置

5.4 运维监控建议

六、性能监控集成

6.1 日志与指标关联

6.2 TraceId追踪机制

6.3 性能指标类型

七、故障诊断指南

7.1 常见问题排查

7.1.1 日志文件未按 `{工序}_{工位}` 分文件夹

7.1.2 日志格式不正确

7.1.3 日志文件未生成

7.2 日志分析工具

7.2.1 文本搜索

7.2.2 TraceId追踪

7.2.3 时间戳分析

7.2.4 错误统计

7.3 故障处理流程

7.3.1 日志排查步骤

7.4 预防性监控

八、总结