{"id":13493270,"url":"https://github.com/iovisor/kubectl-trace","last_synced_at":"2025-05-14T22:08:28.321Z","repository":{"id":37451289,"uuid":"158594821","full_name":"iovisor/kubectl-trace","owner":"iovisor","description":"Schedule bpftrace programs on your kubernetes cluster using the kubectl","archived":false,"fork":false,"pushed_at":"2024-07-18T05:35:22.000Z","size":9553,"stargazers_count":2095,"open_issues_count":51,"forks_count":168,"subscribers_count":34,"default_branch":"master","last_synced_at":"2025-04-10T11:02:49.918Z","etag":null,"topics":["bpf","bpftrace","ebpf","ebpf-programs","kubectl","kubectl-plugin","kubectl-plugins","kubectl-trace","kubernetes-cluster","trace","tracepoints"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iovisor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-21T19:09:14.000Z","updated_at":"2025-04-10T06:15:47.000Z","dependencies_parsed_at":"2023-02-13T21:45:27.365Z","dependency_job_id":"90ec57cd-1023-421c-a168-4765cc54eafb","html_url":"https://github.com/iovisor/kubectl-trace","commit_stats":{"total_commits":258,"total_committers":35,"mean_commits":7.371428571428571,"dds":0.5930232558139534,"last_synced_commit":"478404c229bc10ca58a6b60d14e23b663036bf89"},"previous_names":["fntlnz/kubectl-trace"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iovisor%2Fkubectl-trace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iovisor%2Fkubectl-trace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iovisor%2Fkubectl-trace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iovisor%2Fkubectl-trace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iovisor","download_url":"https://codeload.github.com/iovisor/kubectl-trace/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254235700,"owners_count":22036964,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bpf","bpftrace","ebpf","ebpf-programs","kubectl","kubectl-plugin","kubectl-plugins","kubectl-trace","kubernetes-cluster","trace","tracepoints"],"created_at":"2024-07-31T19:01:13.714Z","updated_at":"2025-05-14T22:08:23.309Z","avatar_url":"https://github.com/iovisor.png","language":"Go","funding_links":[],"categories":["Projects Related to eBPF","API/CLI adaptors","Go","Tools and Libraries","Diagnostics \u0026 Troubleshooting","kubectl Plugins","eBPF 相关项目"],"sub_categories":["Tools","[Jenkins](#jenkins)","Networking","Installing plugins via awesome-kubectl-plugins","工具"],"readme":"![Kubectl trace Logo](docs/logo/logo-sm.png)\n\n`kubectl trace` is a kubectl plugin that allows you to schedule the execution\nof [bpftrace](https://github.com/iovisor/bpftrace) programs in your Kubernetes cluster.\n\n![Screenshot showing the read.bt program for kubectl-trace](docs/img/intro.png)\n\n\u003c!-- toc --\u003e\n\n- [Installing](#installing)\n  * [Krew](#krew)\n  * [Pre-built binaries](#pre-built-binaries)\n  * [Source](#source)\n  * [Packages](#packages)\n    + [Arch - AUR](#arch---aur)\n- [Architecture](#architecture)\n- [Usage](#usage)\n  * [Run a program from string literal](#run-a-program-from-string-literal)\n  * [Run a program from file](#run-a-program-from-file)\n  * [Run a program against a Pod](#run-a-program-against-a-pod)\n  * [Running against a Pod vs against a Node](#running-against-a-pod-vs-against-a-node)\n  * [Using a custom service account](#using-a-custom-service-account)\n  * [Executing in a cluster using Pod Security Policies](#executing-in-a-cluster-using-pod-security-policies)\n  * [Using a patch to customize the trace job](#using-a-patch-to-customize-the-trace-job)\n  * [More bpftrace programs](#more-bpftrace-programs)\n- [Contributing](#contributing)\n\n\u003c!-- tocstop --\u003e\n\n## Installing\n\n### Krew\n\nYou can install `kubectl trace` using the [Krew](https://github.com/kubernetes-sigs/krew), the package manager for kubectl plugins.\n\nOnce you have [Krew installed](https://krew.sigs.k8s.io/docs/user-guide/setup/install/) just run:\n\n```bash\nkubectl krew install trace\n```\n\nYou're ready to go!\n\n### Pre-built binaries\n\nSee the [release](https://github.com/iovisor/kubectl-trace/releases) page for the full list of pre-built assets.\n\nThe commands here show `amd64` versions, `386` versions are available in the releases page.\n\n**Linux**\n\n```bash\ncurl -L -o kubectl-trace.tar.gz https://github.com/iovisor/kubectl-trace/releases/download/v0.1.0-rc.1/kubectl-trace_0.1.0-rc.1_linux_amd64.tar.gz\ntar -xvf kubectl-trace.tar.gz\nmv kubectl-trace /usr/local/bin/kubectl-trace\n```\n\n**OSX**\n\n```bash\ncurl -L -o kubectl-trace.tar.gz https://github.com/iovisor/kubectl-trace/releases/download/v0.1.0-rc.1/kubectl-trace_0.1.0-rc.1_darwin_amd64.tar.gz\ntar -xvf kubectl-trace.tar.gz\nmv kubectl-trace /usr/local/bin/kubectl-trace\n```\n\n\n**Windows**\n\nIn PowerShell v5+\n```powershell\n$url = \"https://github.com/iovisor/kubectl-trace/releases/download/v0.1.0-rc.1/kubectl-trace_0.1.0-rc.1_windows_amd64.zip\"\n$output = \"$PSScriptRoot\\kubectl-trace.zip\"\n\nInvoke-WebRequest -Uri $url -OutFile $output\nExpand-Archive \"$PSScriptRoot\\kubectl-trace.zip\" -DestinationPath \"$PSScriptRoot\\kubectl-trace\"\n```\n\n### Source\n\nUsing go modules, you can build kubectl-trace at any git tag:\n\n```\nGO111MODULE=on go get github.com/iovisor/kubectl-trace/cmd/kubectl-trace@latest\n```\n\nThis will download and compile `kubectl-trace` so that you can use it as a kubectl plugin with `kubectl trace`, note that you will need to be on a recent version of go which supports go modules.\n\nTo keep track of the ref you used to build, you can add an ldflag at build time to set this to match the ref provided to go modules:\n\n```\n\u003e GO111MODULE=on go get -ldflags='-X github.com/iovisor/kubectl-trace/pkg/version.gitCommit=v0.1.2' github.com/iovisor/kubectl-trace/cmd/kubectl-trace@v0.1.2\n\u003e $GOHOME/bin/kubectl-trace version\ngit commit: v0.1.2\nbuild date: 2021-08-10 12:38:37.921341766 -0400 EDT m=+0.034327432\n```\n\n**Note:** It is recommended you build tagged revisions only if you are looking for stability. Building branches such as `master` or the `latest` tag may result in a more unstable build which has received less QA than a tagged release.\n\n### Packages\n\nYou can't find the package for your distro of choice?\nYou are very welcome and encouraged to create it and then [open an issue](https://github.com/iovisor/kubectl-trace/issues/new) to inform us for review.\n\n#### Arch - AUR\n\nThe official [PKGBUILD](https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=kubectl-trace-git) is on AUR.\n\nIf you use `yay` to manage AUR packages you can do:\n\n```\nyay -S kubectl-trace-git\n```\n\n## Architecture\n\nSee [architecture.md](/docs/architecture.md)\n\n## Usage\n\nYou don't need to setup anything on your cluster before using it, please don't use it already\non a production system, just because this isn't yet 100% ready.\n\n### Run a program from string literal\n\nIn this  case we are running a program that probes a tracepoint\non the node `ip-180-12-0-152.ec2.internal`.\n\n```\nkubectl trace run ip-180-12-0-152.ec2.internal -e \"tracepoint:syscalls:sys_enter_* { @[probe] = count(); }\"\n```\n\n### Run a program from file\n\nHere we run a program named `read.bt` against the node `ip-180-12-0-152.ec2.internal`\n\n```\nkubectl trace run ip-180-12-0-152.ec2.internal -f read.bt\n```\n\n### Run a program against a Pod\n\n![Screenshot showing the read.bt program for kubectl-trace](docs/img/pod.png)\n\nThat pod has a Go program in it that is at `/caturday`, that program has a function called `main.counterValue` in it that returns an integer\nevery time it is called.\n\nThe purpose of this program is to load an `uretprobe` on the `/caturday` binary so that every time the `main.counterValue` function is called\nwe get the return value out.\n\nSince `kubectl trace` for pods is just an helper to resolve the context of a container's Pod, you will always be in the root namespaces\nbut in this case you will have a variable `$container_pid` containing the pid of the root process in that container on the root pid namespace.\n\nWhat you do then is that you get the `/caturday` binary via `/proc/$container_pid/exe`, like this:\n\n```\nkubectl trace run -e 'uretprobe:/proc/$container_pid/exe:\"main.counterValue\" { printf(\"%d\\n\", retval) }' pod/caturday-566d99889-8glv9 -a -n caturday\n```\n\n### Running against a Pod vs against a Node\n\nIn general, you run kprobes/kretprobes, tracepoints, software, hardware and profile events against nodes using the `node/node-name` syntax or just use the\nnode name, node is the default.\n\nWhen you want to actually probe an userspace program with an uprobe/uretprobe or use an user-level static tracepoint (usdt) your best\nbet is to run it against a pod using the `pod/pod-name` syntax.\n\nIt's always important to remember that running a program against a pod, as of now, is just a facilitator to find the process id for the binary you want to probe\non the root process namespace.\n\nYou could do the same thing when running in a Node by knowing the pid of your process yourself after entering in the node via another medium, e.g: ssh.\n\nSo, running against a pod **doesn't mean** that your bpftrace program will be contained in that pod but just that it will pass to your program some\nknowledge of the context of a container, in this case only the root process id is supported via the `$container_pid` variable.\n\n\n### Using a custom service account\n\nBy default `kubectl trace` will use the `default` service account in the target namespace (that is also `default`), to schedule the pods needed for your bpftrace program.\n\nIf you need to pass a service account you can use the `--serviceaccount` flag.\n\n```bash\nkubectl trace run --serviceaccount=kubectltrace ip-180-12-0-152.ec2.internal -f read.bt\n```\n\n### Executing in a cluster using Pod Security Policies\n\nIf your cluster has pod security policies you will need to make so that `kubectl trace` can\nuse a service account that can run privileged containers.\n\nThat service account, then will need to be in a group that uses the proper privileged `PodSecurityPolicy`.\n\nFirst, create the service account that you will use with `kubectl trace`,\nyou can use a different namespace other than `default`, just remember to pass that namespace to the `run` command when you will use `kubectl trace`:\n\n```yaml\napiVersion: v1\nkind: ServiceAccount\nmetadata:\n  name: kubectltrace\n  namespace: default\n```\n\nNow that we have a `kubectltrace` service account let's create a Pod Security Policy:\n\n```yaml\napiVersion: policy/v1beta1\nkind: PodSecurityPolicy\nmetadata:\n  name: kubectltrace\nspec:\n  fsGroup:\n    rule: RunAsAny\n  privileged: true\n  runAsUser:\n    rule: RunAsAny\n  seLinux:\n    rule: RunAsAny\n  supplementalGroups:\n    rule: RunAsAny\n  volumes:\n  - '*'\n  allowedCapabilities:\n  - '*'\n  hostPID: true\n  hostIPC: true\n  hostNetwork: true\n  hostPorts:\n  - min: 1\n    max: 65536\n```\n\nOk, this `PodSecurityPolicy` will allow users assigned to it to run privileged containers,\n`kubectl trace` needs that because of the extended privileges eBPF programs need to run with\nto trace your kernel and programs running in it.\n\nNow with a `ClusterRoleBinding` you bind the `ClusterRole` with the `ServiceAccount`, so that\nthey can work together with the `PodSecurityPolicy` we just created.\n\nYou can change the `namespace: default` here if you created the service account in a namespace other than `default`.\n\n```yaml\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRole\nmetadata:\n  name: kubectltrace-psp\nrules:\n- apiGroups:\n  - policy\n  resources:\n  - podsecuritypolicies\n  resourceNames:\n  - kubectltrace\n  verbs:\n  - use\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRoleBinding\nmetadata:\n    name: kubectltrace-psp\nsubjects:\n- kind: ServiceAccount\n  name: kubectltrace\n  namespace: default\nroleRef:\n   apiGroup: rbac.authorization.k8s.io\n   kind: ClusterRole\n   name: kubectltrace-psp\n```\n\nOK! Now that we are all set we can just run the program by specifying the service account\nwe just created and it will use our pod security policy!\n\n```bash\nkubectl trace run --serviceaccount=kubectltrace ip-180-12-0-152.ec2.internal -f read.bt\n```\n\nIf you used a different namespace other than default for your service account, you will want to specify the namespace too, like this:\n\n```bash\nkubectl trace run --namespace=mynamespace --serviceaccount=kubectltrace ip-180-12-0-152.ec2.internal -f read.bt\n```\n\n### Using a patch to customize the trace job\n\nThere may be times when you need to customize the job descriptor that kubectl-trace generates. You can provide a patch file that will modify any of the job's attributes before it executes on the cluster.\n\nThe `--patch` and `--patch-type` arguments to the `run` command specify your patch file's location and merge strategy:\n\n * `--patch` - sets the path to a YAML or JSON file containing your patch.\n * `--patch-type` - sets the strategy that will be used to modify the job descriptor.\n\n**Patch strategies**\n\nThe supported patch strategies are the same as those used by Kubernetes to support [in-place API object updates](https://v1-17.docs.kubernetes.io/docs/tasks/run-application/update-api-object-kubectl-patch/#use-a-json-merge-patch-to-update-a-deployment).\n\nThese 3 patch strategies are:\n\n - `json` - Sets the [JSON patch](http://jsonpatch.com/) strategy (see [RFC 6209](https://tools.ietf.org/html/rfc6902)).\n - `merge` - Sets the [JSON merge patch](https://tools.ietf.org/html/rfc7396) strategy.\n - `strategic` - [JSON strategic merge patch]() is like the \"JSON merge patch\" but with different array handling (see [Kubernetes strategic merge](https://v1-17.docs.kubernetes.io/docs/tasks/run-application/update-api-object-kubectl-patch/#use-a-json-merge-patch-to-update-a-deployment) for more).\n\n**Note:** You can create your patch files in either YAML or JSON format. The format is independent of the strategy used, e.g. the strategy `json` refers to the \"JSON patch\" strategy, not the format of the patch file.\n\n**Example: customizing resource limits**\n\nA cluster administrator may have set strict resource limits that conflict with the defaults used by `kubectl-trace`, preventing your job from executing. With a patch you can adjust a job's resource limits to match your cluster's config.\n\nBelow is an example of a YAML patch which uses the `json` strategy (\"JSON patch\"). This strategy consists of a list of operations (add, replace, remove), a path which references a location in the document, and an optional value (to add or replace).\n\nThe patch below replaces the first container's resources section, in order to increase both the request and limit values for cpu and memory:\n\n```yaml\n# mypatch.yaml\n- op: replace\n  path: /spec/template/spec/containers/0/resources\n  value:\n    limits:\n      cpu: 2\n      memory: 500Mi\n    requests:\n      cpu: 2\n      memory: 500Mi\n```\n\nWe can now run the job using our patch:\n\n```bash\nkubectl trace run ip-180-12-0-152.ec2.internal -f read.bt --patch mypatch.yaml --patch-type json\n```\n\n**Example: setting an environment variable**\n\nThe following JSON format patch adds a `BPFTRACE_STRLEN` environment variable to the first container. The variable increases `bpftrace`'s string length limit from 64 to 128:\n\n```json\n[\n  {\n    \"op\": \"add\",\n    \"path\": \"/spec/template/spec/containers/0/env\",\n    \"value\": [{ \"name\": \"BPFTRACE_STRLEN\", \"value\": \"128\" }]\n  }\n]\n```\n\n```bash\nkubectl trace run ip-180-12-0-152.ec2.internal -f read.bt --patch mypatch.json --patch-type json\n```\n\n### More bpftrace programs\n\nNeed more programs? Look [here](https://github.com/iovisor/bpftrace/tree/master/tools).\n\n## Contributing\n\nAlready pumped up to commit some code? Here are some resources to join the\ndiscussions in the [IOVisor](https://www.iovisor.org/) community and see\nwhat you want to work on.\n\n* _Mailing List:_ http://lists.iovisor.org/mailman/listinfo/iovisor-dev\n* _IRC:_ #iovisor at irc.oftc.net\n* _Slack_ #kubectl-trace in the [Kubernetes Slack](http://kubernetes.slack.com/)\n* _Kubectl Trace Issue Tracker:_ [Github Issues](https://github.com/iovisor/kubectl-trace/issues)\n\nSpecial thanks to [Ramon Gilabert](https://github.com/RamonGilabert) for the logo.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiovisor%2Fkubectl-trace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiovisor%2Fkubectl-trace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiovisor%2Fkubectl-trace/lists"}