跳转到内容
Nantian Gateway

可观测性

Nantian Gateway 从控制面和数据面输出结构化日志、Prometheus 指标和可选的 OpenTelemetry 追踪数据。本页介绍每种可观测性信号的配置方式。

日志

Section titled “日志”

两个组件均使用结构化日志，默认格式为 JSON。结构化日志可直接与 Loki、Elasticsearch 和 Datadog 等日志聚合系统集成。

控制面日志（Go）

Section titled “控制面日志（Go）”

控制面使用 Go 的 log/slog 包：

参数类型默认值说明
log.levelstringinfo最低日志级别：debug、info、warn 或 error
log.formatstringjson输出格式：json 或 text
log.add_sourceboolfalse在日志条目中包含源文件和行号

debug 级别包含协调（reconciliation）详情、配置快照差异和 gRPC 流事件。此级别的输出量远大于 info，不应在生产环境中长期启用。

启用 log.add_source 后，每条日志条目包含 Go 源文件和行号。这会为每次日志调用增加少量开销，但显著有助于调试。

每条 JSON 日志条目包含 time、level、msg 和上下文特定字段。在本地开发中直接阅读日志时，使用 text 格式。

数据面日志（Rust）

Section titled “数据面日志（Rust）”

数据面使用 Rust 的 tracing 框架，支持细粒度的逐模块控制：

参数类型默认值说明
log.levelstringinfo,nantian_core::connectors=offTracing 过滤指令
log.formatstringjson输出格式：json 或 text
log.add_sourceboolfalse包含源位置
log.include_targetboolfalse包含 tracing 目标（Rust 模块路径）
log.include_thread_idsboolfalse包含线程 ID
log.include_thread_namesboolfalse包含线程名称
log.non_blockingbooltrue使用非阻塞日志输出
log.non_blocking_buffered_linesint65536环形缓冲区容量
log.drop_when_fullbooltrue缓冲区满时丢弃日志

level 字段接受 tracing 过滤语法，支持逐模块粒度控制。例如 info,hyper=warn,tower=debug 将全局级别设为 info，将 hyper 降至 warn，将 tower 提升至 debug。默认配置抑制了 nantian_core::connectors 的详细输出。

非阻塞日志对于高吞吐量代理至关重要。使用阻塞输出时，缓慢的日志接收端（磁盘或网络拥塞）可能导致代理线程停滞。环形缓冲区可吸收突发流量，drop_when_full 确保缓冲区溢出时代理继续运行。

指标

Section titled “指标”

两个平面均在可配置的端点上暴露 Prometheus 指标。

控制面指标

Section titled “控制面指标”

控制面在配置的路径（默认：/metrics）上暴露 HTTP 指标端点。指标包括：

  • 协调计数器 — 已处理的 Kubernetes 资源事件数、遇到的错误数以及生成的配置快照数
  • gRPC 流指标 — 活跃连接数、发送和接收的消息数以及连接持续时间
  • Go 运行时指标 — goroutine 数量、内存分配和 GC 统计信息

数据面指标

Section titled “数据面指标”

数据面在其 admin 监听器的 /metrics 路径上暴露 Prometheus 指标。没有独立的指标服务器需要启用或配置——该端点与 admin 地址共用：

参数类型默认值说明
admin_addrstring"127.0.0.1:19080"admin 监听地址；在此提供 /metrics 及健康检查端点

在 Kubernetes 中，Helm chart 通过数据面 metrics Service 的 19080 端口暴露该端点。

关键数据面指标：

  • 请求计数器 — 总请求数，按 HTTP 方法、状态码和路由分组
  • 延迟直方图 — 请求持续时间百分位数（p50、p95、p99）
  • 连接指标 — 活跃连接数、连接速率和连接持续时间
  • 上游指标 — 后端连接池命中/未命中、后端延迟和后端错误
  • AI 网关指标 — Token 计数、提供商延迟和速率限制执行情况

完整指标参考请参阅指标参考。

链路追踪

Section titled “链路追踪”

OpenTelemetry 链路追踪为可选功能，在数据面配置的 log.open_telemetry 下配置：

参数类型默认值说明
log.open_telemetry.enabledboolfalse启用 OpenTelemetry 链路追踪
log.open_telemetry.endpointstring""OTLP 收集器端点
log.open_telemetry.protocolstring"grpc"OTLP 传输方式（grpc 或 http）
log.open_telemetry.timeoutMsint3000导出超时（毫秒）
log.open_telemetry.insecureboolfalse连接收集器时禁用 TLS
log.open_telemetry.sampleRatiofloat1.0采样比例（0.0 至 1.0）
log.open_telemetry.serviceNamestring"nantian-dataplane"追踪数据中的服务名称
log.open_telemetry.serviceNamespacestring""追踪数据中的服务命名空间

启用后，数据面传播 W3C trace-context 头并将 span 导出到配置的 OTLP 收集器。追踪覆盖请求生命周期：路由匹配、请求头转换、上游请求和响应。

sampleRatio 控制生成追踪的请求比例（默认 1.0 追踪全部请求）。高流量生产环境可调低以减少追踪量与存储成本。

Sentry 错误追踪

Section titled “Sentry 错误追踪”

数据面支持 Sentry 错误追踪，提供完整的 APM 能力：错误/panic 捕获、性能追踪、事件面包屑和版本追踪。

参数类型默认值说明
log.sentry.enabledboolfalse启用 Sentry 错误追踪
log.sentry.dsnstring""Sentry DSN（数据源名称）
log.sentry.environmentstring""环境名称（production、staging、development）
log.sentry.sample_ratefloat1.0事件采样率（0.0 至 1.0）
log.sentry.traces_sample_ratefloat0.01性能事务采样率（0.0 至 1.0）
log.sentry.attach_stacktracebooltrue在错误事件中附加堆栈跟踪
log.sentry.send_default_piiboolfalse发送个人身份信息
log.sentry.debugboolfalse启用 Sentry SDK 调试日志

Sentry 默认处于关闭状态。要启用，请将 log.sentry.enabled 设为 true 并提供有效的 log.sentry.dsn。DSN 可从 Sentry 项目设置中获取。

启用后，数据面会捕获：

  • 错误和 panic — 所有 Rust panic 和未处理错误都会被捕获并上报
  • 性能追踪 — 请求处理中的事务和 span
  • 事件面包屑 — 导致错误的上下文事件
  • 版本追踪 — 将事件与部署的数据面版本关联

Sentry 是追踪事件的额外消费者，不会替代现有的 OpenTelemetry 链路追踪。

Prometheus 采集

Section titled “Prometheus 采集”

配置 Prometheus 采集数据面指标：

scrape_configs:
  - job_name: nantian-gw-dataplane
    kubernetes_sd_configs:
      - role: pod
        namespaces:
          names: [nantian-gw]
    relabel_configs:
      - source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_name]
        action: keep
        regex: nantian-gw-dataplane
      - source_labels: [__meta_kubernetes_pod_container_port_number]
        action: keep
        regex: "19080"

下一步

Section titled “下一步”