FrankenPHP日志需通过Promtail采集stdout/stderr转发至Loki，禁用log.file、配置docker_logs抓取、用pipeline_stages解析时间戳，避免结构化日志干扰聚类。
FrankenPHP 的日志输出机制不支持直接发往 Loki
FrankenPHP 本身没有内置 Loki 客户端或 loki_push 类配置项，它的日志默认走标准输出（stdout）和标准错误（stderr），由宿主环境（如 Docker、systemd）接管。想接入 Loki，必须靠外部组件把日志从 stdout/stderr 采集并转发过去——不是 FrankenPHP 配置问题，而是日志管道设计问题。
用 Promtail 抓取容器 stdout 并推送到 Loki 是最稳的方案
Promtail 轻量、专为 Loki 设计，且能自动打标签（比如 job、container_id）、处理多行日志（对 PHP 错误堆栈很关键）。它不依赖 FrankenPHP 修改任何代码或配置，只要日志写到 stdout 就能捕获。
- 确保 FrankenPHP 启动时禁用日志文件输出：在
frankenphp.yaml中设log.level: "error"且**不要**配log.file，让所有日志只走stdout - Docker 运行时加
--log-driver=local（避免 journald 缓存延迟），并挂载/var/log/pods或用docker logs模式让 Promtail 读取 - Promtail 配置里用
docker类型的scrape_configs，匹配容器名（如job_name: "frankenphp"）和 label（如{container="my-frankenphp"}） - 注意时间戳解析：FrankenPHP 默认日志无 ISO 格式时间，Promtail 需配
pipeline_stages用regex提取或 fallback 到采集时间（timestampstage）
别用 fluent-bit 或 filebeat 直连 Loki，除非你真需要高级过滤
Fluent-bit 支持 Loki 输出插件，但 v2.2+ 才稳定；filebeat 的 Loki output 仍属 beta。它们比 Promtail 重，且容易因 TLS 配置、label 覆盖、重试策略出问题。如果你只是把 FrankenPHP 日志进 Loki，Promtail 的 docker_logs + static_config 组合已足够——少一层抽象，少一个故障点。
- 常见翻车点：
promtail容器没加--privileged或cap_add: [SYS_ADMIN]？不需要。它只读/var/lib/docker/containers，给hostPath挂载 +read-only权限即可 - 日志行丢失？检查
docker run是否用了--log-opt max-size=10m—— 这会让旧日志被轮转删掉，Promtail 就抓不到历史行 - Loki 查不到日志？先
curl -G 'http://loki:3100/loki/api/v1/labels'确认服务通，再看 Promtail 日志里有没有pushed X lines成功提示
PHP 应用层打结构化日志反而会干扰 Loki 聚类
有人想在 PHP 里用 monolog + loki-handler 直传，这会导致两条路日志并存（PHP 自己发一份、容器 stdout 又一份），时间戳、traceID 不一致，查问题时得切两个视图。FrankenPHP 的请求生命周期短，错误基本都打在 stderr，结构化价值有限。
立即学习“PHP免费学习笔记（深入）”；
- 如果真要 trace 关联，优先用
OpenTelemetry SDK for PHP推 span 到 OTLP endpoint（再由 collector 转 Loki + Tempo），而不是改日志格式 - 想加自定义字段（如
user_id）？用 Promtail 的labelsstage 静态注入，或通过 Docker--label传入，在 Promtail 配置里提取为 Loki label - 注意：Loki 的 label 不是字段，不能做全文搜；全文搜靠 log line 本身，所以 PHP 里的
error_log("user_id=123 | failed to fetch")比 JSON 字段更利于检索
