diff --git a/docs/content/en/docs/troubleshooting/_index.md b/docs/content/en/docs/troubleshooting/_index.md index c665ffce91d..21d14e4eb52 100644 --- a/docs/content/en/docs/troubleshooting/_index.md +++ b/docs/content/en/docs/troubleshooting/_index.md @@ -7,30 +7,81 @@ aliases: ["/docs/tutorials/debugging-tetragon"] ## Automatic log and state collection -Before you report a problem, make sure to retrieve the necessary information from your cluster. +Before you report a problem, make sure to retrieve the necessary information +from your cluster. -### Kubernetes cluster +Tetragon's bugtool captures potentially useful information about your +environment for debugging. The tool is meant to be used for debugging a single +Tetragon agent node but can be run automatically in a cluster. Note that in the +context of Kubernetes, the command needs to be run from inside the Tetragon +Pod's container. + +Key information collected by bugtool: +- Tetragon configuration +- Network configuration +- Kernel configuration +- eBPF maps +- Process traces (if tracing is enabled) -You collect information in a Kubernetes cluster using the Cilium CLI: +### Automatic Kubernetes cluster sysdump + +You can collect information in a Kubernetes cluster using the Cilium CLI: ```shell cilium-cli sysdump ``` More details can be found in the [Cilium docs](https://docs.cilium.io/en/stable/operations/troubleshooting/#automatic-log-state-collection). +The Cilium CLI `sysdump` command will automatically run `tetra bugtool` on each +nodes where Tetragon is running. -### Single Node bugtool +### Manual single node sysdump -If you are not running Kubernetes, it is also possible to run the bug collection tool manually with the scope of a single node using: +It's also possible to run the bug collection tool manually with the scope of a +single node using `tetra bugtool`. -```shell -tetra bugtool -``` +#### Kubernetes installation -Tetragon's bugtool captures potentially useful information about your -environment for debugging. The tool is meant to be used for debugging a single -Tetragon agent node. Note that in the context of Kubernetes, the command needs -to be run from inside the Tetragon Pod's container. +1. Identify the Tetragon Pod (`` is likely to be `kube-system` + with the default install): + + ```bash + kubectl get pods -n -l app.kubernetes.io/name=tetragon + ``` + +2. Execute tetra bugtool within the Pod: + + ```bash + kubectl exec -n -c tetragon -- tetra bugtool + ``` + +3. Retrieve the created archive from the Pod's filesystem: + + ```bash + kubectl cp -c tetragon /:tetragon-bugtool.tar.gz tetragon-bugtool-tar.gz + ``` + +#### Container installation + +1. Enter the Tetragon Container: + + ```bash + docker exec -it tetra bugtool + ``` + +2. Retrieve the archive using docker cp: + + ```bash + docker cp :/tetragon-bugtool.tar.gz tetragon-bugtool.tar.gz + ``` + +#### Systemd host installation + +1. Execute tetra bugtool with Elevated Permissions: + + ```bash + sudo tetra bugtool + ``` ## Enable debug log level