OneUptime Logs Monitor（日志监控器）完全指南：基于 OpenTelemetry 的日志告警配置与实现原理

OneUptime Logs Monitor日志监控器完全指南基于 OpenTelemetry 的日志告警配置与实现原理【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本指南以 OneUptime 官方文档 logs-monitor.md 为骨架系统讲解日志监控器的核心概念、创建流程、全部配置项遥测服务、日志过滤器、严重级别、时间窗口、监控判据Log Count 过滤类型与五种条件以及三类实战告警示例并结合仓库源码揭示其底层查询编译与阈值评估原理。读完本文你将能够在 OneUptime 中独立搭建错误日志突增FATAL 日志出现特定错误消息持续出现等日志告警并理解告警从配置到触发的完整链路。日志监控器Logs Monitor概述日志监控允许你持续监控应用程序日志并根据**日志模式pattern、日志数量count与严重级别severity level**触发告警。OneUptime 会评估来自你遥测服务的日志并将其与你配置的监控判据进行比对。在 OneUptime 中Logs是 MonitorType 枚举 中专门面向遥测数据的监控类型之一与之并列的还有Metrics、Traces、Exceptions、Security Events。从源码结构看它被归类在Telemetry监控类别下见MonitorTypeHelper.getMonitorTypeCategories()其官方描述为Alert on log volume or matching log content from any source.针对任意来源的日志量或匹配的日志内容告警搜索关键词keywords包括log、otel、opentelemetry、log query、error log、search logs这意味着你在监控类型选择器中直接输入这些词即可快速定位。日志监控器在一个时间窗口内搜索并计数符合特定过滤条件的日志从而支持针对错误日志突增error log spikes告警监控特定的日志模式或消息按严重级别跟踪日志量按服务、属性attributes和内容过滤日志从日志模式中识别应用程序问题数据从哪来OpenTelemetry 遥测管线日志监控器本身不采集日志它的数据源是已经通过OpenTelemetry上报到 OneUptime 的遥测日志。因此创建日志监控器的前提是你的应用程序已经配置了 OpenTelemetry SDK / Collector并将日志导出到 OneUptime 的遥测接入端点。在 OneUptime 中日志以结构化形式存储在分析型数据表ClickHouse 的 MergeTree 引擎表中。日志模型 Log.ts 定义了日志行包含的字段其中与日志监控器直接相关的核心列包括字段说明与监控器的关系projectId项目 ID租户隔离列查询的默认边界primaryEntityId服务 / 主机 / Pod 等资源 ID对应遥测服务过滤telemetryServiceIdstime/timeUnixNano日志产生时间对应时间窗口过滤lastXSecondsOfLogsseverityText/severityNumber严重级别文本与数值对应严重级别过滤severityTextsattributes/attributeKeys自定义属性键值对对应属性过滤attributesentityKeys实体稳定键service/host/k8s.pod/container 等对应实体/清单项过滤entityKeysbody日志消息体对应正文文本搜索过滤body值得注意的是日志表按(projectId, time, primaryEntityId)排序并分片cityHash64(projectId, primaryEntityId, time)body列带有 TokenBF 跳过索引severityText为低基数列并配有 Set 跳过索引这些设计保证了日志监控器在按服务 严重级别 时间范围过滤时的高效查询。创建日志监控器在 OneUptime Dashboard 中创建日志监控器的步骤如下进入 Dashboard 的Monitors监控器页面点击Create Monitor创建监控器在监控类型选择器中将监控类型选为Logs选择要监控日志的遥测服务Telemetry Services按需配置日志过滤器Log Filters与监控判据Criteria配置项详解遥测服务Telemetry Services选择一个或多个服务监控来自这些服务的日志。这些服务必须已经通过 OpenTelemetry 将日志发送到 OneUptime。在底层该配置对应MonitorStepLogMonitor.telemetryServiceIds字段ObjectID数组编译查询时会被转换为对primaryEntityId的IncludesIN 集合匹配。从源码看MonitorStepLogMonitor还支持一个文档未展开的附加范围选项——实体键entityKeys以主机 / Pod / 容器等清单项Inventory Items为粒度圈定监控范围对应日志行的entityKeys列hasAny(entityKeys, [...])语义。该字段为可选字段老版本保存的监控器可能没有此字段源码注释说明其向后兼容性。Dashboard 的视图模型 MonitorStepViewModel.ts 将其展示为 Inventory Items — Hosts, pods or containers this monitor is scoped to.日志过滤器Log Filters日志监控器支持四类过滤条件全部为可选Required: No过滤器说明是否必填严重级别Severity Levels按日志严重级别过滤ERROR、WARN、INFO、DEBUG 等否正文Body在日志消息正文中进行文本搜索否属性Attributes用于过滤自定义日志属性的键值对否时间窗口Time Window回溯多久搜索日志单位秒默认 60否其中时间窗口对应字段lastXSecondsOfLogs默认值在源码 MonitorStepLogMonitor.ts 的getDefault()中明确为60 秒评估时会以当前时间 − 窗口秒数作为查询的起始时间InBetween(startDate, endDate)。严重级别Severity Levels可以按一个或多个严重级别过滤日志。OneUptime 将严重级别归一化为七种枚举值见 LogSeverity.tsFATAL/EMERGENCY/CRITICALERRORWARN/WARNINGINFO/INFORMATIONALDEBUGTRACEUNSPECIFIED实现细节上OneUptime 在日志摄取ingest阶段会丢弃客户端上报的原始severityText转而根据 OTLP 的severityNumber重新推导为上述七个枚举值之一各严重级别对应 OTLP 区间的低端数值Trace1、Debug5、Info9、Warn13、Error17、Fatal21Unspecified0。normalizeLogSeverity()函数LogSeverity.ts会把历史配置中遗留的TRACE/DEBUG/INFO/WARNING/ERROR/FATAL等字符串别名归一化到正确枚举。这意味着数据库中的severityText只可能是上述七种字符串由于与IN匹配区分大小写任何看起来像严重级别但并非七种枚举之一的字符串例如INFO之外的info将静默匹配不到任何日志而不是报错。监控判据Monitoring Criteria可用的过滤类型Filter Types当前日志监控器支持的判据类型为过滤类型说明日志数量Log Count时间窗口内匹配你过滤条件的日志条数对应源码中的CheckOn.LogCount见 CriteriaFilter.ts。评估时实际观测到的logCount会被读取出来与阈值比较见 LogMonitorCriteria.ts。过滤条件Filter Conditions日志数量支持以下五种比较条件大于Greater Than— 日志数量超过阈值小于Less Than— 日志数量低于阈值大于或等于Greater Than or Equal To— 日志数量在阈值之上或等于阈值小于或等于Less Than or Equal To— 日志数量在阈值之下或等于阈值等于Equal To— 日志数量与阈值完全相等这些比较最终由 CompareCriteria.ts 的compareCriteriaNumbers()统一实现greaterThan、lessThan、equalTo、notEqualTo、greaterThanOrEqual、lessThanOrEqual。值得注意的工程细节是阈值字符串会先经convertToNumber()转成数字且parseInt产生NaN时会被显式拦截返回nullCompareCriteria.ts避免出现value NaN恒为 false 导致判据静默失效的坑。示例判据Example Criteria以下是文档给出的三组可直接落地的配置示例示例一60 秒内超过 100 条错误日志时告警严重级别Severity LevelsERROR时间窗口Time Window60 秒过滤类型Filter Type日志数量Log Count过滤条件Filter Condition大于Greater Than阈值Value100示例二出现任意 FATAL 日志即告警严重级别Severity LevelsFATAL时间窗口Time Window60 秒过滤类型Filter Type日志数量Log Count过滤条件Filter Condition大于Greater Than阈值Value0提示示例二的本质是数量大于 0因此只要时间窗口内出现 1 条及以上 FATAL 日志就会触发告警适合作为高优先级值班告警。示例三监控包含特定错误消息的日志正文Bodydatabase connection timeout时间窗口Time Window300 秒过滤类型Filter Type日志数量Log Count过滤条件Filter Condition大于Greater Than阈值Value5提示正文过滤是文本搜索对应编译为对body列的Search谓词见下文toQuery()实现。对于高频出现的业务错误建议把时间窗口拉长、阈值设高避免抖动触发。源码级原理配置如何编译成日志查询日志监控器的全部配置被封装在MonitorStepLogMonitor接口中MonitorStepLogMonitor.tsexport default interface MonitorStepLogMonitor { attributes: Dictionarystring | number | boolean; // 属性键值对过滤 body: string; // 正文文本搜索 severityTexts: ArrayLogSeverity; // 严重级别多选 telemetryServiceIds: ArrayObjectID; // 遥测服务多选 entityKeys?: Arraystring | undefined; // 实体键可选向后兼容 lastXSecondsOfLogs: number; // 时间窗口秒 }其中的MonitorStepLogMonitorUtil.toQuery()MonitorStepLogMonitor.ts将上述配置逐项编译为对日志表的查询对象映射关系如下配置字段编译结果语义telemetryServiceIdsquery.primaryEntityId new Includes([...])服务 ID 集合匹配entityKeysquery.entityKeys new Includes([...])实体键hasAny匹配空值不生效attributesquery.attributes {...}自定义属性精确匹配severityTextsquery.severityText new Includes([...])严重级别集合匹配bodyquery.body new Search(body)正文全文搜索lastXSecondsOfLogsquery.time new InBetween(now - N秒, now)时间窗口范围匹配也就是说配置ERROR 60 秒 100 条实际会被编译为severityText IN (Error) AND time BETWEEN (now-60s, now)的计数查询然后将计数结果与阈值 100 比较。进阶基于基线的日志量异常检测从源码看除静态阈值外日志监控器在源码层面还提供了**异常检测Anomaly Detection**路径见 LogMonitorCriteria.ts 与 CriteriaFilter.ts 中的AnomalouslyHigh/AnomalouslyLow/Anomalous过滤类型观测到的日志量会被归一化为每分钟速率logCount × 60 / windowSeconds与LogCountBaselineService提供的同小时-周same-hour-of-week滚动基线比较基线样本不足冷启动或基线不可靠时不告警避免薄基线误报支持敏感度Low / Medium / High默认 Medium与检测方法默认 Mean Std Dev另有 Median MAD 选项。需要说明的是异常检测更常见地配置在指标Metrics监控器上日志监控器的异常路径以CheckOn.LogCount 异常类过滤类型为入口具体可用性以你当前 Dashboard 版本的表单呈现为准。前置要求与 OpenTelemetry 接入日志监控要求你的应用程序通过OpenTelemetry将日志发送到 OneUptime。接入方式包括但不限于各语言 OpenTelemetry SDK 直接导出通过 OpenTelemetry Collector含 host-otel-collector、fluentbit、fluentd 等转发方式Kubernetes / Docker 环境通过 kubernetes-agent 或 docker-host 采集。完整的接入说明参见官方文档 OpenTelemetry 接入指南。接入完成后可在 Telemetry → Logs 页面确认日志是否正常入库再回到 Monitors 页面创建上述日志监控器即可开始接收基于日志的告警。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考