Prometheus Remote Write 接入

Remote Write 是迁移到 VictoriaMetrics 的低风险起点：Prometheus 继续抓取目标和执行本地规则，同时异步将样本写入远端存储。确认远端数据完整、Grafana 查询兼容后，再评估缩短本地保留期或由 vmagent 接管采集。切换过程中不要同时修改采集规则、标签和数据源，否则难以定位数据差异。

1. 写入路径与前置检查

Exporter --> Prometheus --> Remote Write --> VictoriaMetrics --> Grafana
                 |                                  |
                 +--> 本地 TSDB 与本地规则             +--> 长期查询

上线前确认以下事项：

• Prometheus 可以通过网络和 DNS 访问 VictoriaMetrics 的写入地址；单机写入路径为 /api/v1/write。
• 集群版应该写入 vminsert 的地址，不能直接写入 vmstorage。
• 为每个集群写入固定的 cluster 或 environment 外部标签；标签一旦投入使用，不能随意改名。
• 目标的指标基数和 Prometheus 的 Remote Write 队列指标已有基线，方便判断接入后的资源变化。

2. 配置 Prometheus

以下片段加入 Prometheus 的 prometheus.yml。队列参数是起始值，不是通用最优值；应在预发或压测环境按样本速率、网络 RTT、后端吞吐和内存使用调优。

global:
  external_labels:
    # 固定来源集群，避免多集群写入时出现相同序列互相覆盖或难以筛选。
    cluster: production-shanghai
    environment: production

remote_write:
  - name: victoriametrics
    # 单机版的写入端点；集群版将域名替换为 vminsert 的 Service。
    url: http://victoriametrics.monitoring.svc:8428/api/v1/write
    queue_config:
      # 初始并发数，增加前必须观察 CPU、内存、网络与后端写入延迟。
      max_shards: 8
      # 每个分片缓存样本数；过大可能显著抬高 Prometheus 内存。
      capacity: 10000
      # 每次发送的最大样本数，在网络开销和单次请求大小之间折中。
      max_samples_per_send: 2000
    write_relabel_configs:
      # 丢弃高频且无业务价值的自监控指标，规则需先经过基数评审。
      - source_labels: [__name__]
        regex: prometheus_http_.+
        action: drop

敏感环境必须经 HTTPS 或服务网格加密传输，并配置认证。不要把 Basic Auth 密码、Bearer Token 或客户端私钥直接提交到 Git；应通过 Secret、外部密钥系统或部署平台注入。

3. 部署单机 VictoriaMetrics

下面是最小的 Kubernetes 示例。数据卷应由生产 StorageClass 提供，ReadWriteOnce 单卷适合单实例；它不提供跨节点高可用。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: victoriametrics
  namespace: monitoring
spec:
  replicas: 1 # 单机形态只能运行一个写入实例并挂载自己的数据卷。
  selector:
    matchLabels:
      app.kubernetes.io/name: victoriametrics
  template:
    metadata:
      labels:
        app.kubernetes.io/name: victoriametrics
    spec:
      containers:
        - name: victoria-metrics
          # 固定为团队验证过的版本，升级前阅读发行说明并在预发验证。
          image: victoriametrics/victoria-metrics:<validated-version>
          args:
            # 数据必须写入持久卷，而不是容器可写层。
            - -storageDataPath=/var/lib/victoria-metrics-data
            # 保留期根据容量、成本与合规要求制定。
            - -retentionPeriod=90d
          ports:
            - name: http
              containerPort: 8428
          resources:
            requests:
              cpu: 500m
              memory: 1Gi
            limits:
              cpu: "2"
              memory: 4Gi
          volumeMounts:
            - name: data
              mountPath: /var/lib/victoria-metrics-data
      volumes:
        - name: data
          persistentVolumeClaim:
            # PVC 应预先创建并绑定到符合 IOPS 要求的 StorageClass。
            claimName: victoriametrics-data
---
apiVersion: v1
kind: Service
metadata:
  name: victoriametrics
  namespace: monitoring
spec:
  selector:
    app.kubernetes.io/name: victoriametrics
  ports:
    - name: http
      port: 8428
      targetPort: http

4. 验证写入和查询

先等待至少两个抓取周期，再用 API 和 Prometheus 自监控指标验证。/health 只能证明 HTTP 服务可响应，不能证明 Remote Write 没有积压。

# 确认 VictoriaMetrics 已就绪，并检查容器是否持续重启。
kubectl -n monitoring get pods -l app.kubernetes.io/name=victoriametrics

# 从集群内查询指标；结果应含有写入的 cluster、environment 等外部标签。
kubectl -n monitoring run vm-query --rm -i --restart=Never \
  --image=curlimages/curl:8.12.1 -- \
  curl -fsSG http://victoriametrics:8428/api/v1/query \
  --data-urlencode 'query=up'

# Remote Write 队列必须不能持续增长；按 remote_name 筛选新增的远端。
curl -fsS http://prometheus.monitoring.svc:9090/metrics | \
  rg 'prometheus_remote_storage_(samples_pending|failed_samples_total|samples_retried_total).*victoriametrics'

Grafana 可将数据源 URL 设置为 http://victoriametrics.monitoring.svc:8428。先对比 up、rate()、聚合和告警规则的结果，再迁移生产看板。查看历史区间时必须选择同一时间范围，避免把 Prometheus 本地保留期外的数据误判为差异。

5. 常见问题

现象	优先检查
samples_pending 持续增加	VictoriaMetrics 写入延迟、网络丢包、磁盘 IOPS、写入限流和队列分片数
Grafana 无数据	数据源 URL、时间范围、外部标签过滤条件与写入是否已完成
远端数据量异常大	write_relabel_configs、标签基数、重复 Prometheus 副本和短生命周期 Job
同一指标出现重复序列	多个写入端缺少区分标签，或 HA 副本去重策略没有设计

不要在未验证队列清空和查询完整性前删除 Prometheus 本地数据。远程写入积压期间即使服务最终恢复，超过 WAL 可重放窗口的样本仍可能丢失。