可观测性
IoT DC3 的日志聚合与指标监控是一套可选栈：一条命令 make up-optional 拉起 EMQX、ELK（Elasticsearch + Logstash + Kibana）、Prometheus 与 Grafana。读完这页你能知道每个组件干什么、暴露在哪个端口、怎么把服务日志接进 Kibana、把服务指标接进 Grafana，以及用哪些环境变量调堆内存和开关 APM；链路追踪（Jaeger）与告警该盯什么，也在这页。
你在这里：已能部署并启动平台，想给运行中的环境加上日志检索与指标看板。
可观测性栈为可选
这套栈不在默认启动范围内。make up-db（PostgreSQL + RabbitMQ）与应用栈起来后平台即可运行；可观测性组件需要单独 make up-optional 才会启动，对内存有额外要求，按需开启。
为什么单独成栈
把可观测性从核心栈里拆出来，是为了让"跑通平台"和"观测平台"两件事互不绑定。评估者只想验证黄金路径时，不必为 Elasticsearch 付出几百兆堆内存；运维要排障、看趋势时，再把这套栈叠加上来即可。它由 dc3/docker-compose-optional.yml 定义，与 db/dev/app 三个核心栈平行，共享同一个 dc3net 网络，因此各服务能用容器别名（如 dc3-elasticsearch、dc3-prometheus）互相寻址。
这套栈解决两类问题：
- 日志（logs）——服务输出的 JSON 文件日志由 Logstash 收集、归一，写入 Elasticsearch，在 Kibana 里按字段检索与关联。
- 指标（metrics）——Prometheus 周期抓取各服务与 exporter 暴露的指标，Grafana 把它们画成看板。
此外 EMQX 作为 MQTT broker 一并放在这个栈里，供 MQTT 类驱动与设备直连接入。
组件与端口
make up-optional 一次拉起以下容器（端口为宿主机发布端口，默认绑定 127.0.0.1，由 DC3_BIND_HOST 控制）。下表只作速查，逐项作用见后文。
| 容器 | 作用 | 宿主机端口（默认） | 控制变量 |
|---|---|---|---|
dc3-emqx | MQTT broker + Dashboard | MQTT 31883、Dashboard 18083、WS 38083、MQTTS 38883 | DC3_EMQX_MQTT_PORT / DC3_EMQX_DASHBOARD_PORT |
dc3-elasticsearch | 日志存储与检索引擎 | 内部 9200（不发布） | DC3_ES_JAVA_OPTS |
dc3-logstash | 日志采集与归一管道 | 内部（不发布） | DC3_LS_JAVA_OPTS |
dc3-kibana | 日志检索与可视化 UI | 5601 | DC3_KIBANA_PORT |
dc3-apm | APM（应用性能）数据接收 | 内部（不发布） | APM_AGENT_ENABLE（应用侧开关） |
dc3-prometheus | 指标抓取与时序存储 | 内部 9090（不发布），保留 7d | — |
dc3-postgres-exporter | PostgreSQL 指标导出 | 内部（不发布） | — |
dc3-nginx-exporter | 前端 nginx 指标导出 | 内部（不发布） | — |
dc3-grafana | 指标看板 UI | 3000 | DC3_GRAFANA_PORT / GF_SERVER_ROOT_URL |
只想起其中几个？
不必整栈拉起。用 SERVICES 过滤，例如只要监控：
make up STACK=optional SERVICES="prometheus grafana"EMQX 的端口变量见 环境变量详解——MQTT 驱动连 31883、运维登录 Dashboard 看连接情况走 18083 。Kibana（5601）与 Grafana（3000）是两个面向人的入口：前者查日志，后者看指标。Elasticsearch、Logstash、APM、Prometheus 与两个 exporter 都不对宿主机发布端口，只在 dc3net 内部互通——它们是后端管线，不直接给人访问。
日志如何接入（ELK）
服务以 JSON 文件形式落日志（消息风格见日志规范），落盘目录通过名为 logs 的 Docker 卷共享：核心栈把日志写进该卷，Logstash 把同一个卷挂载到 /usr/share/logstash/dc3/logs 读取。Logstash 解析、打标后写入 Elasticsearch，最终在 Kibana 里检索。
接入步骤就是把这条链路跑起来：
- 先确保核心栈（dev 或 app）在跑，日志已写进
logs卷。 make up-optional启动 ELK，Logstash 自动从logs卷读取。- 浏览器打开
http://localhost:5601进入 Kibana，按服务名、事件名检索；tenantId目前只作为消息参数出现在正文里，只能全文匹配（字段级检索要等 MDC 接线，见日志规范）。
Elasticsearch 吃内存，先调堆
Elasticsearch 与 Logstash 的 JVM 堆默认偏小，便于在开发机起得来：DC3_ES_JAVA_OPTS 默认 -Xms512m -Xmx512m， DC3_LS_JAVA_OPTS 默认 -Xms256m -Xmx256m。生产或日志量大时按机器内存上调，例如：
DC3_ES_JAVA_OPTS="-Xms2g -Xmx2g" make up-optionalAPM 默认关闭
dc3-apm 容器随 ELK 一起起来，但应用是否上报 APM 数据由 APM_AGENT_ENABLE 决定，默认 false。该变量作用在核心栈（ docker-compose.yml / docker-compose-dev.yml）上，控制服务是否挂载 Java APM Agent 向 dc3-apm 上报性能数据。要启用需在启动核心栈时显式打开：
APM_AGENT_ENABLE=true make up STACK=app起了 apm 容器 ≠ 开了 APM
只 make up-optional 不会自动采集 APM——dc3-apm 仅是接收端。没有把核心栈的 APM_AGENT_ENABLE 设为 true，应用不会挂载 Agent，也就没有数据上报。
指标如何接入（Prometheus / Grafana）
各服务通过 Micrometer 暴露 Prometheus 格式的指标端点；Prometheus 按其配置周期抓取这些端点，并抓取两个 exporter—— postgres-exporter（数据库指标）与 nginx-exporter（前端 nginx 指标）。Prometheus 本地保留 7 天时序数据（ --storage.tsdb.retention.time=7d），Grafana 以它为数据源画看板。
指标端点在哪
各中心与网关都在自身服务端口暴露 /actuator/prometheus——管理端点没有独立端口，带 base-path 的服务要加前缀（如鉴权中心是 http://<host>:8300/auth/actuator/prometheus；各服务的就绪路径见服务清单）。抓取目标列表烧在 dc3-prometheus 镜像内，仓库里看不到；改了网络或端口要核对镜像内的 /etc/prometheus/prometheus.yml。驱动服务不在抓取面里：驱动不依赖 dc3-common-web，没有 actuator 端点。
JVM、HTTP、R2DBC 等 Micrometer 基础指标之外，平台当前只有智能中心注册了业务指标：
| 指标 | 类型 | 标签 | 看什么 |
|---|---|---|---|
agentic.chat.requests / agentic.chat.duration | Counter / Timer | tenant、provider、model、result | 聊天量与耗时，result 区分成败 |
agentic.chat.tokens | Counter | tenant、provider、model | token 消耗 |
agentic.tool.calls / agentic.tool.duration | Counter / Timer | tool、domain、outcome | 工具调用频次与耗时 |
agentic.check.results | Counter | kind、result | L1/L2 连通性检查通过率 |
agentic.transport.global.permits / agentic.transport.provider.permits | Gauge | 后者带 tenant、provider | 并发槽位余量 |
agentic.transport.acquire.timeout | Counter | scope | 拿不到槽位的频率，涨了就该调限流参数 |
预置看板
Grafana 不用从零拼：数据源 DC3 Postgres（直连 dc3_history schema，TimescaleDB）和看板 Point Value Overview 随可选栈自动置备，起栈即有。看板三段：总览（当前范围样本数、活跃位号/设备、静默位号、每分钟摄取速率）→ 单位号趋势 → 位号清单（最新值、最后采集时间、样本数）。
接入步骤：
make up-optional启动 Prometheus、两个 exporter 与 Grafana。- 浏览器打开
http://localhost:3000进入 Grafana 看板。 - Grafana 的外部访问地址由
GF_SERVER_ROOT_URL控制（默认http://localhost:3000）；若通过反向代理或非本机访问，相应调整该变量，避免生成的链接指向localhost。
# 反代/远程访问时修正 Grafana 根地址（示例值）
GF_SERVER_ROOT_URL="https://ops.example.com/grafana" make up-optionalPrometheus 自身不对宿主机发布端口，通常通过 Grafana 间接查询；要直接看 Prometheus，可临时在 compose 里为其加一个端口映射，或用 docker exec / podman exec 进容器排查。
链路追踪（Jaeger）
可选栈里的 dc3-jaeger（all-in-one 镜像）承担链路追踪：UI 在 16686（DC3_JAEGER_UI_PORT），OTLP 接收 gRPC 4317 / HTTP 4318。
各中心与网关默认开启追踪，经 OTLP 导出到 http://dc3-jaeger:4318/v1/traces，链路头按 B3 + W3C 双格式传播——一次跨服务调用在 Jaeger 里能串成一条 trace。开关在应用侧（不在 .env.example 里，按需注入核心栈）：
| 变量 | 默认 | 说明 |
|---|---|---|
OTEL_TRACING_ENABLED | true | 追踪总开关 |
OTEL_TRACING_SAMPLING_PROBABILITY | 1.0 | 采样率，生产建议降到 0.1–0.3 |
OTEL_OTLP_EXPORTER_ENABLED | true | OTLP 导出开关 |
OTEL_EXPORTER_OTLP_ENDPOINT | http://dc3-jaeger:4318/v1/traces | 导出地址 |
OTEL_EXPORTER_OTLP_TIMEOUT | 10s | 导出超时 |
没起 Jaeger 时导出没有接收方，服务日志可能出现连接失败告警（不影响业务请求）；不需要追踪就把 OTEL_OTLP_EXPORTER_ENABLED 设为 false。驱动服务没有追踪埋点，trace 到驱动边界为止。
看什么、告警什么
仓库不内置告警规则——Prometheus 抓取配置和 Grafana 置备都在镜像里，不含 alert rule，要自己配。这套栈里值得接告警的信号：
- 就绪探针：各中心的
/<base>/actuator/health/readiness持续失败（k8s 形态已接探针；Compose 形态用 blackbox 或脚本探测）。 - 摄取健康：预置看板里的 Ingest Rate 突降、Silent Points 上升——前者说明链路断了，后者说明一部分设备停报。
- 队列堆积：RabbitMQ 管理界面（db 栈发布
15672）盯dc3.q.value.point的深度，持续上涨就是数据中心消费跟不上。 - 数据库：postgres-exporter 的连接数、死元组、磁盘增长——时序数据 30 天滚动加两个连续聚合，磁盘只增不减，要有容量预案。
- 智能中心：
agentic.transport.acquire.timeout增长（限流到顶了）、agentic.check.results失败占比升高（provider 不可达）。
约束与边界
- 非默认启动：核心链路不依赖这套栈。它宕了不影响设备接入、命令下发与数据落库——只是少了日志检索与指标看板。
- 内存门槛：Elasticsearch 是这套栈里最重的组件。在 8GB 内存的开发机上，建议按
DC3_ES_JAVA_OPTS默认值或更低运行，并优先用SERVICES过滤只起需要的组件。 - 数据保留：Prometheus 固定保留 7 天；更长留存需改
--storage.tsdb.retention.time或外接长期存储。Elasticsearch 与 Logstash 的数据落在各自的命名卷（elasticsearch、logstash、logs），make reset会一并删除，谨慎使用。 - APM 双重开关：
dc3-apm容器在可选栈、APM_AGENT_ENABLE开关在核心栈，两者都到位才有 APM 数据（见上文）。 - 端口绑定：默认只绑
127.0.0.1。要从其他机器访问 Kibana/Grafana/EMQX Dashboard，需把DC3_BIND_HOST设为0.0.0.0（或具体网卡 IP），并自行评估暴露面。