Flameshot

Flameshot は、Sidecar パターンで動作する軽量な自動パフォーマンスプロファイリングツールです。対象プロセスのリソース使用状況（CPU/メモリ）を監視し、あらかじめ設定した閾値に達すると、async-profiler などの低レベル Profiler を自動的に起動して、非侵襲で現場スナップショットを収集します。

コア機能と仕組み¶

動作モード¶

Flameshot は Sidecar コンテナ モードでデプロイします。業務用のメインコンテナ（Main Container）と同じ Pod 内で実行し、PID 名前空間の共有 を有効にする必要があります。

1. 監視 (Monitor)：Flameshot はメインコンテナ内の対象プロセスのリソース水位を継続的にポーリングします。
2. トリガー (Trigger)：閾値（例: CPU > 80%）に達するか、HTTP API リクエストを受けると、収集タスクを起動します。
3. 実行 (Execute)：設定された言語タイプ（現時点では Java と Go をサポート）に応じて、対応する Profiler ツールを呼び出して対象プロセスを収集します。
4. 収集 (Collect)：生成された Profile ファイル（例: .jfr または .pprof）をオブザーバビリティセンターへアップロードします。
5. 定時: FLAMESHOT_AUTO_PROFILING を設定すると、条件に合致した全プロセスを定期的に 1 回ずつ Profiling します。収集時間の既定値は 30s で、FLAMESHOT_AUTO_PROFILING_DURATION で調整できます。
6. OOM 要約: コンテナの oom_kill 増分を検知すると、Flameshot は対象 Java プロセスの起動引数から -XX:+HeapDumpOnOutOfMemoryError と -XX:HeapDumpPath=... を自動解析します。dump ファイルが共有ボリューム内にあり、生成に成功した場合、Flameshot は対応する .hprof を見つけて要約ログを 1 件アップロードします。

適用シーン¶

• 本番環境の保険：サービスが CPU 急上昇やメモリリークで落ちる直前に、現場証跡を自動で保持します。
• 性能負荷試験の分析：負荷試験基盤と組み合わせ、高負荷時の性能ホットスポットを自動収集します。

設定の詳細¶

Flameshot のすべての挙動は環境変数で制御します。設定は グローバル設定 と 収集ポリシー の 2 つに分かれます。

グローバル環境変数¶

これらの変数は Sidecar コンテナの基本動作を制御します。

DataKit を DaemonSet 方式でデプロイし、hostNetwork/hostPort で 9529 を公開している場合、Flameshot は通常の Service ドメイン名経由でランダム転送するのではなく、現在の業務 Pod が配置されているノード の DataKit に直接接続することを推奨します。

- name: NODE_IP
  valueFrom:
    fieldRef:
      fieldPath: status.hostIP
- name: FLAMESHOT_DATAKIT_ADDR
  value: "http://$(NODE_IP):9529/profiling/v1/input"

これにより、各業務 Pod は Profile を自身のノード上の DataKit にアップロードするようになり、調査やノードローカル収集の意味論を保ちやすくなります。

収集ポリシー設定 (FLAMESHOT_PROCESSES)¶

環境変数 FLAMESHOT_PROCESSES で監視対象を定義します。この変数の値は標準的な JSON 配列 文字列である必要があります。

Kubernetes YAML 内で設定の可読性を保つため、JSON 設定は YAML の複数行テキスト構文（|）で記述することを 強く推奨 します。以下の例を参照してください。

    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,
              "mem_usage_percent_emergency": 92,
              "mem_usage_mb_emergency": 1536,
              "heap_dump_on_memory_emergency": true,
              "emergency_duration": "10s",
              "tags": [
                "env:prod",
                "version:v1.2"
              ]
            }
          ]

共通フィールドの説明：

