FastDeploy/docs/zh/observability

Observability 示例配置 (examples/observability)

该目录提供了一套完整的、基于 Docker Compose 的可观测性（Observability）示例，包括：

• Prometheus：指标收集
• Grafana：指标可视化
• OpenTelemetry Collector：分布式追踪数据接收与处理

开发者可以使用此示例环境 一键启动本地监控与追踪系统。

先决条件

需要确保提前安装以下组件：

• Docker
• Docker Compose（或新版 Docker CLI 支持 docker compose）

使用方法

整体启动

进入目录：

cd examples/observability

在 examples/observability 目录下执行以下命令即可启动完整的监控和追踪服务：

docker compose -f docker-compose.yaml up -d

启动完成后可访问：

• Prometheus 访问: http://localhost:9090
• Grafana 访问: http://localhost:3000
• OTLP 接收端: 应用程序应将 Traces 发送到 OTel Collector 的默认端口（通常是 4317 或 4318）。
  • grpc: 4317端口
  • http: 4318端口
• Jeager 访问：http://localhost:16886

【注意事项】：

• Prometheus的抓取地址换成自己的地址

• Grafana的展示端口映射成自己可以访问的端口

• Jaeger的展示端口映射成自己可以访问的端口

• 如果启动了整体服务就不需要再单独去启动子服务了

metrics启动

进入目录：

cd examples/observability/metrics

在 examples/observability 目录下执行以下命令即可启动完整的监控和追踪服务：

docker compose -f prometheus_compose.yaml up -d

启动完成后可访问：

• Grafana 访问: http://localhost:3000

trace启动

进入目录：

cd examples/observability/tracing

在 examples/observability 目录下执行以下命令即可启动完整的监控和追踪服务：

docker compose -f tracing_compose.yaml up -d

启动完成后可访问：

• OTLP 接收端:应用程序应将 Traces 发送到 OTel Collector 的默认端口（通常是 4317 或 4318）。
  • grpc: 4317端口
  • http: 4318端口
• Jeager 访问：http://localhost:16886

目录结构与文件说明

核心启动文件

文件名	作用	详情
docker-compose.yaml	主启动文件	定义并启动完整的可观测性组件（Prometheus、Grafana、OTel Collector、Jaeger）。这是启动整个 Observability 环境的唯一入口。

指标 (Metrics) 与监控配置

文件/目录	作用	详情
metrics	指标配置根目录	包含所有与指标收集和 Prometheus 相关的配置。
prometheus.yaml	Prometheus 主配置	定义抓取目标（scrape targets）、全局采集参数，并可选地配置记录规则（recording rules）。所有监控端点都在此定义。
prometheus_compose.yaml	Prometheus Docker 配置	定义 Prometheus 容器、卷挂载和网络设置。
grafana/datasources/datasource.yaml	数据源配置	定义 Grafana 连接 Prometheus 的方式。
grafana/dashboards/config/dashboard.yaml	仪表板加载配置	指定仪表板 JSON 文件所在路径。
grafana/dashboards/json/fastdeploy-dashboard.json	仪表板	包含 fastdeploy监控指标的可视化布局与查询定义。

分布式追踪 (Tracing) 配置

文件/目录	作用	详情
tracing	追踪配置根目录	包含所有与分布式追踪相关的配置。
opentelemetry.yaml	OTel Collector 配置	定义 Collector 的数据管道： • receivers：接收 OTLP 数据（traces, metrics, logs） • processors：处理与批次化数据 • exporters：将数据导出到追踪后端（如 Jaeger）或文件 • extensions：健康检查、pprof 和 zpages • pipelines：定义 traces、metrics 和 logs 的完整处理流程
tracing_compose.yaml	Tracing Docker 配置	定义 OTel Collector 和 Jaeger 的容器配置。

4. 如何定制

4.1 修改指标抓取目标

若应用程序端口、路径更改，请编辑：

metrics/prometheus.yaml

4.2 调整追踪采样率或处理逻辑

编辑：

tracing/opentelemetry.yaml

4.3 添加自定义 Grafana 仪表盘

1. 新增 JSON 仪表盘至：

grafana/dashboards/json/

1. 在下方文件中注册该仪表盘，使 Grafana 自动加载：

grafana/dashboards/config/dashboard.yaml