Skip to content

Commit 453cc76

Browse files
mtardymtardy
committed
docs: split troubleshooting page into subpages
It makes more sense now that we have multiple topics to create subpages. Signed-off-by: Mahe Tardy <[email protected]>
1 parent 1900bdf commit 453cc76

File tree

3 files changed

+148
-122
lines changed

3 files changed

+148
-122
lines changed

‎docs/content/en/docs/troubleshooting/_index.md‎

Lines changed: 0 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -5,125 +5,3 @@ description: Learn how to troubleshoot Tetragon
55
aliases: ["/docs/tutorials/debugging-tetragon"]
66
---
77

8-
## Automatic log and state collection
9-
10-
Before you report a problem, make sure to retrieve the necessary information
11-
from your cluster.
12-
13-
Tetragon's bugtool captures potentially useful information about your
14-
environment for debugging. The tool is meant to be used for debugging a single
15-
Tetragon agent node but can be run automatically in a cluster. Note that in the
16-
context of Kubernetes, the command needs to be run from inside the Tetragon
17-
Pod's container.
18-
19-
Key information collected by bugtool:
20-
- Tetragon configuration
21-
- Network configuration
22-
- Kernel configuration
23-
- eBPF maps
24-
- Process traces (if tracing is enabled)
25-
26-
### Automatic Kubernetes cluster sysdump
27-
28-
You can collect information in a Kubernetes cluster using the Cilium CLI:
29-
30-
```shell
31-
cilium-cli sysdump
32-
```
33-
34-
More details can be found in the [Cilium docs](https://docs.cilium.io/en/stable/operations/troubleshooting/#automatic-log-state-collection).
35-
The Cilium CLI `sysdump` command will automatically run `tetra bugtool` on each
36-
nodes where Tetragon is running.
37-
38-
### Manual single node sysdump
39-
40-
It's also possible to run the bug collection tool manually with the scope of a
41-
single node using `tetra bugtool`.
42-
43-
#### Kubernetes installation
44-
45-
1. Identify the Tetragon Pod (`<tetragon-namespace>` is likely to be `kube-system`
46-
with the default install):
47-
48-
```bash
49-
kubectl get pods -n <tetragon-namespace> -l app.kubernetes.io/name=tetragon
50-
```
51-
52-
2. Execute tetra bugtool within the Pod:
53-
54-
```bash
55-
kubectl exec -n <tetragon-namespace> <tetragon-pod-name> -c tetragon -- tetra bugtool
56-
```
57-
58-
3. Retrieve the created archive from the Pod's filesystem:
59-
60-
```bash
61-
kubectl cp -c tetragon <tetragon-namespace>/<tetragon-pod-name>:tetragon-bugtool.tar.gz tetragon-bugtool.tar.gz
62-
```
63-
64-
#### Container installation
65-
66-
1. Enter the Tetragon Container:
67-
68-
```bash
69-
docker exec -it <tetragon-container-id> tetra bugtool
70-
```
71-
72-
2. Retrieve the archive using docker cp:
73-
74-
```bash
75-
docker cp <tetragon-container-id>:/tetragon-bugtool.tar.gz tetragon-bugtool.tar.gz
76-
```
77-
78-
#### Systemd host installation
79-
80-
1. Execute tetra bugtool with Elevated Permissions:
81-
82-
```bash
83-
sudo tetra bugtool
84-
```
85-
86-
## Enable debug log level
87-
88-
When debugging, it might be useful to change the log level. The default log
89-
level is controlled by the log-level option at startup:
90-
91-
* Enable debug level with `--log-level=debug`
92-
* Enable trace level with `--log-level=trace`
93-
94-
### Change log level on Kubernetes
95-
96-
{{< warning >}}
97-
The Pods of the Tetragon DaemonSet will be restarted automatically after
98-
changing the debug Helm value.
99-
{{< /warning >}}
100-
101-
It is possible to change the log level of Tetragon's DaemonSet Pods by setting
102-
`tetragon.debug` to `true`.
103-
104-
### Change log level dynamically
105-
106-
It is possible to change the log level dynamically by using the `tetra loglevel`
107-
sub-command. `tetra` needs access to Tetragon's gRPC server endpoint which can
108-
be configured via `--server-address`.
109-
110-
{{< warning >}}
111-
Keep in mind that Tetragon's gRPC server is (by default) only exposed on
112-
`localhost`. Also, it's important to understand that this only changes the log
113-
level of the single Tetragon instance targeted with `--server-address` and not
114-
all Tetragon instances when it's, for example, running as DaemonSet in a
115-
Kubernetes environment.
116-
{{< /warning >}}
117-
118-
* Get the current log level:
119-
120-
```shell
121-
tetra loglevel get
122-
```
123-
124-
* Dynamically change the log level. Allowed values are
125-
`[trace|debug|info|warning|error|fatal|panic]`:
126-
127-
```shell
128-
tetra loglevel set debug
129-
```

‎docs/content/en/docs/troubleshooting/loglevel.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
title: "Log level"
3+
weight: 2
4+
description: "Learn how to configure log levels."
5+
---
6+
7+
When debugging, it might be useful to change the log level. The default log
8+
level is controlled by the log-level option at startup:
9+
10+
* Enable debug level with `--log-level=debug`
11+
* Enable trace level with `--log-level=trace`
12+
13+
## Change log level on Kubernetes
14+
15+
{{< warning >}}
16+
The Pods of the Tetragon DaemonSet will be restarted automatically after
17+
changing the debug Helm value.
18+
{{< /warning >}}
19+
20+
It is possible to change the log level of Tetragon's DaemonSet Pods by setting
21+
`tetragon.debug` to `true`.
22+
23+
## Change log level dynamically
24+
25+
It is possible to change the log level dynamically by using the `tetra loglevel`
26+
sub-command. `tetra` needs access to Tetragon's gRPC server endpoint which can
27+
be configured via `--server-address`.
28+
29+
{{< warning >}}
30+
Keep in mind that Tetragon's gRPC server is (by default) only exposed on
31+
`localhost`. Also, it's important to understand that this only changes the log
32+
level of the single Tetragon instance targeted with `--server-address` and not
33+
all Tetragon instances when it's, for example, running as DaemonSet in a
34+
Kubernetes environment.
35+
{{< /warning >}}
36+
37+
* Get the current log level:
38+
39+
```shell
40+
tetra loglevel get
41+
```
42+
43+
* Dynamically change the log level. Allowed values are
44+
`[trace|debug|info|warning|error|fatal|panic]`:
45+
46+
```shell
47+
tetra loglevel set debug
48+
```

‎docs/content/en/docs/troubleshooting/sysdump.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: "System dump"
3+
weight: 1
4+
description: "Learn how to collect system dumps."
5+
---
6+
7+
Before you report a problem, make sure to retrieve the necessary information
8+
from your cluster.
9+
10+
Tetragon's bugtool captures potentially useful information about your
11+
environment for debugging. The tool is meant to be used for debugging a single
12+
Tetragon agent node but can be run automatically in a cluster. Note that in the
13+
context of Kubernetes, the command needs to be run from inside the Tetragon
14+
Pod's container.
15+
16+
Key information collected by bugtool:
17+
- Tetragon configuration
18+
- Network configuration
19+
- Kernel configuration
20+
- eBPF maps
21+
- Process traces (if tracing is enabled)
22+
23+
## Automatic Kubernetes cluster sysdump
24+
25+
You can collect information in a Kubernetes cluster using the Cilium CLI:
26+
27+
```shell
28+
cilium-cli sysdump
29+
```
30+
31+
More details can be found in the [Cilium docs](https://docs.cilium.io/en/stable/operations/troubleshooting/#automatic-log-state-collection).
32+
The Cilium CLI `sysdump` command will automatically run `tetra bugtool` on each
33+
nodes where Tetragon is running.
34+
35+
## Manual single node sysdump
36+
37+
It's also possible to run the bug collection tool manually with the scope of a
38+
single node using `tetra bugtool`.
39+
40+
### Kubernetes installation
41+
42+
1. Identify the Tetragon Pod (`<tetragon-namespace>` is likely to be `kube-system`
43+
with the default install):
44+
45+
```bash
46+
kubectl get pods -n <tetragon-namespace> -l app.kubernetes.io/name=tetragon
47+
```
48+
49+
2. Execute tetra bugtool within the Pod:
50+
51+
```bash
52+
kubectl exec -n <tetragon-namespace> <tetragon-pod-name> -c tetragon -- tetra bugtool
53+
```
54+
55+
3. Retrieve the created archive from the Pod's filesystem:
56+
57+
```bash
58+
kubectl cp -c tetragon <tetragon-namespace>/<tetragon-pod-name>:tetragon-bugtool.tar.gz tetragon-bugtool.tar.gz
59+
```
60+
61+
### Container installation
62+
63+
1. Enter the Tetragon Container:
64+
65+
```bash
66+
docker exec -it <tetragon-container-id> tetra bugtool
67+
```
68+
69+
2. Retrieve the archive using docker cp:
70+
71+
```bash
72+
docker cp <tetragon-container-id>:/tetragon-bugtool.tar.gz tetragon-bugtool.tar.gz
73+
```
74+
75+
### Systemd host installation
76+
77+
1. Execute tetra bugtool with Elevated Permissions:
78+
79+
```bash
80+
sudo tetra bugtool
81+
```
82+
83+
## Enable debug log level
84+
85+
When debugging, it might be useful to change the log level. The default log
86+
level is controlled by the log-level option at startup:
87+
88+
* Enable debug level with `--log-level=debug`
89+
* Enable trace level with `--log-level=trace`
90+
91+
### Change log level on Kubernetes
92+
93+
{{< warning >}}
94+
The Pods of the Tetragon DaemonSet will be restarted automatically after
95+
changing the debug Helm value.
96+
{{< /warning >}}
97+
98+
It is possible to change the log level of Tetragon's DaemonSet Pods by setting
99+
`tetragon.debug` to `true`.
100+

0 commit comments

Comments
 (0)