• service (String): オブザーバビリティセンターに報告されるサービス名。
• language (String): 対象プロセスの言語。現時点では java、go、golang をサポートします。
• command (String): プロセスのコマンドラインに一致する正規表現。
• duration (String): 1 回あたりの収集時間（例: 30s, 1m）。注意: 実行タイムアウトの制約があるため、5 分を超えないことを推奨します。
• emergency_duration (String): メモリ緊急閾値に達した後の高速収集時間。10s または 15s の設定を推奨します。
• pprof_url (String): Go pprof の HTTP アドレス。例: http://127.0.0.1:6060。language が go または golang の場合に設定が必要です。
• pprof_types (List): Go pprof の種類。cpu、goroutine、heap、mutex、block をサポートし、profile 収集器の既存 Go pull モードと整合します。
• pprof_timeout (String): Go pprof リクエストのタイムアウト時間。duration より長く設定することを推奨します。
• tags (List): カスタムタグのリスト。env、version などのメタ情報を含めることを推奨します。
• cpu_usage_percent (Int): CPU トリガー閾値 (0-N)。マルチコア環境では 100 を超える場合があります。
• mem_usage_percent (Int): メモリ使用率の平均閾値 (0-100)。直近 5 点の平均値でトリガーします。
• mem_usage_mb (Int): メモリ使用量の平均閾値 (MB)。直近 5 点の平均値でトリガーします。
• mem_usage_percent_emergency (Int): メモリ使用率の緊急瞬時閾値 (0-100)。単一点で一致すると即時トリガーします。
• mem_usage_mb_emergency (Int): メモリ使用量の緊急瞬時閾値 (MB)。単一点で一致すると即時トリガーします。
• heap_dump_on_memory_emergency (Bool): メモリ緊急閾値に達した際、そのプロセス規則で能動的 Heap Dump を許可するかどうか。未設定の場合、FLAMESHOT_HEAP_DUMP_ENABLED=true なら既定で許可されます。
• cpu_usage_percent、mem_usage_percent、mem_usage_mb は未設定または 0 の場合、その閾値チェックをスキップします。
• FLAMESHOT_POD_MEM_LIMIT を設定すると、mem_usage_percent と mem_usage_percent_emergency はホスト視点ではなく Pod limit 視点で優先的に計算されます。
• FLAMESHOT_HEAP_DUMP_ENABLED=true を設定すると、メモリ緊急閾値に達した際に jmap Heap Dump タスクが投入されます。この機能を使うには、Sidecar 内で FLAMESHOT_HEAP_DUMP_JMAP_PATH が指す jmap を実行可能である必要があります。hprof のオブジェクトストレージアップロードも同時に設定している場合、生成された .hprof は継続してアップロードされ、イベントには hprof_object_key、hprof_download_url、およびアップロード状態が含まれます。

言語別ガイド¶

監視対象アプリケーションの技術スタックに応じて、Flameshot は異なる低レベルツールを呼び出します。

import (
    "net/http"
    _ "net/http/pprof"
)

func main() {
    go http.ListenAndServe("127.0.0.1:6060", nil)
}

- name: POD_IP
  valueFrom:
    fieldRef:
      fieldPath: status.podIP
- name: FLAMESHOT_PROCESSES
  value: |
    [
      {
        "service": "go-app",
        "language": "go",
        "command": "^/app/go-app$",
        "pprof_url": "http://$(POD_IP):6060",
        "pprof_types": ["cpu", "goroutine", "heap", "mutex", "block"],
        "duration": "30s",
        "pprof_timeout": "45s"
      }
    ]

{
  "service": "go-app",
  "language": "go",
  "command": "^/app/go-app",
  "pprof_url": "http://127.0.0.1:6060",
  "pprof_types": ["cpu", "goroutine", "heap", "mutex", "block"],
  "duration": "30s",
  "pprof_timeout": "45s",
  "tags": ["env:prod", "version:v1"]
}

デプロイガイド¶

Kubernetes Sidecar デプロイ¶

Flameshot を正常に動作させるには、Pod 設定が次の 3 条件を満たす必要があります。

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

DataKit DaemonSet 設定の注意事項¶

DataKit を DaemonSet 方式でデプロイする場合、Flameshot は現在のノード IP 経由で Profile をアップロードすることを推奨します。

- name: NODE_IP
  valueFrom:
    fieldRef:
      fieldPath: status.hostIP
- name: FLAMESHOT_DATAKIT_ADDR
  value: "http://$(NODE_IP):9529/profiling/v1/input"

同時に、DataKit が次の条件を満たしていることを確認する必要があります。

1. profile 収集器が有効 であり、Profiling アップロードエンドポイントが登録されていること：

   [[inputs.profile]]
     endpoints = ["/profiling/v1/input"]
   

2. localhost 以外からの Profiling API アクセスを許可 していること。DataKit で HTTP API のホワイトリストを有効にしている場合は、/profiling/v1/input を ENV_HTTP_PUBLIC_APIS に追加してください：

   - name: ENV_HTTP_PUBLIC_APIS
     value: /otel/v1/trace,/otel/v1/metric,/otel/v1/logs,/profiling/v1/input
   

   この変数に他のインターフェースがすでに設定されている場合、既存値を直接上書きせず、末尾に /profiling/v1/input を追加してください。さもないと、次のようになります。

   datakit.publicAccessDisabled: api /profiling/v1/input disabled from external IP, only loopback(localhost) allowed
   

3. DataKit の待受アドレスがノード IP からアクセス可能 であること。DaemonSet の典型設定は hostNetwork: true、hostPort: 9529、ENV_HTTP_LISTEN=0.0.0.0:9529 です。

OOM HProf 要約の要件¶

