6.1 监控与可观测性

6.1 监控与可观测性

在生产环境中运行 Qdrant，监控与可观测性是保障服务稳定性的关键。没有完善的监控体系，你就像在黑夜里开车——不知道油量、不知道速度、不知道前方路况。本章将系统讲解 Qdrant 的监控指标体系、日志管理、健康检查以及告警策略。

Prometheus 指标集成

Qdrant 内置了 Prometheus 指标暴露端点，这是最推荐的监控数据采集方式。

开启指标端点

在 Qdrant 的配置文件中启用 telemetry：

telemetry:
  enabled: true
  metrics:
    port: 6333  # 指标暴露端口
    enable: true
​

启用后，可以通过以下端点获取指标：

GET /metrics
​

该端点返回标准的 Prometheus 文本格式指标，可以直接被 Prometheus Server 抓取。

核心性能指标

Qdrant 暴露了大量细粒度指标，以下是生产环境中最关键的几类：

请求延迟指标

qdrant_requests_count 和 qdrant_requests_duration_seconds 是两个最核心的指标，分别统计请求总数和请求耗时。通过这些指标可以监控：

• 搜索请求的 P50、P95、P99 延迟
• 上行（写入/更新）和下行（查询/搜索）的吞吐量
• 不同 API 端点的响应时间分布

在 Grafana 中配置如下 PromQL 查询：

# 搜索请求 P99 延迟
histogram_quantile(0.99, rate(qdrant_requests_duration_seconds_bucket{method="POST", endpoint="/collections/{collection}/points/search"}[5m]))

# 搜索请求吞吐量 QPS
sum(rate(qdrant_requests_count{endpoint=~"/collections/.*/points/search"}[1m]))
​

向量操作指标

qdrant_collections_vector_count 记录每个集合中的向量总数。这个指标帮助你：

• 追踪数据增长趋势
• 预判容量规划需求
• 检测异常的数据删除

qdrant_collections_optimization_status 反映集合的优化状态，当值不为 green 时，说明集合正在进行内部优化或存在未完成的后台任务。

资源使用指标

Qdrant 通过标准的 Go runtime 指标暴露内存和 CPU 使用情况：

• process_resident_memory_bytes：进程常驻内存
• go_goroutines：协程数量（异常增长可能意味着资源泄漏）
• go_memstats_alloc_bytes：当前堆内存分配

完整指标清单

Qdrant 的指标覆盖以下几个维度：

1. HTTP 请求指标：请求计数、延迟直方图、错误率
2. 集合级别指标：向量数量、索引状态、分片信息
3. 存储层指标：磁盘 I/O、文件描述符、段合并进度
4. 集群指标：节点间通信延迟、分片复制状态、共识模块状态
5. 内部组件指标：HNSW 图操作、量化器性能、过滤执行时间

日志管理

日志级别配置

Qdrant 支持动态调整日志级别，适应不同场景的需求：

log_level: INFO  # 可选: TRACE, DEBUG, INFO, WARN, ERROR
​

生产环境建议使用 INFO 级别。当需要排查问题时，可以临时调整到 DEBUG 或 TRACE 级别，获取更详细的内部执行信息。

日志格式与结构化

Qdrant 默认输出 JSON 格式的结构化日志，方便日志采集系统解析。一条典型的搜索请求日志包含：

{
  "timestamp": "2026-07-06T10:30:00.123Z",
  "level": "INFO",
  "message": "Search request completed",
  "collection": "product_vectors",
  "request_id": "abc-123",
  "search_time_ms": 3.2,
  "results_count": 10,
  "filter_applied": true
}
​

结构化日志的好处是可以精确地按照任意字段进行过滤和聚合分析，这对于排查性能问题和审计非常有价值。

日志采集与存储

对于生产部署，建议将日志采集到集中式日志平台：

方案一：文件日志 + Filebeat

将 Qdrant 日志输出到文件，使用 Filebeat 采集并推送到 Elasticsearch 或 Loki。

方案二：容器日志 + Fluentd

在 Docker/Kubernetes 环境中，使用 Fluentd DaemonSet 采集容器标准输出日志。

方案三：直接推送到日志服务

使用 Vector 等高性能日志路由工具，直接将 Qdrant 日志推送到云端日志服务。

关键日志事件

在日常运维中，需要重点关注以下日志事件：

• WARN 级别的优化延迟警告
• ERROR 级别的磁盘写入失败
• 集群节点间的通信超时
• 分片重新平衡（Rebalance）事件
• 内存压力触发的内部优化暂停

健康检查

HTTP 健康端点

Qdrant 提供了标准的健康检查端点：

