kubectl flame 🔥

A kubectl plugin that allows you to profile production applications with low-overhead by generating FlameGraphs

Running kubectlf-flame does not require any modification to existing pods.

Table of Contents

• Requirements
• Usage
• Installing
• How it works
• Contribute
• Maintainers
• License

Requirements

• Supported languages: Go, Java (any JVM based language), Python, Ruby, and NodeJS
• Kubernetes cluster that use Docker as the container runtime (tested on GKE, EKS and AKS)

Usage

Installation

This plugin is forked from the upstream kubectl-flame project so it is not available on Krew. To install the plugin checkout this repo and run:

kubectl krew install --manifest=.krew.yaml

This will clash with any existing installations of kubectl-flame.

Profiling Kubernetes Pod

In order to profile a Java application in pod mypod for 1 minute and save the flamegraph as /tmp/flamegraph.svg run:

kubectl flame mypod -t 1m --lang java -f /tmp/flamegraph.svg

Profiling Alpine based container

Profiling Java application in alpine based containers require using --alpine flag:

kubectl flame mypod -t 1m -f /tmp/flamegraph.svg --lang java --alpine

NOTICE: this is only required for Java apps, the --alpine flag is unnecessary for Go profiling.

Profiling sidecar container

Pods that contains more than one container require specifying the target container as an argument:

kubectl flame mypod -t 1m --lang go -f /tmp/flamegraph.svg mycontainer

Profiling Golang multi-process container

Profiling Go application in pods that contains more than one process require specifying the target process name via --pgrep flag:

kubectl flame mypod -t 1m --lang go -f /tmp/flamegraph.svg --pgrep go-app

Java profiling assumes that the process name is java. Use --pgrep flag if your process name is different.

Profiling on clusters running containerd

To run this tool on Kubernetes clusters that use containerd as the runtime engine, you must specify the path to the containerd runtime files:

kubectl flame mypod -t 1m --docker-path /run/containerd

Installing

Krew

You can install kubectl flame using the Krew, the package manager for kubectl plugins.

Once you have Krew installed just run:

kubectl krew install flame

Pre-built binaries

See the release page for the full list of pre-built assets.

How it works

kubectl-flame launch a Kubernetes Job on the same node as the target pod. Under the hood kubectl-flame use async-profiler in order to generate flame graphs for Java applications. Interaction with the target JVM is done via a shared /tmp folder. Golang support is based on ebpf profiling. Python support is based on py-spy. Ruby support is based on rbspy. NodeJS support is based on perf. In order for Javascript Symbols to be resolved, node process needs to be run with --perf-basic-prof flag.

Contribute

Please refer to the contributing.md file for information about how to get involved. We welcome issues, questions, and pull requests.

License

This project is licensed under the terms of the Apache 2.0 open source license. Please refer to LICENSE for the full terms.