Imported from alibaba/loongcollector (skills/selfmonitor/SKILL.md). Install upstream with npx skills add alibaba/loongcollector --skill selfmonitor. Copyright stays with the author.

自监控代码标准

你是一个自监控代码质量专家，负责确保LoongCollector中所有代码正确使用自监控功能。你的职责是检查指标使用、告警使用、代码风格和实现逻辑的正确性。

指标命名规范

命名格式

变量名基本格式: {模块}_{指标内容描述}_{单位}（全部大写）

变量内容基本格式: {指标内容描述}_{单位}（全部小写）

例如：

const string METRIC_RUNNER_FLUSHER_IN_RAW_SIZE_BYTES = "in_raw_size_bytes";

模块前缀分类

• agent_: 进程级指标，描述整个Agent的状态
• pipeline_: Pipeline级指标，描述数据流水线的状态
• plugin_: 插件级指标，描述具体插件的状态
• component_: 组件级指标，描述内部组件的状态
• runner_: Runner级指标，描述运行器的状态

单位分类规范

根据指标类型和用途，使用以下标准单位：

计数类指标

• _total: 累计总数（默认单位，无单位时使用）
  • 示例: input_records_total, send_success_total, error_count_total

大小类指标

• _bytes: 字节数
  • 示例: input_size_bytes, memory_used_bytes, file_size_bytes
• _mb: 兆字节（内存使用等）
  • 示例: agent_memory_used_mb, go_memory_used_mb

时间类指标

• _ms: 毫秒（处理时间、延迟等）
  • 示例: process_time_ms, send_delay_ms, read_delay_ms
• _s: 秒（长时间间隔）
  • 示例: uptime_s, last_run_time_s

比率类指标

• _percent: 百分比
  • 示例: cpu_usage_percent, memory_usage_percent
• _ps: 每秒（速率）
  • 示例: send_bytes_ps, process_lines_ps

状态类指标

• _flag: 标志位（0或1）
  • 示例: enabled_flag, valid_flag
• _state: 状态值
  • 示例: register_state, connection_state

指标内容描述规范

• 使用下划线分隔的英文描述
• 动词使用过去分词形式：processed, sent, failed
• 名词使用复数形式：events, records, errors
• 避免缩写，使用完整单词

正确示例:

METRIC_AGENT_CPU_PERCENT
METRIC_AGENT_MEMORY_USED_MB
METRIC_PLUGIN_IN_EVENTS_TOTAL
METRIC_PLUGIN_OUT_SIZE_BYTES
METRIC_PIPELINE_PROCESSORS_TOTAL_PROCESS_TIME_MS
METRIC_RUNNER_LAST_RUN_TIME
METRIC_COMPONENT_QUEUE_SIZE

错误示例:

// 缺少模块前缀
CPU_PERCENT
// 单位不规范
METRIC_AGENT_MEMORY_USED_KB
// 命名不清晰
METRIC_PLUGIN_DATA
// 缩写不规范
METRIC_AGENT_MEM_MB

Label命名规范

Label Key格式: METRIC_LABEL_KEY_{描述}

常用Label Key:

METRIC_LABEL_KEY_PROJECT        // 项目名
METRIC_LABEL_KEY_LOGSTORE       // 日志库名
METRIC_LABEL_KEY_PIPELINE_NAME  // 流水线名
METRIC_LABEL_KEY_PLUGIN_TYPE    // 插件类型
METRIC_LABEL_KEY_PLUGIN_ID      // 插件ID
METRIC_LABEL_KEY_FILE_NAME      // 文件名
METRIC_LABEL_KEY_FILE_DEV       // 设备号
METRIC_LABEL_KEY_FILE_INODE     // inode号
METRIC_LABEL_KEY_REGION         // 地域
METRIC_LABEL_KEY_RUNNER_NAME    // 运行器名

告警等级使用规范

告警等级定义

根据PR #2319的设计，告警等级分为3个级别：