Java プロセスで OOM が発生した後、Flameshot に .hprof 要約を自動補足させたい場合は、次の条件をすべて満たしてください。

1. 業務 JVM の起動引数で -XX:+HeapDumpOnOutOfMemoryError を有効にする。
2. 業務 JVM の起動引数で -XX:HeapDumpPath=/data/... を設定し、そのパスが共有ボリューム内にあること。
3. Flameshot に FLAMESHOT_OOM_HPROF_ENABLED=true を設定する。
4. 運用側で照合ウィンドウを明確に把握できるよう、FLAMESHOT_OOM_HPROF_MATCH_WINDOW も明示的に設定することを推奨します。

例:

java \
  -XX:+HeapDumpOnOutOfMemoryError \
  -XX:HeapDumpPath=/data/dumps/app.hprof \
  -jar app.jar

説明:

• Flameshot は対象 Java プロセスの起動引数から直接 HeapDumpPath を自動解析するため、.hprof のパスを別途設定する必要はありません。
• FLAMESHOT_OOM_HPROF_ENABLED は Flameshot 側の復旧ロジックを有効化するだけで、対象 JVM に HeapDump 関連パラメータを注入するものではありません。
• 対象プロセスが HeapDumpOnOutOfMemoryError を有効にしていない場合、または HeapDumpPath が共有ボリューム内にない場合、Flameshot は OOM イベントのみを記録し、対応する .hprof ファイルを見つけられません。
• dump 完了前にコンテナが直接終了した場合、.hprof は生成されないことがあります。

Docker ローカルテスト¶

ローカルの Docker 環境でテストする必要がある場合は、次のコマンドで Flameshot を起動し、対象コンテナを監視できます。

前提条件：

• --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

意味の説明：このインターフェースは、必要に応じて 1 つの 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 権限があるか確認してください。
   • Go アプリについては、pprof_url が Flameshot Sidecar 内からアクセス可能か確認してください。

   • Go アプリの場合、まず Flameshot コンテナ内で pprof endpoint にアクセスできることを確認します。

     curl -v "http://<pprof-host>:6060/debug/pprof/"
     curl -v "http://<pprof-host>:6060/debug/pprof/goroutine?debug=0"
     

   • ログに connect: connection refused が出る場合、対応する IP:Port が待ち受けていません。Pod に入って確認してください。

     netstat -lntp | grep ':6060'
     ss -ltnp | grep ':6060'
     

   LISTEN が表示されない場合、業務プロセスが pprof を有効化していないか、待受ポートが 6060 ではありません。60602 ... ESTABLISHED のような接続が見えても、6060 が待ち受けていることにはなりません。 - pprof が Pod IP で待ち受けている場合、pprof_url は http://$(POD_IP):6060 に設定してください。loopback または全アドレスで待ち受けている場合は http://127.0.0.1:6060 を使用できます。

2. ファイルがアップロードされない？

   • FLAMESHOT_PROFILING_PATH が 2 つのコンテナ間で正しくマウントされているか確認してください。
   • システムがファイルのライフサイクルを自動管理し、収集完了後に一時ファイルの削除を試みます。
   • Go の収集は .pprof をメモリアタッチメント形式で直接アップロードするため、通常はローカルへの書き出しに依存しません。Go の収集ログにすでに upload to DataKit err が出ている場合は、まず DataKit が返す HTTP ステータスコードとレスポンス本文を確認してください。

   • DataKit が 403 を返し、datakit.publicAccessDisabled を含む場合、/profiling/v1/input が localhost 以外に開放されていません。DataKit 設定に次を追加してください。

     - name: ENV_HTTP_PUBLIC_APIS
       value: /otel/v1/trace,/otel/v1/metric,/otel/v1/logs,/profiling/v1/input
     

   • DataKit が input "profile" is not enabled for API "/profiling/v1/input" を返す場合、DataKit で profile 収集器が有効化されていません。次を有効化してください。

     [[inputs.profile]]
       endpoints = ["/profiling/v1/input"]
     

3. 正規表現設定が面倒

   • JAVA アプリのプロセス名はすべて java なので、"command":"java" と "language": "java" を設定するだけで、すべての JAVA アプリにマッチします。
   • 特定のアプリだけを設定したい場合は、正規表現の設定が必須です。

更新履歴 (Changelog)¶

0.2.2 (2026-5-12)¶

問題修正¶

• 修正
  • Profiling 上報メタデータの tags_profiler に host、env、version、service などのタグが重複書き込みされる可能性がある問題を修正しました。
• 調整
  • 高水位 jcmd スナップショット機能および関連設定項目を削除しました。
  • cgroup メモリ圧迫時の観測フィールドを追加し、閾値、cgroup 現在値、および上限値の調査をしやすくしました。

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) を柔軟に設定できます。