Webman日志对接ELK需强制输出含trace_id、service_name等字段的标准JSON，Filebeat启用json.keys_under_root，Logstash用@metadata动态索引并预置index template确保trace_id为keyword类型。
Webman 默认使用 monolog 写本地文件，不带 trace_id、服务名、上下文字段，直接对接 ELK 会丢失关键追踪信息。必须改造日志输出格式，并确保链路标识贯穿采集、传输、索引全过程。
Webman 日志格式需适配 Logstash 的 grok 解析规则
Logstash 的 filter 段常依赖 grok 匹配原始日志行，但 Webman 默认日志是 JSON 格式（如启用 JsonFormatter），而 Logstash 的 beats 输入默认已解析 JSON，此时再用 grok 会报错或重复解析。
正确做法是：关闭 grok 对 JSON 日志的干预，只对非 JSON 行日志（如系统日志、Docker stdout）启用 grok。
- 在
logstash/pipeline/logstash.conf的filter块中，用if [message] !~ /^\{.*\}$/判断是否为 JSON，非 JSON 才走grok -
Webman端需强制输出标准 JSON，包含trace_id、service_name、level、timestamp、message字段，例如：{"trace_id":"a1b2c3","service_name":"order-api","level":"info","timestamp":"2026-06-07T20:32:00+08:00","message":"order created"} - 若用
Filebeat收集，确保其filebeat.yml中启用了json.keys_under_root: true和json.overwrite_keys: true，否则嵌套 JSON 字段无法提升到根层级
Logstash filter 中的 [@metadata][target_index] 必须动态生成且唯一
Webman 多实例部署时，不同服务（如 user-api、pay-service）必须写入不同索引，否则 Kibana 里无法按服务隔离查询。硬编码索引名（如 index => "webman-logs"）会导致所有服务日志混在一起。
解决方式是利用日志中的字段动态构造索引名：
Webman 2.2.0
下载
Webman 2.2.0版本强化了 TCP/UDP 服务支持，优化路由组管理，并增强异步任务处理能力。结合协程与连接池技术，Webman 能轻松应对高并发场景，适用于网站、接口服务、即时通讯、物联网及游戏开发，兼具高性能、灵活扩展与稳定可靠，是多场景 PHP 服务开发的理想选择。
- 确保
Webman日志 JSON 中有service_name字段（不能是app_name或其他，要和 Logstash 配置一致） - 在
filter块中用mutate { add_field => {"[@metadata][target_index]" => "%{[service_name]}-logs-%{+YYYY.MM.dd}"} } - 注意：必须用
[@metadata]而非普通字段，因为output.elasticsearch.index只支持读取@metadata下的变量 - 如果
service_name为空，Logstash 会 fallback 到默认索引，建议加一层if ![service_name] { mutate { add_field => {"[@metadata][target_index]" => "unknown-logs-%{+YYYY.MM.dd}"} } }
Filebeat 启动后无日志流入 Logstash 的常见卡点
现象是 Filebeat 进程 running，但 Logstash 的 stdout 或 Elasticsearch 里看不到数据，大概率不是网络不通，而是配置未对齐。
-
Filebeat的output.logstash必须指向 Logstash 的beats输入端口（如5045），不是tcp端口（如5044）——这两个端口在logstash.conf中是分开定义的 -
Filebeat的fields里不要设log_type: "webman"，否则会触发 Logstash 中elseif [fields][log_type] == "system"分支，把 Webman 日志误判为系统日志 - 检查
Filebeat是否读到了日志文件：运行./filebeat test output和./filebeat test config；再看filebeat --once -e是否打印出解析后的 event - Logstash 启动后需等几秒才真正监听端口，
Filebeat若启动过早会重试失败，建议加startup_delay: 5s或用 systemd 依赖控制顺序
Kibana 中看不到 trace_id 聚合或无法跳转链路
即使日志进了 ES，Kibana 里也查不到 trace_id 字段，或字段类型是 text 而非 keyword，导致无法用于 terms 聚合、可视化或关联 SkyWalking。
根本原因是 Elasticsearch 自动 mapping 把首次出现的 trace_id 当作全文字段建了 text 类型，后续无法修正。
- 必须在日志首次写入前，提前创建 index template，明确指定
trace_id为keyword，message保留text+keyword多字段 - 模板名称建议匹配 Logstash 动态索引名，如
webman-logs-*，优先级设高（"priority": 100） - 验证方式：调用
GET /_index_template/webman-logs-template，再查一个真实文档的 mapping：GET /webman-logs-2026.06.07/_mapping - 如果已写入错误 mapping，只能 reindex 到新索引，旧索引 delete，无法 in-place 修改