C++告警使用规范

正确使用方式:

// 使用新的等级化接口
AlarmManager::GetInstance()->SendAlarmWarning(LOGTAIL_CONFIG_ALARM, "配置解析失败");
AlarmManager::GetInstance()->SendAlarmError(PROCESS_QUEUE_BUSY_ALARM, "处理队列繁忙");
AlarmManager::GetInstance()->SendAlarmCritical(CATEGORY_CONFIG_ALARM, "配置加载失败");

错误使用方式:

// 不要使用旧的SendAlarm接口
AlarmManager::GetInstance()->SendAlarm(LOGTAIL_CONFIG_ALARM, "配置解析失败");

Go告警使用规范

正确使用方式:

// 使用等级化接口
logger.Warning(ctx, selfmonitor.CategoryConfigAlarm, "配置解析失败")
logger.Error(ctx, selfmonitor.ProcessQueueBusyAlarm, "处理队列繁忙") 
logger.Critical(ctx, selfmonitor.CategoryConfigAlarm, "配置加载失败")

错误使用方式:

// 不要使用未定义的告警类型
logger.Warning(ctx, "UNKNOWN_ALARM", "未知告警")

新增指标操作指南

C++新增指标步骤

1. 定义指标常量:

   • 在 core/monitor/metric_constants/MetricConstants.h 中添加指标常量
   • 在对应的 .cpp 文件中实现常量值

2. 创建MetricsRecordRef:

   // 在类中定义MetricsRecordRef
   MetricsRecordRef mMetricsRecordRef;
   
   // 在初始化函数中创建MetricsRecordRef
   void Plugin::Init() {
       // 准备labels
       MetricLabelsPtr labels = std::make_shared<MetricLabels>();
       labels->emplace_back(METRIC_LABEL_KEY_PROJECT, mProject);
       labels->emplace_back(METRIC_LABEL_KEY_PLUGIN_TYPE, mPluginType);
       
       // 创建MetricsRecordRef
       WriteMetrics::GetInstance()->PrepareMetricsRecordRef(
           mMetricsRecordRef, 
           std::move(labels), 
           nullptr  // dynamicLabels
       );
   }

3. 创建指标对象:

   // 在类中定义指标指针
   CounterPtr mCounterPtr;
   IntGaugePtr mGaugePtr;
   
   // 在MetricsRecordRef创建后，commit前创建指标对象
   void Plugin::Init() {
       // ... 创建MetricsRecordRef的代码 ...
       
       // 创建指标对象（必须在commit前）
       mCounterPtr = mMetricsRecordRef.CreateCounter(METRIC_PLUGIN_IN_EVENTS_TOTAL);
       mGaugePtr = mMetricsRecordRef.CreateIntGauge(METRIC_PLUGIN_QUEUE_SIZE);
       
       // 提交MetricsRecordRef，之后不能再创建新指标
       mMetricsRecordRef.Commit();
   }

4. 更新指标值:

   // 使用宏进行安全更新
   void Plugin::ProcessData() {
       // 检查MetricsRecordRef是否已提交
       if (mMetricsRecordRef.IsCommitted()) {
           ADD_COUNTER(mCounterPtr, value);
           SET_GAUGE(mGaugePtr, value);
           ADD_GAUGE(mGaugePtr, delta);
       }
   }

重要注意事项:

• MetricsRecordRef必须在commit前创建所有指标对象
• commit后不能再调用CreateCounter、CreateIntGauge等方法
• 使用IsCommitted()检查状态，避免在已提交后创建指标
• 若某个Gauge类型的指标对应的参数的默认值非0，需要在Init的时候先将值Set一次

Go新增指标步骤

1. 定义指标常量:

   • 在 pkg/selfmonitor/metrics_constants_*.go 中添加指标常量

   // 在 metrics_constants_plugin.go 中添加
   const (
       MetricPluginInEventsTotal = "in_events_total"
       MetricPluginQueueSize     = "queue_size"
   )

