跳到主要内容

独立 Collector 调试验证

本文用于先验证 FreeKit Host 到 OpenTelemetry Collector 的网络和 OTLP 配置。Collector 使用 debug exporter 把接收到的信号摘要写入自身日志，不提供查询页面，也不持久化数据。

FreeKit.Host / Job / Message
    ├── OpenTelemetry SDK: Trace + Metrics
    └── Serilog OTLP Sink: Logs
                    │ OTLP/gRPC :4317
                    ▼
        OpenTelemetry Collector
                    │
                    └── debug exporter → docker logs

完成验证后，应切换到 OpenObserve 完整部署 或其他真实后端，不要长期使用高噪声 debug 输出。

1. 创建配置目录​

在服务器上创建独立目录：

sudo mkdir -p /opt/otel-collector-debug
cd /opt/otel-collector-debug

创建 /opt/otel-collector-debug/config.yaml：

extensions:
  health_check:
    endpoint: 0.0.0.0:13133

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 256
    spike_limit_mib: 64
  batch:
    timeout: 5s
    send_batch_size: 1024

exporters:
  debug:
    verbosity: basic

service:
  extensions: [health_check]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [debug]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [debug]
  telemetry:
    logs:
      level: info

该配置监听：

  • 4317：OTLP/gRPC，FreeKit 容器推荐使用
  • 4318：OTLP HTTP/protobuf
  • 13133：Collector 健康检查

2. 创建共享网络​

仓库的单容器部署脚本使用 freekit-net：

sudo docker network inspect freekit-net >/dev/null 2>&1 || \
  sudo docker network create freekit-net

Collector 和待验证的应用容器必须同时加入该网络。若应用由 build/compose/freekit_pro_modules/docker-compose.yml 启动，注意该 Compose 当前使用自己的默认网络，需显式接入 freekit-net 后才能使用容器名访问 Collector。

3. 启动 Collector​

版本与仓库完整部署保持一致：

sudo docker pull otel/opentelemetry-collector-contrib:0.157.0

sudo docker run -d \
  --name otel-collector \
  --restart unless-stopped \
  --network freekit-net \
  --memory 512m \
  -v /opt/otel-collector-debug/config.yaml:/etc/otelcol-contrib/config.yaml:ro \
  otel/opentelemetry-collector-contrib:0.157.0 \
  --config=/etc/otelcol-contrib/config.yaml

这里没有映射 4317/4318 到宿主机。相同 Docker 网络内的容器可通过 http://otel-collector:4317 通信，同时避免把无认证 OTLP receiver 暴露到公网。

检查启动状态：

sudo docker ps --filter name=otel-collector
sudo docker logs --tail 100 otel-collector

用网络内临时容器检查健康端点：

sudo docker run --rm --network freekit-net curlimages/curl:8.12.1 \
  -fsS http://otel-collector:13133/

4. 配置 Trace 与 Metrics​

容器方式推荐使用环境变量：

-e OpenTelemetry__Enabled=true \
-e OTEL_SERVICE_NAME=freekit-host \
-e OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317 \
-e OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
-e OpenTelemetry__FreeSql__Enabled=true \
-e OpenTelemetry__FreeSql__IncludeSql=false

服务名分别使用：

宿主OTEL_SERVICE_NAME
FreeKit.Hostfreekit-host
FreeKit.Job.Hostfreekit-job
FreeKit.MessageHandler.Hostfreekit-message

也可以在各 Host 的配置文件中使用：

{
  "OpenTelemetry": {
    "Enabled": true,
    "ServiceName": "freekit-host",
    "FreeSql": {
      "Enabled": true,
      "IncludeSql": false
    },
    "Otlp": {
      "Endpoint": "http://otel-collector:4317",
      "Protocol": "grpc"
    }
  }
}

三个生产配置当前已指向该容器名，但 endpoint 可达的前提仍是网络互通。

5. Logs 需要单独确认​

AddFreeKitObservability 只注册 Trace/Metrics。Logs 由 Serilog.Sinks.OpenTelemetry 单独发送。三个生产 appsettings.Production.json 已配置 endpoint http://otel-collector:4317；如果当前环境没有加载生产配置，则只设置 OTEL_EXPORTER_OTLP_ENDPOINT 并不会自动启用 Serilog OTLP Sink。

因此建议分两步验证：

  1. 先通过 SDK 验证 Trace/Metrics。
  2. 再确认当前 Host 实际加载的 Serilog.WriteTo 中存在名为 OpenTelemetry 的 Sink，且 endpoint 指向此 Collector。

切换 endpoint 时需要同时调整两条配置链。完整区别见 可观测性总览与应用接入。

6. 产生并确认遥测数据​

访问主 Host 的普通 API，或触发 Job/Message 的数据库、HTTP 或任务处理。不要只访问 /health，因为应用侧明确过滤了该路径的 ASP.NET Core Trace。

查看最近日志：

sudo docker logs --since 5m otel-collector

debug exporter 收到数据时会出现类似摘要：

Traces  # of resource spans: ...
Metrics # of resource metrics: ...
Logs    # of resource logs: ...

根据目标逐项判断：

现象优先检查
三种信号都没有Docker 网络、endpoint、协议、Collector 配置解析错误
有 Metrics、无 Trace是否只请求 /health；是否发生了可采集的请求/HttpClient/FreeSql 操作
有 Trace/Metrics、无 LogsSerilog OTLP Sink 是否加载、endpoint 是否一致、最低日志级别
有 HTTP Trace、无数据库 SpanOpenTelemetry:FreeSql:Enabled、是否实际执行 FreeSql 命令
服务名不对OTEL_SERVICE_NAME 是否覆盖了 Host 默认值

检查两个容器是否同网：

sudo docker network inspect freekit-net

Containers 中应同时包含 otel-collector 和待验证的业务容器。

7. 非 Docker 或跨主机场景​

只有本机进程或其他主机确实需要访问 Collector 时，才映射 receiver 端口。单机调试建议只绑定回环地址：

-p 127.0.0.1:4317:4317 \
-p 127.0.0.1:4318:4318 \
-p 127.0.0.1:13133:13133

本机 .NET 进程的 endpoint 随后使用：

http://127.0.0.1:4317

跨服务器场景不要把无认证、无 TLS 的 4317/4318 直接开放公网。至少需要来源 IP 限制、TLS、认证、发送队列、容量限制和 Collector 自身监控。更推荐让应用和 Collector 通过私有网络通信。

8. 切换到真实后端​

验证完成后停止并删除调试 Collector，再部署完整栈，避免容器名和端口冲突：

sudo docker rm -f otel-collector

然后按 OpenObserve 完整部署 启动仓库配置。完整配置会把 debug exporter 替换为带 Basic Auth 的 otlp_http/openobserve，并额外采集宿主、MySQL 和 Redis 指标。

Collector 临时不可用一般不会阻止业务请求，但内存队列耗尽后遥测可能丢失。不要把 debug Collector 当作可靠存储或审计系统。

相关文档与源码​

  • 可观测性总览与应用接入
  • OpenObserve 完整部署
  • src/BuildingBlocks/IGeekFan.FreeKit.Web/Extensions/ObservabilityExtensions.cs
  • src/BuildingBlocks/IGeekFan.FreeKit.Web/Extensions/FreeSqlObservability.cs
  • src/Services/Host/FreeKit.Host/appsettings.Production.json
  • src/Services/Host/FreeKit.Job.Host/appsettings.Production.json
  • src/Services/Host/FreeKit.MessageHandler.Host/appsettings.Production.json
  • build/observability/otel-collector.yaml