newrelic/nri-prometheus

New Relic Prometheus OpenMetrics Integration 镜像文档

1. 镜像概述和主要用途

New Relic Prometheus OpenMetrics Integration 镜像是 New Relic 提供的专用工具，用于将 Prometheus 或兼容 OpenMetrics 格式的指标数据无缝集成到 New Relic 平台。该镜像通过抓取 Prometheus 数据源（如 Prometheus 服务器、暴露 OpenMetrics 端点的应用或服务），将指标转换为 New Relic 兼容格式，并发送至 New Relic 进行存储、分析和可视化，帮助用户利用 New Relic 的高级监控、告警和分析能力统一管理 Prometheus 生态的指标数据。

2. 核心功能和特性

• 多格式支持：兼容 Prometheus exposition 格式和 OpenMetrics 标准，支持主流 Prometheus 数据源（如 Prometheus 服务器、Prometheus 导出器、Kubernetes 指标等）。
• 灵活的数据抓取：可配置抓取间隔、目标端点、指标过滤规则，支持静态目标和动态服务发现（如 Kubernetes 服务发现）。
• 指标转换与增强：自动将 Prometheus 标签映射为 New Relic 属性，支持自定义标签添加，提升指标上下文信息。
• 高效数据传输：采用批处理机制发送指标，支持压缩传输，降低网络带宽占用。
• 安全性：支持 TLS 加密连接（用于 Prometheus 端点和 New Relic 后端），支持基本认证（用于保护 Prometheus 端点访问）。
• 配置简化：通过环境变量或配置文件灵活配置，支持容器化部署（Kubernetes、Docker Compose 等）。

3. 使用场景和适用范围

3.1 使用场景

• Prometheus 数据集中管理：将多环境（开发、测试、生产）的 Prometheus 指标集中发送至 New Relic，实现统一监控视图。
• Prometheus 与 New Relic 协同：利用 New Relic 的高级分析（如异常检测、根因分析）增强 Prometheus 指标的可观测性。
• Kubernetes 监控集成：抓取 Kubernetes 集群内 Prometheus 指标（如 node-exporter、kube-state-metrics），结合 New Relic Kubernetes 监控能力。
• 迁移与扩展：从 Prometheus 原生存储平滑迁移至 New Relic，无需修改现有 Prometheus 部署。

3.2 适用范围

• 使用 Prometheus 作为监控工具的开发/运维团队。
• 需要将 Prometheus 指标与 New Relic 日志、APM 数据关联分析的组织。
• 需跨团队共享 Prometheus 指标或满足合规性要求（如数据留存策略）的企业。

4. 使用方法和配置说明

4.1 前提条件

• 拥有 New Relic 账号（注册地址：New Relic 官网）。
• 获取 New Relic ingestion API 密钥（需具备指标写入权限，创建路径：New Relic 控制台 > API 密钥 > Ingest - License）。
• 目标 Prometheus 或 OpenMetrics 端点可访问（需网络连通性，如防火墙策略开放）。

4.2 拉取镜像

从 New Relic 容器镜像仓库拉取最新版本（推荐）或指定版本：

bash
docker pull newrelic/prometheus-openmetrics-integration:latest

4.3 运行容器（Docker Run）

通过 docker run 命令启动容器，核心配置通过环境变量传入：

bash
docker run -d \
  --name newrelic-prometheus-integration \
  -e NEW_RELIC_API_KEY=<YOUR_NEW_RELIC_INGEST_API_KEY> \
  -e PROMETHEUS_ENDPOINT=http://<prometheus-ip>:9090/metrics \  # Prometheus 指标端点
  -e SCRAPE_INTERVAL=60s \  # 指标抓取间隔（默认 60s）
  -e NEW_RELIC_REGION=us \  # New Relic 区域（us 或 eu，默认 us）
  -e FILTER_INCLUDE_METRICS="node_cpu_*,node_memory_*" \  # 可选：仅包含指定指标（支持通配符）
  -v /path/to/custom-config.yml:/etc/newrelic/config.yml \  # 可选：挂载自定义配置文件
  newrelic/prometheus-openmetrics-integration:latest