2. 注册指标:

   // 在插件结构体中定义指标
   type Plugin struct {
       pipeline.PluginContext
       metricCounter selfmonitor.CounterMetric
       metricGauge   selfmonitor.GaugeMetric
       // ... 其他字段
   }
   
   // 在插件初始化时注册指标
   func (p *Plugin) InitMetricRecord(pluginMeta *pipeline.PluginMeta) {
       // 获取插件通用labels
       labels := pipeline.GetPluginCommonLabels(p.Config.Context, pluginMeta)
       
       // 注册MetricsRecord
       p.MetricRecord = p.Config.Context.RegisterMetricRecord(labels)
       
       // 创建并注册指标对象
       p.metricCounter = selfmonitor.NewCounterMetricAndRegister(p.MetricRecord, selfmonitor.MetricPluginInEventsTotal)
       p.metricGauge = selfmonitor.NewGaugeMetricAndRegister(p.MetricRecord, selfmonitor.MetricPluginQueueSize)
   }

3. 更新指标值:

   // 更新指标值
   func (p *Plugin) ProcessData() {
       // 安全更新指标值
       if p.metricCounter != nil {
           p.metricCounter.Add(1)
       }
       if p.metricGauge != nil {
           p.metricGauge.Set(queueSize)
       }
   }

重要注意事项:

• 使用InitMetricRecord方法初始化指标
• 通过NewCounterMetricAndRegister和NewGaugeMetricAndRegister创建并注册指标
• 更新指标值前检查对象是否为nil
• 指标会自动上报，无需手动提交

新增告警类型操作指南

C++新增告警类型步骤

1. 在 core/monitor/AlarmManager.h 中添加告警类型:

   enum AlarmType {
       // ... 现有类型
       NEW_ALARM_TYPE = 70,  // 使用下一个可用数字
       ALL_LOGTAIL_ALARM_NUM = 71  // 更新总数
   };

2. 在告警消息类型映射中添加:

   // 在 AlarmManager.cpp 的构造函数中添加
   AlarmManager::AlarmManager() {
       // ... 现有代码 ...
       mMessageType.push_back("NEW_ALARM_TYPE");  // 添加新告警类型
   }

3. 使用告警:

   // 在需要发送告警的地方
   void SomeFunction() {
       // 使用等级化接口发送告警
       AlarmManager::GetInstance()->SendAlarmWarning(
           NEW_ALARM_TYPE, 
           "具体错误信息: " + errorDetails
       );
       
       // 或者使用其他等级
       AlarmManager::GetInstance()->SendAlarmError(
           NEW_ALARM_TYPE, 
           "严重错误信息"
       );
   }

重要注意事项:

• 告警类型枚举值必须连续，不能跳跃
• 更新ALL_LOGTAIL_ALARM_NUM为新的总数
• 在mMessageType向量中添加对应的字符串
• 使用等级化接口，避免使用旧的SendAlarm方法

Go新增告警类型步骤

1. 在 pkg/selfmonitor/alarm_constants.go 中添加告警类型:

   const (
       // ... 现有类型
       NewAlarmType AlarmType = "NEW_ALARM_TYPE"
   )

2. 使用告警:

   // 在需要发送告警的地方
   func (p *Plugin) ProcessData() error {
       if err := p.doSomething(); err != nil {
           // 使用等级化接口发送告警
           logger.Warning(ctx, selfmonitor.NewAlarmType, 
               fmt.Sprintf("处理数据失败: %v", err))
           return err
       }
       
       // 或者使用其他等级
       if p.isCriticalError() {
           logger.Critical(ctx, selfmonitor.NewAlarmType, 
               "严重错误，需要立即处理")
       }
       
       return nil
   }

重要注意事项:

• 告警类型字符串必须与C++中的枚举名称一致
• 使用等级化接口：Warning、Error、Critical
• 告警消息应该包含具体的错误信息
• 避免在循环中频繁发送相同告警

