newrelic/newrelic-prometheus-configurator

New Relic Prometheus Configurator Image 技术文档

一、镜像概述

New Relic Prometheus Configurator Image 是由 New Relic 官方提供的容器化工具，旨在简化 Prometheus 与 New Relic 平台的集成配置流程。该镜像通过自动化生成和管理 Prometheus 配置文件（如 prometheus.yml），帮助用户快速实现 Prometheus 指标向 New Relic 的采集与上报，减少手动配置的复杂度和出错风险。

主要用途

• 自动生成适配 New Relic 的 Prometheus 配置文件，包含 Remote Write 端点配置。
• 简化 Prometheus 与 New Relic 集成过程中的密钥管理、指标过滤和格式转换。
• 支持容器化环境（如 Kubernetes、Docker Compose）中的 Prometheus 配置动态管理。

二、核心功能和特性

三、使用场景和适用范围

典型使用场景

1. Prometheus 指标上报 New Relic：需将 Prometheus 采集的指标（如服务器、应用、Kubernetes 集群指标）上报至 New Relic 进行监控分析。
2. Kubernetes 集群监控：在 Kubernetes 环境中，通过该工具生成 Prometheus ConfigMap，实现集群内 Prometheus 与 New Relic 的无缝集成。
3. 多环境配置统一管理：通过环境变量动态调整配置参数，实现开发/测试/生产环境的 Prometheus 配置标准化。
4. 简化新手集成流程：对 Prometheus 或 New Relic 配置不熟悉的用户，可通过该工具快速完成基础集成，降低学习成本。

适用范围

• 已部署 Prometheus 并需对接 New Relic 的用户。
• 容器化部署环境（Docker、Kubernetes）中的 Prometheus 配置管理。
• 需要批量或动态生成 Prometheus 配置的场景（如 CI/CD 流水线集成）。

四、使用方法和配置说明

4.1 前置条件

• 已安装 Docker 或容器运行时（如 containerd）。
• 拥有 New Relic 账号及有效的 许可证密钥（License Key，可在 New Relic 控制台的「Account Settings > API keys」中获取）。
• Prometheus 实例已部署（需确保 Prometheus 支持 Remote Write 功能，版本 ≥2.0）。

4.2 镜像拉取

从 Docker Hub 或 New Relic 官方镜像仓库拉取最新版本镜像：

bash
docker pull docker.xuanyuan.run/newrelic/newrelic-prometheus-configurator:latest

4.3 基础使用步骤

4.3.1 生成 Prometheus 配置文件

通过运行容器生成 prometheus.yml，并挂载到本地目录以便 Prometheus 使用：

bash
docker run -it --rm \
  -e NEW_RELIC_LICENSE_KEY=<YOUR_NEW_RELIC_LICENSE_KEY> \
  -v $(pwd)/prometheus-config:/output \
  docker.xuanyuan.run/newrelic/newrelic-prometheus-configurator:latest

• 说明：容器启动后，会在 /output 目录生成 prometheus.yml，并通过本地挂载的 ./prometheus-config 目录输出到宿主机。

4.3.2 集成到 Prometheus 部署

将生成的 prometheus.yml 挂载到 Prometheus 容器中，示例 Docker Compose 配置：

yaml
# docker-compose.yml
version: '3'
services:
  prometheus:
    image: docker.xuanyuan.run/prom/prometheus:latest
    volumes:
      - ./prometheus-config/prometheus.yml:/etc/prometheus/prometheus.yml  # 挂载生成的配置文件
    ports:
      - "9090:9090"
    restart: always

  configurator:
    image: docker.xuanyuan.run/newrelic/newrelic-prometheus-configurator:latest
    environment:
      - NEW_RELIC_LICENSE_KEY=<YOUR_NEW_RELIC_LICENSE_KEY>
      - PROMETHEUS_CONFIG_OUTPUT_PATH=/output/prometheus.yml
    volumes:
      - ./prometheus-config:/output
    restart: on-failure  # 配置生成后可停止，或按需设置为 "always" 监控配置变更

4.4 配置参数说明

4.4.1 核心环境变量

通过环境变量控制配置生成逻辑，常用参数如下：

4.4.2 自定义配置示例（Docker Compose）

通过 docker-compose.yml 集成 Prometheus 和 Configurator，实现配置自动生成与 Prometheus 联动：

yaml
# docker-compose.yml
version: '3.8'

services:
  prometheus-configurator:
    image: docker.xuanyuan.run/newrelic/newrelic-prometheus-configurator:latest
    environment:
      - NEW_RELIC_LICENSE_KEY=eu01xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  # 替换为实际密钥
      - METRIC_INCLUDE_PATTERNS=^node_cpu_.*,^node_memory_.*,^kube_pod_.*
      - METRIC_EXCLUDE_PATTERNS=^node_cpu_guest.*  # 排除 guest CPU 指标
      - PROMETHEUS_CONFIG_OUTPUT_PATH=/config/prometheus.yml
    volumes:
      - prometheus-config:/config  # 共享配置目录给 Prometheus
    restart: on-failure  # 配置生成成功后可停止，或按需设置为 "always"

  prometheus:
    image: docker.xuanyuan.run/prom/prometheus:v2.45.0
    volumes:
      - prometheus-config:/etc/prometheus  # 挂载生成的配置文件
      - prometheus-data:/prometheus  # 持久化 Prometheus 数据
    ports:
      - "9090:9090"
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'  # 使用生成的配置
    depends_on:
      - prometheus-configurator  # 确保配置生成后启动 Prometheus
    restart: always

volumes:
  prometheus-config:  # 共享配置卷
  prometheus-data:    # Prometheus 数据卷

4.5 验证配置

1. 启动容器后，检查挂载目录下是否生成 prometheus.yml：

   bash
   cat ./prometheus-config/prometheus.yml
   

   预期输出应包含 remote_write 配置，指向 New Relic 端点：

   yaml
   remote_write:
     - url: "https://metric-api.newrelic.com/prometheus/v1/write?api_key=eu01xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
       write_relabel_configs:
         - source_labels: [__name__]
           regex: "(node_cpu_.*|node_memory_.*|kube_pod_.*)"
           action: keep
         - source_labels: [__name__]
           regex: "node_cpu_guest.*"
           action: drop
   

2. 访问 Prometheus 控制台（http://localhost:9090），在「Status > Configuration」中确认配置加载成功，且「Remote Write Targets」显示正常连接。

五、注意事项

• 密钥安全：NEW_RELIC_LICENSE_KEY 为敏感信息，建议通过容器平台的密钥管理功能（如 Kubernetes Secrets）注入，避免明文暴露。
• 版本兼容性：确保 Prometheus 版本 ≥2.0（支持 Remote Write），New Relic 账号需开通 Prometheus 集成权限。
• 指标量控制：通过 METRIC_INCLUDE_PATTERNS 和 METRIC_EXCLUDE_PATTERNS 合理过滤指标，避免大量无效数据导致的流量和存储成本增加。
• 镜像更新：定期拉取最新镜像（newrelic/newrelic-prometheus-configurator:latest）以获取功能更新和安全补丁。

六、参考链接

• 官方文档：https://github.com/newrelic/newrelic-prometheus-configurator#readme
• New Relic Remote Write 文档：https://docs.newrelic.com/docs/infrastructure/prometheus-integration/get-started/send-prometheus-metrics-new-relic/