监控与可观测性
**本文引用的文件** - [[logger.go]](../file/bi-common/observability/logger/logger.go) - [[json_logger.go]](../file/bi-common/observability/logger/json-logger.go) - [[options.go]](../file/bi-common/observability/logger/options.go) - [[setup.go]](../file/bi-common/observability/logger/setup.go) - [[tracer.go]](../file/bi-common/observability/logger/tracing/tracer.go) - [[metrics.go]](../file/bi-common/observability/metrics/metrics.go) - [[values.yaml]](../file/bi-intra/charts/grafana/values.yaml) - [[_config.tpl]](../file/bi-intra/charts/grafana/templates/config.tpl) - [[apisix-prometheus-global-rule.json]](../file/bi-intra/apisix/apisix-prometheus-global-rule.json) - [[application-dev.yaml]](../file/bi-analysis/configs/application-dev.yaml) - [[config.go]](../file/bi-common/registry/nacos/config.go)
目录
简介
本文件面向BI分析平台的监控与可观测性体系，围绕日志系统、分布式链路追踪、指标采集与告警、Grafana仪表盘与数据源配置、性能关键指标与阈值、日志聚合与检索、运维部署与维护、故障诊断与性能分析、以及扩展与自定义开发进行系统化说明。目标是帮助开发者与运维人员快速理解并落地可观测性能力。
项目结构
可观测性相关能力主要分布在以下模块：
- 日志系统：统一的日志配置、JSON格式化输出、本地与阿里云SLS双写、轮转与清理
- 链路追踪：OpenTelemetry TracerProvider初始化、全局字段注入（trace.id/span.id）
- 指标系统：Prometheus指标定义与记录工具
- 可视化与告警：Grafana Helm Chart配置、数据源与告警模板
- 网关与外部集成：APISIX Prometheus插件、Nacos配置中心
图表来源
- [logger.go]
- [json_logger.go]
- [options.go]
- [setup.go]
- [tracer.go]
- [metrics.go]
- [values.yaml]
- [_config.tpl]
- [apisix-prometheus-global-rule.json]
- [application-dev.yaml]
- [config.go]
章节来源
- [logger.go]
- [setup.go]
- [tracer.go]
- [metrics.go]
- [values.yaml]
- [_config.tpl]
- [apisix-prometheus-global-rule.json]
- [application-dev.yaml]
- [config.go]
核心组件
- 结构化日志与JSON规范
- 支持JSON与文本两种格式；JSON模式下统一输出时间戳、级别与键值对字段
- 提供多输出Writer（stdout/file），可选每日轮转与压缩
- 支持本地日志与阿里云SLS双写，失败不影响本地日志
- 分布式链路追踪
- 初始化TracerProvider，设置服务资源信息（名称、版本、环境、实例ID）
- AlwaysSample采样策略，便于日志关联
- 全局注入trace.id与span.id字段
- 指标采集与告警
- 定义HTTP请求、数据库、缓存、业务等指标向量
- 提供记录函数，便于在业务层埋点
- Grafana Helm Chart内置数据源与告警模板配置入口
- 可视化与数据源
- Grafana数据源配置（Prometheus等）与告警规则模板
- APISIX全局启用Prometheus插件，暴露网关指标
- 配置中心与环境
- Nacos客户端配置与DataIDs管理
- 开发环境配置示例
章节来源
- [logger.go]
- [json_logger.go]
- [options.go]
- [setup.go]
- [tracer.go]
- [metrics.go]
- [values.yaml]
- [apisix-prometheus-global-rule.json]
- [application-dev.yaml]
- [config.go]
架构总览
整体可观测性由“日志—追踪—指标—可视化”四层组成，形成闭环：日志承载事件与上下文，追踪串联请求链路，指标量化性能与健康度，可视化呈现并触发告警。
图表来源
组件详解
日志系统：结构化与JSON规范
- 配置项
- 日志级别、格式、输出方式（stdout/file/both）、文件轮转参数、阿里云SLS接入
- 输出行为
- JSON模式：统一输出时间戳、级别、键值对字段；线程安全写入
- 文本模式：key=value格式，便于人类阅读
- 多输出合并：stdout与文件同时输出
- 每日轮转：基于日期的滚动与清理
- 阿里云SLS
- 可选启用，失败不影响本地日志
- 全局字段
- 服务信息（名称、版本、实例ID、环境）
- 调用位置、时间戳
- 追踪字段（trace.id/span.id）
图表来源
章节来源
分布式链路追踪：初始化与字段注入
- 初始化
- 创建TracerProvider，设置服务资源（名称、版本、环境、实例ID）
- AlwaysSample采样策略，确保日志关联
- 设置为全局TracerProvider
- 字段注入
- 在日志中自动注入trace.id与span.id
- 通过Kratos中间件Tracing提取上下文
图表来源
章节来源
指标采集与监控告警
- 指标定义
- HTTP请求总量/耗时直方图
- 数据库查询总量/耗时直方图/错误计数
- 缓存命中/未命中/操作耗时
- 业务操作总量（模块/操作/状态）
- 记录方法
- 提供Record系列函数，按标签维度上报
- Grafana配置
- values.yaml中预留datasources与alerting模板入口
- _config.tpl负责模板渲染与密钥注入
图表来源
章节来源
Grafana仪表板与数据源配置
- 数据源
- Prometheus数据源可通过values.yaml配置
- 支持代理访问与默认数据源设置
- 告警与通知
- 通过alerting与notifiers配置文件模板化
- 支持从文件、Secret或内联配置
- 下载仪表盘与模板
- downloadDashboards镜像与环境变量可选
图表来源
章节来源
日志聚合与检索
- 本地与SLS双写：本地日志用于快速定位，SLS用于集中检索与长期归档
- JSON结构化：便于解析与检索
- 轮转与清理：避免磁盘膨胀，支持压缩与按天轮转
章节来源
性能监控关键指标与阈值建议
- HTTP请求
- 指标：http_requests_total、http_request_duration_seconds
- 建议：P95/P99延时阈值按业务SLA设定；错误率（status>=500）阈值接近0
- 数据库
- 指标：db_query_total、db_query_duration_seconds、db_query_errors_total
- 建议：慢查询阈值（如>500ms）与错误率阈值
- 缓存
- 指标：cache_hits_total、cache_misses_total、cache_operation_duration_seconds
- 建议：命中率目标（如>95%），异常抖动阈值
- 业务
- 指标：business_operations_total
- 建议：吞吐量基线与异常波动阈值
章节来源
部署与维护指南
- 初始化与清理
- 启动阶段调用MustSetup或Setup，defer Shutdown优雅关闭
- 通过全局cleanup与shutdown统一管理资源
- 配置中心
- Nacos客户端配置与DataIDs管理，开发环境示例见application-dev.yaml
- 网关指标
- APISIX启用Prometheus插件，统一暴露网关指标
章节来源
依赖关系分析
- 组件耦合
- Setup依赖Tracing与Logger，统一注入服务信息与追踪字段
- Logger依赖JSON/文本输出与文件轮转
- 指标与可视化解耦，通过Prometheus导出
- 外部依赖
- OpenTelemetry TracerProvider、Kratos日志与中间件
- Prometheus/Grafana、APISIX、Nacos
图表来源
章节来源
性能考量
- 日志写入
- JSON序列化与互斥锁保护，建议在高并发场景控制字段数量与大小
- 文件轮转采用lumberjack或每日轮转，合理设置MaxSize/MaxAge避免频繁IO
- 追踪
- AlwaysSample策略保证日志关联，但会增加trace开销；生产可评估采样率
- 指标
- 标签基数控制（如path、table、operation），避免高基数导致内存增长
- 直方图桶设置应覆盖典型延迟分布
[本节为通用指导，无需特定文件引用]
故障排查指南
- 日志无法输出/轮转异常
- 检查输出配置与文件权限；确认轮转参数合理
- SLS写入失败
- 查看阿里云SLS配置是否正确；关注初始化错误日志
- 追踪字段缺失
- 确认TracerProvider已初始化且为全局；检查中间件是否生效
- 指标无数据
- 检查Prometheus抓取配置与服务端点暴露；核对Grafana数据源URL
- Grafana告警未触发
- 校验alerting与notifiers模板渲染结果；确认规则表达式与阈值
章节来源
结论
本可观测性方案以“结构化日志+链路追踪+Prometheus指标+Grafana可视化”为核心，结合APISIX与Nacos完善边缘与配置治理，既满足日常问题定位，也支撑生产级监控告警与容量规划。建议在各服务中统一使用MustSetup/Setup初始化，并在业务关键路径埋点指标，持续优化标签与阈值，提升可观测性价值。
[本节为总结，无需特定文件引用]
附录
JSON日志字段规范（建议）
- 必填字段
- ts：RFC3339时间戳
- level：日志级别
- service.name/service.version/service.id/service.env：服务元信息
- trace.id/span.id：追踪上下文
- 可选字段
- module、operation、status：业务语义
- region、cluster：运行环境
- caller：调用位置
- 其他上下文键值对
章节来源
指标埋点清单（建议）
- HTTP层：method、path、status
- DB层：table、operation
- 缓存层：cache_type、operation
- 业务层：module、operation、status
章节来源