braedon/prometheus-es-exporter

Prometheus Elasticsearch Exporter

镜像概述和主要用途

Prometheus Elasticsearch Exporter用于从Elasticsearch集群收集两类指标：一是通过配置的查询获取的数据指标，二是集群自身的运行状态指标（如集群健康、节点统计、索引信息等），并将这些指标转换为Prometheus兼容的格式，以便进行监控和告警。

https://github.com/braedon/prometheus-es-exporter | Python包 | https://hub.docker.com/r/braedon/prometheus-es-exporter | https://braedon.github.io/helm/prometheus-es-exporter

核心功能和特性

查询指标

exporter定期对Elasticsearch集群运行配置的查询，并将结果导出为Prometheus gauge指标。

• 自动解析Elasticsearch结果中的值，JSON中值的路径用于构建指标名称
• 仅从聚合结果中提取指标，例外情况包括查询的hits.total计数（暴露为hits指标）和took时间（暴露为took_milliseconds指标）
• 任何聚合桶的键会转换为标签，而非插入到指标名称中

支持的聚合类型

有限的聚合类型有明确支持和测试，可查看tests/test_parser.py获取使用这些聚合的示例查询及其生成的指标。大多数其他聚合只要结果格式与明确支持的聚合结构相似，也应能正常工作。

如需使用特定聚合但遇到问题（且未明确不支持），请提交issue或PR。

不支持的聚合类型

部分聚合明确不支持，因实现复杂度或设计限制无法正常工作：

• top_hits：该聚合返回文档而非文档指标，从任意文档中提取指标因复杂度超出本exporter范围。

集群指标

当exporter的指标端点被调用时，会查询Elasticsearch集群的_cluster/health、_nodes/stats和_stats端点，并将结果导出为Prometheus gauge指标。

端点响应会被尽可能通用地解析，以支持各版本Elasticsearch（过去和未来），这可能导致部分指标不够理想（如指标冗余、无 gauge 与 counter 区分，所有指标均为 gauge）。如有改进建议，可通过Github issue或PR反馈。

查看tests/test_cluster_health_parser.py、tests/test_nodes_stats_parser.py和tests/test_indices_stats_parser.py获取响应示例及生成的指标。

exporter还生成以下特定指标：

es_indices_aliases_alias{index, alias} (gauge)

索引别名及其指向的索引，从_alias端点解析。当前别名的指标值为1，别名移除或变更指向索引时，旧指标会立即删除。

注意：Prometheus可能在短时间内（通常5分钟）仍返回已删除指标。未来可能在删除前将旧指标值设为0以缓解此问题，因此建议检查指标值而非仅判断存在性。

可通过and操作符结合此指标过滤其他索引指标，例如：

es_indices_mappings_field_count and on(index) (es_indices_aliases_alias{alias="logstash-today"} == 1)

es_indices_mappings_field_count{index, field_type} (gauge)

索引中特定类型的映射字段数量，从_mappings端点解析。按索引求和可计算每个索引的总字段数，有助于检查是否接近字段限制，例如：

sum(es_indices_mappings_field_count) by(index) > 900

使用场景和适用范围

• 监控Elasticsearch集群健康状态及节点性能
• 跟踪索引字段映射数量，避免达到字段限制
• 监控自定义查询结果指标，支持业务分析或性能优化
• 集成Prometheus和Grafana构建Elasticsearch可视化监控面板

详细使用方法和配置说明

安装

exporter需要Python 3和Pip 3环境。通过Pip安装最新发布版本：

bash
> pip3 install prometheus-es-exporter

注意：可能需要将启动脚本路径（见pip输出）添加到PATH环境变量。

命令行使用

安装后可通过prometheus-es-exporter命令运行。默认绑定端口9206，查询localhost:9200的Elasticsearch，使用当前目录的exporter.cfg配置文件。可通过选项修改默认值：

bash
> prometheus-es-exporter -p <端口> -e <Elasticsearch节点> -c <查询配置文件路径>

使用-h标志查看所有可用选项详情。

配置优先级

• 所有选项可通过环境变量设置，变量名前缀为ES_EXPORTER，例如ES_EXPORTER_BASIC_USER=fred等效于--basic-user fred
• 命令行选项优先级高于环境变量
• 可通过--config FILE从配置文件设置选项，文件格式为Configobj的unrepr模式（例如配置文件中basic-user="fred"等效于--basic-user fred）
• 配置优先级：命令行 > 环境变量 > 配置文件 > 默认值

查询配置示例和说明见提供的exporter.cfg文件。

Docker部署

已发布版本的Docker镜像可在Docker Hub获取（无latest标签）：

bash
> sudo docker pull braedon/prometheus-es-exporter:<version>

运行容器需挂载查询配置文件到/usr/src/app/exporter.cfg，并映射容器端口9206到主机端口。镜像名后的选项会传递给容器内进程（例如配置Elasticsearch节点需使用-e）：

bash
> sudo docker run --rm --name exporter \
    -v <查询配置文件路径>:/usr/src/app/exporter.cfg \
    -p <主机端口>:9206 \
    braedon/prometheus-es-exporter:<version> -e <Elasticsearch节点>

如需在构建时嵌入配置文件，可扩展现有镜像创建自定义Dockerfile。

Helm部署

Helm chart可从仓库https://braedon.github.io/helm/%E8%8E%B7%E5%8F%96%EF%BC%9A

bash
> helm repo add braedon https://braedon.github.com/helm
> helm repo update

> helm install braedon/prometheus-es-exporter --name <发布名称> \
                                              --set elasticsearch.cluster=<Elasticsearch节点> \
                                              --set image.tag=<镜像标签>

配置详情见https://braedon.github.io/helm/prometheus-es-exporter/%E3%80%82

开发相关

从源码安装

在项目根目录执行：

bash
> pip3 install .

使用-e标志以"可编辑"模式安装，便于测试修改无需重新安装：

bash
> pip3 install -e .

运行测试

在项目根目录执行（仅覆盖响应解析功能，无系统测试）：

bash
> python3 -m unittest

构建Docker镜像

从源码构建镜像：

bash
> sudo docker build -t <仓库名称和标签> .

容器内开发

构建镜像后，在项目根目录运行（文件实时同步，可直接测试修改）：

bash
> sudo docker run --rm -it --name exporter --entrypoint bash -v $(pwd):/usr/src/app <仓库名称和标签>

如遇pkg_resources.DistributionNotFound错误，需在容器内重新运行pip install -e .。

欢迎通过PR贡献代码！