Flameshot

Flameshot 是一个基于 Sidecar 模式运行的轻量级自动性能剖析（Profiling）工具。它通过监控目标进程的资源使用情况（CPU/内存），在达到预设阈值时自动触发底层 Profiler（如 async-profiler），从而实现无侵入的现场快照采集。

核心功能与原理¶

运行模式¶

Flameshot 采用 Sidecar 容器 模式部署。它必须与业务主容器（Main Container）运行在同一个 Pod 中，并开启 PID 命名空间共享。

1. 监控 (Monitor)：Flameshot 持续轮询主容器内目标进程的资源水位。
2. 触发 (Trigger)：当满足阈值（如 CPU > 80%）或收到 HTTP API 请求时，触发采集任务。
3. 执行 (Execute)：根据配置的语言类型（目前支持 Java），调用对应的 Profiler 工具 attach 到目标进程。
4. 收集 (Collect)：生成的 Profile 文件（如 .jfr）存储于共享卷中，随后上传至数据观测中心。
5. 定时: 配置 FLAMESHOT_AUTO_PROFILING 后，会定时对所有匹配到的进程采集一次 30s 的 Profiling 数据。

适用场景¶

• 生产环境兜底：在服务因 CPU 飙高或内存泄漏即将崩溃前，自动保留现场证据。
• 性能压测分析：配合压测平台，自动采集高负载下的性能热点。

配置详解¶

Flameshot 的所有行为均通过环境变量进行控制。配置分为 全局设置 和 采集策略 两部分。

全局环境变量¶

这些变量控制 Sidecar 容器的基础行为。

采集策略配置 (FLAMESHOT_PROCESSES)¶

通过环境变量 FLAMESHOT_PROCESSES 定义监控目标。该变量的值必须是一个标准的 JSON 数组 字符串。

为了在 Kubernetes YAML 中保持配置的可读性，强烈建议使用 YAML 的多行文本语法（|）来书写 JSON 配置，如下所示：

    env:
      # ... 其他环境变量 ...
      - name: FLAMESHOT_PROCESSES
        value: |
          [
            {
              "service": "user-service",
              "language": "java",
              "command": "^java.*user-service\\.jar$",
              "duration": "60s",
              "events": "cpu,alloc",
              "cpu_usage_percent": 80,
              "mem_usage_percent": 80,
              "mem_usage_mb": 1024,
              "tags": [
                "env:prod",
                "version:v1.2"
              ]
            }
          ]

通用字段说明：

• service (String): 上报到观测中心的服务名称。
• language (String): 目标进程语言。目前支持 java。
• command (String): 匹配进程命令行的正则表达式。
• duration (String): 单次采集时长（例如 30s, 1m）。注意：受限于执行超时，建议不超过 5 分钟。
• tags (List): 自定义标签列表，建议包含 env, version 等元信息。
• cpu_usage_percent (Int): CPU 触发阈值 (0-N)。多核环境下数值可能超过 100。
• mem_usage_percent (Int): 内存使用率触发阈值 (0-100)。
• mem_usage_mb (Int): 内存使用量绝对值触发阈值 (MB)。
• 这三个配置： cpu_usage_percent mem_usage_percent mem_usage_mb 不配置或者配置 0 都会略过该项的阈值检查。

语言特定指南¶

根据被监控应用的技术栈，Flameshot 会调用不同的底层工具。

部署指南¶

Kubernetes Sidecar 部署¶

为了使 Flameshot 正常工作，Pod 配置必须满足以下三个条件：

1. 共享进程空间 (shareProcessNamespace: true)。
2. 共享存储卷 (EmptyDir)。
3. 系统权限 (Capabilities)。

YAML 示例：

apiVersion: v1
kind: Pod
metadata:
  name: java-app-profiled
spec:
  # 1. [核心] 开启 PID 共享，让 Sidecar 能看到 Java 进程
  shareProcessNamespace: true

  volumes:
  - name: shared-data
    emptyDir: {}

  containers:
  # 业务容器
  - name: my-app
    image: my-app:latest
    volumeMounts:
    - name: shared-data
      mountPath: /data # 需与 Sidecar 配置一致

  # Flameshot Sidecar
  - name: flameshot
    image: pubrepo.jiagouyun.com/datakit/flameshot:latest
    env:
      - name: FLAMESHOT_PROFILING_PATH
        value: "/data"
      # ... 其他环境变量 ...

    # 2. [核心] 赋予 ptrace 权限
    securityContext:
      capabilities:
        add: ["SYS_PTRACE"]

    # 3. [核心] 挂载同一目录
    volumeMounts:
    - name: shared-data
      mountPath: /data