4.4 Docker Compose 配置

创建 docker-compose.yml 文件，定义服务配置：

yaml
version: '3'
services:
  prometheus-integration:
    image: newrelic/prometheus-openmetrics-integration:latest
    container_name: newrelic-prometheus-integration
    restart: always
    environment:
      - NEW_RELIC_API_KEY=<YOUR_NEW_RELIC_INGEST_API_KEY>  # 必填：New Relic Ingest API 密钥
      - PROMETHEUS_ENDPOINT=http://prometheus:9090/metrics  # 必填：Prometheus 指标端点（支持多个，用逗号分隔）
      - SCRAPE_INTERVAL=30s  # 可选：抓取间隔，默认 60s
      - NEW_RELIC_REGION=us  # 可选：区域（us/eu），默认 us
      - TLS_ENABLED=true  # 可选：是否启用 TLS 连接 Prometheus 端点，默认 false
      - BASIC_AUTH_USER=admin  # 可选：Prometheus 端点基本认证用户名（若启用）
      - BASIC_AUTH_PASSWORD=secret  # 可选：Prometheus 端点基本认证密码（若启用）
    volumes:
      - ./custom-config.yml:/etc/newrelic/config.yml  # 可选：挂载自定义配置文件
    depends_on:
      - prometheus  # 若 Prometheus 也在 Compose 中部署，需添加依赖

  # 示例：Prometheus 服务（若需在同一 Compose 中部署）
  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

4.5 配置文件说明

除环境变量外，可通过挂载配置文件（如 custom-config.yml）实现更复杂配置（如动态服务发现、指标转换规则）。配置文件示例：

yaml
# 全局配置
global:
  scrape_interval: 30s  # 覆盖环境变量 SCRAPE_INTERVAL
  timeout: 10s

# New Relic 配置
new_relic:
  api_key: <YOUR_NEW_RELIC_API_KEY>  # 可覆盖环境变量
  region: eu  # 可覆盖环境变量
  metrics:
    include: ["node_*", "kube_*"]  # 仅包含指定指标（优先级高于环境变量 FILTER_INCLUDE_METRICS）
    exclude: ["go_*"]  # 排除指定指标

# Prometheus 目标配置（支持静态目标和服务发现）
prometheus:
  targets:
    static_configs:
      - targets: ["prometheus:9090", "node-exporter:9100"]  # 静态目标列表（覆盖环境变量 PROMETHEUS_ENDPOINT）
        labels:  # 为目标添加自定义标签
          environment: "production"
          cluster: "europe-west1"
    # 示例：Kubernetes 服务发现（需配置 Kubernetes API 访问）
    kubernetes_sd_configs:
      - role: pod
        namespaces:
          names: ["default"]

5. 配置参数和环境变量

5.1 核心环境变量（优先级：环境变量 > 配置文件 > 默认值）

5.2 高级环境变量

6. 常见问题

Q1：指标未出现在 New Relic 控制台？

• 检查 NEW_RELIC_API_KEY 是否正确（需具备 "Ingest - License" 权限）。
• 确认 PROMETHEUS_ENDPOINT 可访问（容器内执行 curl <endpoint> 验证连通性）。
• 查看容器日志（docker logs <container-name>），排查抓取或发送错误。

Q2：如何监控 Kubernetes 集群内的 Prometheus 指标？

• 使用配置文件的 kubernetes_sd_configs 开启服务发现，或通过环境变量 PROMETHEUS_ENDPOINT 指定 kube-state-metrics、node-exporter 等端点。
• 推荐通过 Kubernetes DaemonSet 或 Deployment 部署该镜像，确保集群内网络可达。

Q3：如何限制发送到 New Relic 的指标数量？

• 通过 FILTER_INCLUDE_METRICS 或配置文件 new_relic.metrics.include 仅包含关键指标。
• 使用 FILTER_EXCLUDE_METRICS 排除低价值指标（如高频噪声指标）。

7. 参考链接

• New Relic Prometheus 集成官方文档
• New Relic API 密钥创建指南
• Prometheus OpenMetrics 格式规范