GET /healthz
GET /health
GET /metrics/health
​

健康检查端点返回 HTTP 200 状态码表示服务正常，HTTP 503 表示服务异常。这些端点可以集成到负载均衡器和容器编排系统中。

存活检查（Liveness）

存活检查用于判断 Qdrant 进程是否在运行并能够响应请求。配置示例：

# Kubernetes Liveness Probe
livenessProbe:
  httpGet:
    path: /healthz
    port: 6333
  initialDelaySeconds: 30
  periodSeconds: 10
  failureThreshold: 3
​

就绪检查（Readiness）

就绪检查用于判断 Qdrant 是否已经完成初始化并准备好处理流量。Qdrant 在启动时需要加载数据和构建索引，这个过程可能需要一些时间。就绪检查会等到数据加载完成后才返回成功：

# Kubernetes Readiness Probe
readinessProbe:
  httpGet:
    path: /readyz
    port: 6333
  initialDelaySeconds: 60
  periodSeconds: 5
  failureThreshold: 3
​

集合级别健康检查

除了实例级别的健康检查，还可以通过 API 检查特定集合的状态：

GET /collections/{collection_name}
​

返回的响应中包含集合的详细状态信息，包括向量数量、索引状态、分片分布等。可以编写脚本定期检查这些状态，确保每个集合都处于健康状态。

Grafana 仪表板

推荐仪表板布局

一个完整的 Qdrant 监控仪表板应该包含以下几个面板：

概览面板

• 集群节点状态（在线/离线）
• 集合总数和总向量数量
• 全局 QPS 和平均延迟
• 内存和 CPU 使用率

性能面板

• 搜索延迟分布（P50/P95/P99 折线图）
• 写入吞吐量（条/秒 时间序列）
• 请求错误率
• 不同集合的性能对比

资源面板

• 内存使用趋势（堆内存、常驻内存）
• 磁盘使用量和 I/O 延迟
• CPU 使用率（用户态、系统态）
• 网络流量（入/出）

集群面板（仅集群模式）

• 分片分布热力图
• 节点间复制延迟
• 共识模块状态
• 数据平衡进度

告警规则设计

基于 Prometheus 指标，配置以下关键告警规则：

P0 级告警（立即响应）

• Qdrant 服务不可达（健康检查连续失败 3 次）
• 搜索请求 P99 延迟超过 500ms（持续 5 分钟）
• 磁盘使用率超过 90%
• 集群节点离线

P1 级告警（30分钟内响应）

• 搜索请求 P95 延迟超过 200ms（持续 10 分钟）
• 内存使用率超过 80%
• 写入请求错误率超过 1%
• 集合优化状态异常（持续优化超过 30 分钟）

P2 级告警（当日响应）

• 日志中出现 ERROR 级别事件
• 向量数量增长异常（超出预期模型 20%）
• 磁盘 I/O 延迟增加

Prometheus 告警规则示例

- alert: QdrantHighLatency
  expr: histogram_quantile(0.99, rate(qdrant_requests_duration_seconds_bucket[5m])) > 0.5
  for: 5m
  labels:
    severity: critical
  annotations:
    summary: "Qdrant 搜索延迟过高"
    description: "搜索请求 P99 延迟达到 {{ $value }}s，超过 500ms 阈值"
​

分布式追踪

在微服务架构中，Qdrant 通常作为下游服务被调用。为了追踪一个请求的完整链路，需要集成分布式追踪。

Qdrant 支持通过 OpenTelemetry 协议导出追踪数据：

telemetry:
  tracing:
    host: otel-collector
    port: 4317
    enable: true
​

启用后，每个 API 请求都会生成 Span，包含请求路径、处理时间、集合名称等信息。这些 Span 会与调用方的追踪上下文自动关联，形成完整的请求链路视图。

在 Jaeger 或 Tempo 中可以看到类似如下的追踪链路：

用户请求 → API 网关 → 业务服务（embedding 生成）→ Qdrant（向量搜索）→ 业务服务（结果处理）→ 返回

每个环节的耗时一目了然，快速定位性能瓶颈。

总结

Qdrant 的可观测性体系涵盖指标、日志、追踪三大支柱。通过 Prometheus 采集指标、Grafana 可视化、结构化日志集中管理、分布式追踪串联请求链路，可以构建出完整的 Qdrant 运维监控体系。核心要点：

• 开启内置的 Prometheus 指标暴露，重点关注请求延迟和资源使用
• 使用结构化日志并接入集中式日志平台
• 配置存活检查和就绪检查，保障服务可用性
• 设计分层告警策略，确保关键问题及时响应
• 集成分布式追踪，理解请求在系统中的完整路径