prom/graphite-exporter

Graphite Exporter

概述和主要用途

Graphite Exporter是用于导出Graphite明文协议指标的工具，通过TCP和UDP接收数据，将点分隔的Graphite指标转换为带标签的Prometheus指标并暴露HTTP端点，供Prometheus采集。适用于现有Graphite监控系统向Prometheus迁移或集成，以及处理核心Prometheus导出器未覆盖的指标。

核心功能和特性

• 多协议支持：同时支持TCP和UDP接收Graphite明文协议数据
• 指标转换：将Graphite点分隔指标转换为带标签的Prometheus指标
• 标签处理：支持Graphite带标签carbon格式，自动丢弃无效标签并计数解析失败
• 灵活配置：通过YAML文件自定义指标映射规则，支持正则匹配与标签提取
• 内存管理：默认5分钟后垃圾回收未更新指标，可通过--graphite.sample-expiry调整
• 安全防护：支持TLS加密和基本认证保护HTTP端点

使用场景和适用范围

• 现有Graphite监控系统与Prometheus集成
• 非Prometheus原生应用（通过Graphite协议发送指标）接入Prometheus
• 处理核心Prometheus导出器（如Node Exporter）未覆盖的业务指标
• 需要同时接收TCP和UDP指标数据的场景

使用方法和配置说明

基本使用

编译运行

sh
make
./graphite_exporter

发送测试数据

配置监控系统向9109端口发送Graphite数据，测试示例：

sh
# TCP测试
echo "test_tcp 1234 $(date +%s)" | nc localhost 9109
# UDP测试
echo "test_udp 1234 $(date +%s)" | nc -u -w1 localhost 9109

指标可通过 http://localhost:9108/metrics 访问

Graphite标签处理

支持https://graphite.readthedocs.io/en/latest/tags.html，无效标签会被丢弃，`graphite_tag_parse_failures`计数器递增。默认配置标签优先于指标标签，如需使用指标标签可启用https://github.com/prometheus/statsd_exporter/#honor-labels。

指标映射和配置

注意：0.2.0版本后配置格式变更为https://github.com/prometheus/statsd_exporter的YAML风格，旧配置需转换（见下方说明）

YAML配置

通过YAML文件定义指标映射规则，语法与https://github.com/prometheus/statsd_exporter兼容（不支持`timer_type`相关特性）。未匹配规则的指标将转换为无标签Prometheus指标，非字母数字字符（除`_`和`:`）替换为`_`。启用`--graphite.mapping-strict-match`可仅保留匹配规则的指标。

示例配置：

yaml
mappings:
- match: test.dispatcher.*.*.*
  name: dispatcher_events_total
  labels:
    action: $2
    job: test_dispatcher
    outcome: $3
    processor: $1
- match: '*.signup.*.*'
  name: signup_events_total
  labels:
    job: ${1}_server
    outcome: $3
    provider: $2
- match: 'servers\.(.*)\.networking\.subnetworks\.transmissions\.([a-z0-9-]+)\.(.*)'
  match_type: regex
  name: 'servers_networking_transmissions_${3}'
  labels: 
    hostname: ${1}
    device: ${2}

转换效果：

test.dispatcher.FooProcessor.send.success → dispatcher_events_total{processor="FooProcessor", action="send", outcome="success", job="test_dispatcher"}
foo_product.signup.facebook.failure → signup_events_total{provider="facebook", outcome="failure", job="foo_product_server"}

旧配置转换

0.2.0前版本配置需通过https://github.com/bakins/statsd-exporter-convert转换：

sh
# 安装转换工具
go get -u github.com/bakins/statsd-exporter-convert

# 转换示例
statsd-exporter-convert old_config.conf > new_config.yaml

Docker部署

使用官方镜像https://hub.docker.com/r/prom/graphite-exporter部署：

bash
# 拉取镜像
docker pull docker.xuanyuan.run/prom/graphite-exporter

# 运行容器（挂载配置文件）
docker run -d -p 9108:9108 -p 9109:9109 -p 9109:9109/udp \
  -v ${PWD}/graphite_mapping.yaml:/tmp/graphite_mapping.yaml \
  docker.xuanyuan.run/prom/graphite-exporter --graphite.mapping-config=/tmp/graphite_mapping.yaml

端口说明：

• 9108：Prometheus采集指标的HTTP端口
• 9109：TCP接收Graphite数据端口
• 9109/udp：UDP接收Graphite数据端口

实验性功能：Whisper数据导入

使用getool工具导入Graphite的Whisper数据：

sh
# 查看帮助
getool create-blocks --help

# 导入示例（指定块时长为8小时）
getool create-blocks --block-duration=8h --input-dir=/path/to/whisper --output-dir=/path/to/tsdb

合并至现有Prometheus存储时，需启动Prometheus并添加--storage.tsdb.allow-overlapping-blocks标志。

与Graphite桥的不兼容性

不兼容https://prometheus.github.io/client_java/io/prometheus/client/bridge/Graphite.html或https://github.com/prometheus/client_python#graphite的Graphite桥，因数据模型转换会丢失信息且指标可能冲突。替代方案：

• 直接配置Prometheus采集应用指标
• 批处理任务使用https://prometheus.io/docs/practices/pushing/
• 需推送指标时考虑https://github.com/prometheus-community/PushProx或https://github.com/grafana/agent

TLS和基本认证

通过--web.config.file指定配置文件启用安全特性，格式详见https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md。配置示例：

yaml
tls_config:
  cert_file: /etc/tls/cert.pem
  key_file: /etc/tls/key.pem
basic_auth_users:
  admin: $2a$10$VQwZ...  # bcrypt加密的密码