awaragi/prometheus-mssql-exporter

Prometheus MSSQL Exporter Docker容器

镜像概述和主要用途

Prometheus MSSQL Exporter是用于Microsoft SQL Server (MSSQL)的Prometheus导出器，可暴露多种关键性能和状态指标，便于通过Prometheus进行监控和分析。已针对MSSQL 2017和2019 Docker镜像测试，其他版本可能兼容但未经过测试。

核心功能和特性

暴露以下指标：

• mssql_up：运行状态
• mssql_product_version：实例版本（主版本.次版本）
• mssql_instance_local_time：实例本地时间（距离纪元的秒数）
• mssql_connections{database,state}：活动连接数
• mssql_client_connections{client,database}：活动客户端连接数
• mssql_deadlocks：每秒死锁数（自上次重启起）
• mssql_user_errors：每秒用户错误数（自上次重启起）
• mssql_kill_connection_errors：每秒终止连接错误数（自上次重启起）
• mssql_database_state{database}：数据库状态：0=在线 1=恢复中 2=正在恢复 3=恢复挂起 4=可疑 5=紧急 6=离线 7=复制 10=离线辅助
• mssql_log_growths{database}：事务日志扩展次数（自上次重启起）
• mssql_database_filesize{database,logicalname,type,filename}：数据库文件物理大小（KB），包括名称和类型（0=行 1=日志 2=文件流 3=不适用 4=全文索引（MSSQL 2008前））
• mssql_page_read_total：每秒页面读取数
• mssql_page_write_total：每秒页面写入数
• mssql_page_life_expectancy：页面在缓冲池中不被引用的最小秒数（建议保持在300秒以上）
• mssql_lazy_write_total：每秒延迟写入数
• mssql_page_checkpoint_total：每秒检查点页面数
• mssql_io_stall{database,type}：I/O延迟时间（毫秒，自上次重启起）
• mssql_io_stall_total{database}：总I/O延迟时间（毫秒，自上次重启起）
• mssql_batch_requests：每秒接收的Transact-SQL命令批次数（受I/O、用户数等因素影响，高值表示良好吞吐量）
• mssql_transactions{database}：数据库每秒启动的事务数（不包括仅XTP事务）
• mssql_page_fault_count：页面错误数（自上次重启起）
• mssql_memory_utilization_percentage：内存利用率百分比
• mssql_total_physical_memory_kb：总物理内存（KB）
• mssql_available_physical_memory_kb：可用物理内存（KB）
• mssql_total_page_file_kb：总页面文件（KB）
• mssql_available_page_file_kb：可用页面文件（KB）

使用场景和适用范围

适用于需要监控MSSQL数据库性能和状态的场景，如数据库管理员、DevOps工程师，可集成到Prometheus+Grafana监控体系中，实现对MSSQL实例的实时监控、告警和性能分析。支持MSSQL 2017、2019及兼容版本的Docker部署环境。

使用方法和配置说明

基本使用

使用以下命令启动容器：

bash
docker run -e SERVER=192.168.56.101 -e USERNAME=SA -e PASSWORD=qkD4x3yy -e DEBUG=app -p 4000:4000 --name prometheus-mssql-exporter awaragi/prometheus-mssql-exporter

环境变量说明

镜像支持以下环境变量，暴露端口4000：

• SERVER：服务器IP或DNS名称（必填）
• PORT：服务器端口（可选，默认1433）
• USERNAME：访问用户（必填）
• PASSWORD：访问密码（必填）
• ENCRYPT：强制加密设置（可选，默认true，参考Microsoft文档）
• TRUST_SERVER_CERTIFICATE：设置信任服务器证书（可选，默认true，参考Microsoft文档）
• DEBUG：启用日志的逗号分隔列表（可选，当前支持app和metrics）

用户权限要求

指定用户必须具备以下权限：

sql
GRANT VIEW ANY DEFINITION TO <user>
GRANT VIEW SERVER STATE TO <user>

常见问题（FAQ）

无法连接到数据库

在https://github.com/awaragi/prometheus-mssql-exporter/issues/19%E4%B8%AD%E6%8F%90%E5%87%BA%E3%80%82
可能是SQL Server作为命名实例运行，默认TCP端口动态配置，需按文档显式指定端口。

运行多个导出器实例

在https://github.com/awaragi/prometheus-mssql-exporter/issues/20%E4%B8%AD%E6%8F%90%E5%87%BA%E3%80%82
每个容器应使用独立的Docker端口转发（例如-p 4001:4000和-p 4002:4000）。

可使用的Grafana仪表盘

以下是推荐的Grafana仪表盘：

• [***]

后台运行

使用docker run -d ...在后台运行容器。

开发（可选）

启动测试MSSQL服务器

启动本地MSSQL实例进行测试：

shell
npm run test:mssql:2019
# 或
npm run test:mssql:2017

如需持久化存储，添加-v /<mypath>:/var/opt/mssql/data到命令行。

列出所有可用指标

列出所有可用指标及生成指标的查询（供DBA验证）：

shell
npm run metrics

开发环境变量

• SERVER：sqlserver
• PORT：SQL Server端口（可选，默认1433）
• USERNAME：SQL Server用户（需管理员或具备所需权限的用户）
• PASSWORD：SQL用户密码
• ENCRYPT：强制加密设置（可选，默认true）
• TRUST_SERVER_CERTIFICATE：设置信任服务器证书（可选，默认true）
• EXPOSE：Web服务器端口（默认4000）
• DEBUG：详细日志（app：应用日志；metrics：指标执行日志；db：数据库连接日志；queries：数据库查询及结果日志）

通过命令行启动

使用NodeJS

针对本地运行的MSSQL（见上文启动Docker实例方法），执行以下命令生成详细日志：

shell
npm start

更详细的执行（打印所有查询及结果）：

shell
npm run start:verbose

使用Docker

构建并启动Docker镜像：

shell
npm run docker:run

测试

使用Curl或浏览器

通过curl或wget获取指标：

shell
curl http://localhost:4000/metrics

E2E测试

可针对MSSQL 2017或2019 Docker实例执行E2E测试，检查所有预期指标键的存在性（不关注具体值）。添加新指标时需更新E2E测试以包含新键：

shell
npm test

构建并推送到DockerHub

使用docker build和docker push，或使用GitHub Workflows/Actions（见.github/workflows）。