用 Categraf Oracle Input 监控 Oracle 数据库账号授权、实例配置与自定义 SQL 指标采集实战【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingaleCategraf 的 Oracle 插件通过执行 SQL 查询 Oracle 动态性能视图v$*系列与数据字典视图将数值结果转换为时序指标实现数据库会话、活动量、表空间、系统指标、Data Guard 延迟等多维度监控。本文基于本仓库 integrations/Oracle 目录下的插件文档、采集配置与配套告警/面板完整讲解监控账号授权、oracle.toml实例连接配置、metric.toml查询定义与指标命名规律并给出自定义指标扩展与--test验证方法帮助你快速把任意 Oracle 数据库接入 Categraf 与 Nightingale 监控体系。插件概述与适用场景Oracle 插件用于监控 Oracle 数据库其工作方式不是读取外部 API而是直接连接数据库执行预定义的 SQL把查询结果中的数值列转成指标。本仓库的集成包内包含四个组成部分文件作用integrations/Oracle/collect/oracle/oracle.toml实例连接配置模板对应部署后的conf/input.oracle/oracle.tomlintegrations/Oracle/collect/oracle/metric.toml全部 SQL 查询定义对应部署后的conf/input.oracle/metric.tomlintegrations/Oracle/dashboards/oracle_by_categraf.json开箱即用的监控面板integrations/Oracle/alerts/oracle_alert.json配套告警规则模板插件文档说明其默认无法运行在 Windows 上。如果 Oracle 数据库部署在 Windows无需担心在 Linux 上部署一个 Categraf 实例通过远程方式监控 Windows 上的 Oracle 即可。文档同时给出了验证背景本次功能验证使用 Oracle Database Free 26ai并写入 20,000 行数据构成工作负载后完成真实数据校验——这从侧面说明插件对较新版本 Oracle 及真实负载场景均有覆盖。监控账号的创建与最小权限收敛官方建议为监控单独创建专用账号而不是使用业务账号或 DBA 账号。文档给出的是便于验证的基础授权基线CREATE USER categraf IDENTIFIED BY password; GRANT CREATE SESSION TO categraf; GRANT SELECT_CATALOG_ROLE TO categraf;其中SELECT_CATALOG_ROLE授予了对数据字典视图的查询能力足以支撑metric.toml中大部分基于v$*、dba_*视图的查询。文档强调生产环境可以按metric.toml实际查询的视图进一步收敛权限——即只授予该账号确实用到的那些视图的最小读取权限。同时需要注意环境差异不同 Oracle 版本、CDB/PDB 架构、Data Guard 和 ASM 环境所需的视图并不相同。如果某条 SQL 报ORA-00942表或视图不存在或ORA-01031权限不足正确做法是为该视图补充最小读取权限而不是退回去使用业务账号。实例连接配置oracle.toml实例连接配置位于conf/input.oracle/oracle.toml查询定义单独放在同目录的metric.toml两者职责分离。文档给出的连接配置示例interval 15 [[instances]] address oracle.example.com:1521/FREE username categraf password password is_sys_dba false is_sys_oper false disable_connection_pool false max_open_connections 5 conn_max_idle_time 15m conn_max_lifetime 24h labels { env prod }仓库内 oracle.toml 模板还额外给出了多实例写法每个实例是一个独立的[[instances]]块且支持interval_times参数——注释中说明其语义为interval global.interval * interval_times即某个实例可以用全局采集间隔的整数倍来拉低采集频率适合低频变化的次要实例。各参数含义与建议如下参数含义说明interval采集间隔秒全局采集周期示例为 15 秒address数据库连接地址格式host:port/service_name最后一段是 service name不一定是 SIDusername/password连接账号密码建议使用专用监控账号is_sys_dba是否以 SYSDBA 身份连接默认falseis_sys_oper是否以 SYSOPER 身份连接默认falsedisable_connection_pool是否禁用连接池默认false即启用连接池max_open_connections连接池最大打开连接数示例为 5conn_max_idle_time连接最大空闲时间示例15m空闲超时回收conn_max_lifetime连接最大存活时间示例24h防止长连接被服务端掐断interval_times间隔倍数interval global.interval * interval_timeslabels附加标签示例{ env prod }会作为指标的附加 label关于address有两个关键注意点最后一段是 service name服务名不一定是 SID。例如oracle.example.com:1521/FREE中的FREE是服务名配置前应在目标库用lsnrctl services或查询确认。面板通过oracle_up指标的address标签筛选实例。查看 面板定义 可发现几乎所有面板查询都带{address$address}过滤条件例如oracle_up{address$address}、rate(oracle_activity_execute_count_value{address$address}[2m])。因此不要在采集侧删除或统一覆盖address标签否则面板的实例下拉筛选会失效。查询定义与指标采集原理metric.tomlOracle input 的核心原理是执行 metric.toml 中定义的 SQL把查询结果中的数值列转换为指标。每个查询对应一个[[metrics]]配置段。文档以activity为例[[metrics]] mesurement activity metric_fields [ value ] field_to_append name timeout 3s request SELECT name, value FROM v$sysstat WHERE name IN (parse count (total), execute count, user commits, user rollbacks) 各字段语义字段含义mesurement指标类别分类前缀label_fields作为 label 的字段列表metric_fields作为指标值的字段列表因为要作为指标数值该字段的值必须是数字field_to_append该字段的值会附加到 metric_name 后面成为指标名的一部分timeout查询超时时间如3srequest实际执行的 SQL 语句特别提醒当前 Oracle input 配置结构中的字段拼写是mesurement而非标准英文measurement应按 Categraf 实际配置保留。写成measurement会导致自定义查询名称不能被正确解析——这是文档明确强调的坑。结合面板中的实际指标名可以推断出指标命名规律插件会生成oracle_mesurement_...前缀的指标。例如activityfield_to_append namemetric_fields [value]生成oracle_activity_execute_count_value、oracle_activity_user_commits_value、oracle_activity_user_rollbacks_value等指标name 值中的空格归一化为下划线不带field_to_append的查询直接按oracle_mesurement_metric_field命名如oracle_sessions_value、oracle_tablespace_bytessysmetric使用field_to_append metric_name生成oracle_sysmetric_io_requests_per_second_value、oracle_sysmetric_buffer_cache_hit_ratio_value等指标。默认采集的指标清单metric.toml默认内置了 11 组查询覆盖数据库监控的常见维度。逐个拆解如下sessions会话数[[metrics]] mesurement sessions label_fields [ status, type ] metric_fields [ value ] timeout 3s request SELECT status, type, COUNT(*) as value FROM v$session GROUP BY status, type 按statusACTIVE/INACTIVE与typeUSER/BACKGROUND分组统计会话数生成带status、type标签的oracle_sessions_value。告警模板中活跃连接告警即使用sum by (instance) (oracle_sessions_value{statusACTIVE,typeUSER})。lock锁对象[[metrics]] mesurement lock metric_fields [ cnt ] timeout 3s request SELECT COUNT(*) AS cnt FROM ALL_OBJECTS A, V$LOCKED_OBJECT B, SYS.GV_$SESSION C WHERE A.OBJECT_ID B.OBJECT_ID AND B.PROCESS C.PROCESS 关联三个视图统计当前被锁定的对象数量用于观察锁堆积情况。slow_queries慢 SQL 耗时分布[[metrics]] mesurement slow_queries metric_fields [ p95_time_usecs, p99_time_usecs ] timeout 3s request SELECT percentile_disc(0.95) WITHIN GROUP (ORDER BY elapsed_time) AS p95_time_usecs, percentile_disc(0.99) WITHIN GROUP (ORDER BY elapsed_time) AS p99_time_usecs FROM v$sql WHERE last_active_time sysdate - 5/(24*60) 统计最近 5 分钟内 SQL 执行耗时的 P95/P99 分位数单位微秒用来发现慢 SQL 趋势。resource资源限制水位[[metrics]] mesurement resource label_fields [ resource_name ] metric_fields [ current_utilization, limit_value ] timeout 3s request SELECT resource_name, current_utilization, CASE WHEN TRIM(limit_value) UNLIMITED THEN -1 ELSE TRIM(limit_value) END AS limit_value FROM v$resource_limit 读取各资源processes、sessions 等当前利用率与上限UNLIMITED被归一化为-1。asm_diskgroupASM 磁盘组空间[[metrics]] mesurement asm_diskgroup label_fields [ name ] metric_fields [ total, free ] timeout 3s ignore_zero_result true request SELECT name, total_mb * 1024 * 1024 AS total, free_mb * 1024 * 1024 AS free FROM v$asm_diskgroup_stat WHERE EXISTS (SELECT 1 FROM v$datafile WHERE name LIKE %) 通过EXISTS子查询仅在数据库确实使用 ASM数据文件路径以开头时才返回数据单位为字节。注意其ignore_zero_result true——当数据库没有 ASM 环境时该查询返回空结果会被忽略不会产生 0 值误报。activity活动量统计见上文示例采集 parse、execute、commit、rollback 四类计数累计值面板中用rate()换算为每秒速率。process后台进程数[[metrics]] mesurement process metric_fields [ count ] timeout 3s request SELECT COUNT(*) AS count FROM v$process对应告警模板中的oracle_process_count用于连接数超限告警。wait_time等待事件耗时[[metrics]] mesurement wait_time metric_fields [ value ] label_fields [ wait_class ] timeout 3s request SELECT n.wait_class AS wait_class, ROUND(m.time_waited / m.INTSIZE_CSEC, 3) AS value FROM v$waitclassmetric m, v$system_wait_class n WHERE m.wait_class_id n.wait_class_id AND n.wait_class ! Idle 按等待类别输出最近 1 分钟窗口内的等待时间秒已过滤 Idle 空闲等待是判断数据库瓶颈I/O、CPU 调度、锁等的关键指标。tablespace表空间使用[[metrics]] mesurement tablespace label_fields [ tablespace, type ] metric_fields [ bytes, max_bytes, free ] timeout 3s request SELECT dt.tablespace_name AS tablespace, dt.contents AS type, dt.block_size * dtum.used_space AS bytes, dt.block_size * dtum.tablespace_size AS max_bytes, dt.block_size * (dtum.tablespace_size - dtum.used_space) AS free FROM dba_tablespace_usage_metrics dtum, dba_tablespaces dt WHERE dtum.tablespace_name dt.tablespace_name ORDER BY tablespace 输出每个表空间的已用、上限与剩余字节数均转换为字节面板用oracle_tablespace_bytes/oracle_tablespace_max_bytes计算使用率告警模板据此设置95%告警。sysmetric系统指标[[metrics]] mesurement sysmetric metric_fields [ value ] field_to_append metric_name timeout 3s request SELECT metric_name, value FROM v$sysmetric WHERE group_id 2 从v$sysmetric的 group_id2最近 60 秒窗口批量采集 Oracle 内置的几十项系统指标如 Buffer Cache Hit Ratio、Redo Allocation Hit Ratio、Physical Read/Write Bytes per Sec、I/O Requests per Sec、User Transaction per Sec 等面板中大量 stat 图都来自这一组指标。applylagData Guard 应用延迟[[metrics]] mesurement applylag metric_fields [ value ] timeout 3s ignore_zero_result true request SELECT ROUND( EXTRACT(DAY FROM TO_DSINTERVAL(value)) * 86400 EXTRACT(HOUR FROM TO_DSINTERVAL(value)) * 3600 EXTRACT(MINUTE FROM TO_DSINTERVAL(value)) * 60 EXTRACT(SECOND FROM TO_DSINTERVAL(value)) ) AS value FROM v$dataguard_stats WHERE name apply lag 将 Data Guard 的apply lag间隔型文本换算为秒数同样带ignore_zero_result true仅在存在 Data Guard 环境时才有数据。自定义指标扩展如果你想监控的指标默认没有采集只需要在metric.toml中新增一个[[metrics]]配置段即可无需改动插件代码。需要注意字段拼写保持mesurement而不是measurementmetric_fields指定的列必须是数值类型NUMBER等否则无法作为指标值若查询结果可能为空例如依赖特定功能的环境可配合ignore_zero_result true避免产生无意义的数据新增段建议设置合理的timeout防止慢 SQL 拖慢整体采集。例如要额外采集归档日志数量可参考告警模板中已引用的oracle_archivelog_count命名风格自行补充对应查询并放在metric.toml中。验证采集是否正常配置完成后用 Categraf 的测试模式验证命令如下./categraf --test --inputs oracle该命令会以单次执行的方式运行 oracle input并在终端直接打印采集到的指标便于快速确认连接、SQL 和指标解析是否正确。验证时至少确认以下内容oracle_up 1表示实例连接与采集成功这是最重要的探活指标告警模板中oracle_up ! 1即为实例可能挂了的 P1 级告警sessions、activity、tablespace、sysmetric四组核心指标有数据返回。需要特别说明Data Guard、ASM、锁和慢 SQL 面板只有在对应功能或事件存在时才会返回数据——例如非 ASM 环境看不到asm_diskgroup无锁冲突时lock为空Data Guard 指标仅在备库存在时出现这是正常现象不代表采集故障。配套面板与告警规则集成包自带的面板与告警让采集完即可用监控面板oracle_by_categraf.json 包含按地址$address变量筛选的多组图表面板主要 PromQL 示例如下面板主题查询示例数据库状态oracle_up{address$address}活动量速率rate(oracle_activity_execute_count_value{address$address}[2m])、rate(oracle_activity_user_commits_value{address$address}[2m])等待时间oracle_wait_time_value{address$address}表空间使用率oracle_tablespace_bytes{address$address}/oracle_tablespace_max_bytes{address$address}会话数oracle_sessions_value{address$address,statusACTIVE}系统指标oracle_sysmetric_buffer_cache_hit_ratio_value{address$address}、oracle_sysmetric_io_requests_per_second_value{address$address}、oracle_sysmetric_physical_read_bytes_per_sec_value{address$address}等告警规则oracle_alert.json 内置 5 条与面板配套的规则含严重级别、通知通道与处置建议annotations 中的 action 字段可通过 i18n 文件 查看英文版本。核心规则一览规则PromQL级别监控数据采集失败可能已经挂了oracle_up ! 1P1数据库归档日志量大于 100oracle_archivelog_count 100P2数据库总连接数大于 500800 为 P3oracle_process_count 500/ 800P2/P3数据库活跃连接数大于 100sum by (instance) (oracle_sessions_value{statusACTIVE,typeUSER}) 100P2表空间使用率大于 95%oracle_tablespace_bytes/oracle_tablespace_max_bytes*100 95P2规则注解中还附带了排障思路例如表空间告警的处置动作包括用DBA_DATA_FILES与DBA_FREE_SPACE定位具体表空间、应急扩容ALTER DATABASE DATAFILE ... RESIZE、清理历史数据后执行 shrink/move 真正释放空间、检查数据文件 AUTOEXTEND 与 MAXSIZE 设置等。常见问题速查ORA-00942/ORA-01031查询视图不存在或权限不足。按环境CDB/PDB、Data Guard、ASM为监控账号补充对应视图的最小读取权限。自定义查询不生效检查mesurement是否写成了measurement当前插件按mesurement拼写解析。面板实例筛选为空确认未删除或覆盖采集指标的address标签面板依赖它做实例级筛选。某些面板无数据Data Guard、ASM、锁、慢 SQL 指标只在对应功能或事件存在时产生属预期行为。Windows 上的 Oracle插件默认无法在 Windows 上运行用 Linux 上的 Categraf 远程采集即可。【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考