代码风格规范

C++代码风格

• 命名规范:

  • 类名使用PascalCase: AlarmManager, MetricRecord
  • 函数名使用camelCase: SendAlarmWarning, GetInstance
  • 常量使用SCREAMING_SNAKE_CASE: METRIC_AGENT_CPU
  • 成员变量使用m前缀: mAlarmBufferMutex, mAllAlarmMap

• 代码结构:

  • 头文件声明与实现分离
  • 使用namespace logtail包装
  • 适当的const和constexpr使用

Go代码风格

• 命名规范:

  • 包名使用小写: selfmonitor
  • 类型名使用PascalCase: AlarmType, AlarmLevel
  • 函数名使用camelCase: Record, SerializeToPb
  • 常量使用SCREAMING_SNAKE_CASE: AlarmLevelWarning

• 代码结构:

  • 适当的错误处理
  • 使用sync.Mutex保护并发访问
  • 清晰的注释和文档

指标使用最佳实践

指标创建最佳实践

1. 在合适的生命周期创建指标:

   C++示例:

   class Plugin {
   private:
       MetricsRecordRef mMetricsRecordRef;
       CounterPtr mProcessedCounter;
       IntGaugePtr mQueueSizeGauge;
       
   public:
       bool Init() {
           // 在Init方法中创建MetricsRecordRef和指标对象
           MetricLabelsPtr labels = std::make_shared<MetricLabels>();
           labels->emplace_back(METRIC_LABEL_KEY_PLUGIN_TYPE, "input_file");
           
           WriteMetrics::GetInstance()->PrepareMetricsRecordRef(
               mMetricsRecordRef, std::move(labels), nullptr);
           
           // 创建指标对象
           mProcessedCounter = mMetricsRecordRef.CreateCounter(METRIC_PLUGIN_PROCESSED_TOTAL);
           mQueueSizeGauge = mMetricsRecordRef.CreateIntGauge(METRIC_PLUGIN_QUEUE_SIZE);
           
           // 提交MetricsRecordRef
           mMetricsRecordRef.Commit();
           return true;
       }
   };

   Go示例:

   type Plugin struct {
       pipeline.PluginContext
       processedCounter selfmonitor.CounterMetric
       queueSizeGauge   selfmonitor.GaugeMetric
   }
   
   func (p *Plugin) InitMetricRecord(pluginMeta *pipeline.PluginMeta) {
       // 获取插件通用labels
       labels := pipeline.GetPluginCommonLabels(p.Config.Context, pluginMeta)
       
       // 注册MetricsRecord
       p.MetricRecord = p.Config.Context.RegisterMetricRecord(labels)
       
       // 创建并注册指标对象
       p.processedCounter = selfmonitor.NewCounterMetricAndRegister(p.MetricRecord, selfmonitor.MetricPluginProcessedTotal)
       p.queueSizeGauge = selfmonitor.NewGaugeMetricAndRegister(p.MetricRecord, selfmonitor.MetricPluginQueueSize)
   }

2. 使用安全的更新宏:

   // 使用宏确保指针非空
   void Plugin::ProcessData() {
       // 检查MetricsRecordRef状态
       if (mMetricsRecordRef.IsCommitted()) {
           ADD_COUNTER(mProcessedCounter, 1);
           SET_GAUGE(mQueueSizeGauge, currentQueueSize);
       }
   }
   
   // 错误示例：直接调用可能为空指针
   void Plugin::ProcessDataWrong() {
       mProcessedCounter->Add(1);  // 危险：可能为空指针
   }

3. 避免频繁创建指标对象:

   // 正确：在初始化时创建一次
   class Plugin {
       CounterPtr mCounter;  // 成员变量，只创建一次
       
   public:
       void Init() {
           mCounter = mMetricsRecordRef.CreateCounter(METRIC_NAME);
           mMetricsRecordRef.Commit();
       }
       
       void ProcessData() {
           ADD_COUNTER(mCounter, 1);  // 重复使用
       }
   };
   
   // 错误：每次调用都创建新指标
   void ProcessDataWrong() {
       auto counter = mMetricsRecordRef.CreateCounter(METRIC_NAME);  // 错误：频繁创建
       counter->Add(1);
   }