Docker 本地测试¶

如果您需要在本地 Docker 环境中进行测试，可以使用以下命令启动 Flameshot 并监控目标容器。

前提条件：

• 主容器与 Flameshot 容器共享 /opt/java/openjdk (或实际 JDK 路径)。
• 使用 --pid="container:<target_id>" 或共享卷方式（视具体 Docker 版本而定）。

测试镜像： pubrepo.jiagouyun.com/datakit/flameshot:1.85.1-testing_testing-iss-2876

启动命令示例：

docker run -d \
  --name flameshot-debug \
  --volumes-from <YOUR_JAVA_APP_CONTAINER> \
  -e FLAMESHOT_DATAKIT_ADDR="http://datakit:9529/profiling/v1/input" \
  -e FLAMESHOT_PROCESSES='[{"service":"local-test","command":"java","language":"java","cpu_usage_percent":10}]' \
  pubrepo.jiagouyun.com/datakit/flameshot:1.85.1-testing_testing-iss-2876

API 接口参考¶

Flameshot 提供了 HTTP 接口，允许用户或自动化运维脚本主动触发采集任务。

手动触发采集¶

接口地址：GET /v1/profile

语义说明：该接口用于按需生成一份 Profile 数据，而非获取监控指标。

请求参数：

使用示例：

1. 按 PID 触发采集：

   # 对 PID 为 1234 的进程采集 30 秒的 CPU 和内存分配数据
   curl "http://localhost:8089/v1/profile?pid=1234&duration=30s&events=cpu,alloc"
   

2. 按进程名正则触发采集：

   # 对名称匹配 tmall.jar 的进程采集默认时长的数据
   curl "http://localhost:8089/v1/profile?command=^java\\b.*tmall\\.jar$"
   

JFR 数据格式¶

以下是几种核心事件类型的详细说明：

alloc 并非当前所有内存的总和，而是当前采样期间内所分配的内存大小。

常见问题与排查¶

1. 无法采集数据？

   • 检查 Pod 是否开启了 shareProcessNamespace: true。
   • 检查 Sidecar 是否拥有 SYS_PTRACE 权限。

2. 文件未上传？

   • 检查 FLAMESHOT_PROFILING_PATH 是否在两个容器间正确挂载。
   • 系统会自动管理文件生命周期，采集完成后会尝试删除临时文件。

3. 配置正则太麻烦

   • JAVA 应用的进程名都是 java, 所以配置 "command":"java" "language": "java" 即可匹配所有的 JAVA 应用。
   • 想要配置特定的应用而不是所有，正则是必须要配置的。

更新日志 (Changelog)¶

0.2.1 (2026-2-11)¶

新增功能¶

• 优化
  • 在容器环境中，使用资源配置的大小作为阈值计算的基础值。

0.2.0 (2026-2-4)¶

新增功能¶

• 增加配置
  • 支持通过环境变量 FLAMESHOT_AUTO_PROFILING 配置定时执行 Profiling
• 优化功能
  • 优化配置阈值

0.1.0 (2025-12-17)¶

Flameshot 的第一个正式版本，专注于为容器环境下的 Java 应用提供自动化的性能剖析能力。

新增功能¶

• 核心架构：
  • 支持 Kubernetes Sidecar 模式部署，利用共享 PID 命名空间实现无侵入监控。
  • 支持 Linux AMD64 和 ARM64 多架构运行。
• 语言支持：
  • Java: 深度集成 async-profiler，支持 CPU、Alloc、Lock 等多种事件采集。
  • 支持自动检测并适配目标容器的 JDK 环境。
• 触发机制：
  • 阈值触发: 支持基于 CPU 使用率 (cpu_usage_percent) 和内存使用率/量 (mem_usage_percent/mem_usage_mb) 的自动触发。
  • API 触发: 提供 HTTP 接口 GET /v1/monitor，支持通过 PID 或正则匹配进程名手动触发采集。
• 数据集成：
  • 支持将生成的 .jfr 或火焰图数据自动上报至 DataKit。
  • 支持通过环境变量 FLAMESHOT_PROCESSES 灵活配置多进程监控策略及标签 (tags)。