告警使用最佳实践

1. 选择合适的告警等级:

   // 正确：根据影响程度选择等级
   void ProcessData() {
       if (parseError) {
           // warning: 单点解析失败，不影响整体流程
           AlarmManager::GetInstance()->SendAlarmWarning(
               PARSE_LOG_FAIL_ALARM, 
               "单行解析失败: " + errorLine
           );
       }
       
       if (queueFull) {
           // error: 队列满，影响处理流程
           AlarmManager::GetInstance()->SendAlarmError(
               PROCESS_QUEUE_BUSY_ALARM, 
               "处理队列已满，当前大小: " + std::to_string(queueSize)
           );
       }
       
       if (configLoadFailed) {
           // error: 单个采集配置加载失败，影响一个流水线，可能导致客户资损
           AlarmManager::GetInstance()->SendAlarmCritical(
               CATEGORY_CONFIG_ALARM, 
               "采集配置加载失败: " + configError
           );
       }
   }

2. 提供有意义的告警消息:

   // 正确：包含具体错误信息和解决建议
   void HandleFileError(const std::string& filePath, int errorCode) {
       std::string message = "文件读取失败: " + filePath + 
                           ", 错误码: " + std::to_string(errorCode) +
                           ", 建议检查文件权限和路径";
       
       AlarmManager::GetInstance()->SendAlarmError(
           OPEN_LOGFILE_FAIL_ALARM, 
           message
       );
   }
   
   // 错误：告警消息过于简单
   void HandleFileErrorWrong(const std::string& filePath) {
       AlarmManager::GetInstance()->SendAlarmError(
           OPEN_LOGFILE_FAIL_ALARM, 
           "文件错误"  // 太简单，无法定位问题
       );
   }

3. 避免告警风暴:

   // 正确：使用限流机制避免告警风暴
   class AlarmLimiter {
   private:
       std::map<AlarmType, time_t> mLastAlarmTime;
       static const int ALARM_INTERVAL_SEC = 60;  // 60秒内不重复发送相同告警
       
   public:
       void SendAlarmWithLimit(AlarmType type, const std::string& message) {
           time_t now = time(nullptr);
           auto it = mLastAlarmTime.find(type);
           
           if (it == mLastAlarmTime.end() || 
               now - it->second > ALARM_INTERVAL_SEC) {
               
               AlarmManager::GetInstance()->SendAlarmError(type, message);
               mLastAlarmTime[type] = now;
           }
       }
   };
   
   // 错误：在循环中频繁发送相同告警
   void ProcessDataWrong() {
       for (auto& item : dataList) {
           if (item.hasError) {
               // 错误：可能产生大量重复告警
               AlarmManager::GetInstance()->SendAlarmError(
                   PROCESS_DATA_FAIL_ALARM, 
                   "数据处理失败"
               );
           }
       }
   }

检查清单

在提交涉及自监控的代码前，请确保：

1. 指标命名:

   • 指标名称符合命名规范
   • 使用了正确的模块前缀
   • 单位使用标准格式
   • Label名称符合命名规范

2. 告警使用:

   • 使用正确的告警等级接口
   • 告警等级与严重程度匹配
   • 避免使用已废弃的接口
   • 告警消息有意义

3. 代码实现:

   • 指标能正常创建和更新
   • 告警能正常记录和聚合
   • 使用了安全的更新宏
   • 错误处理完善

4. 性能考虑:

   • 避免频繁创建指标对象
   • 避免告警风暴
   • 指标更新不会影响主流程性能

5. 测试验证:

   • 新增指标能正常上报
   • 新增告警能正常触发
   • 数据格式符合预期
   • 性能影响可接受