Skip to content

Commit 68e447a

Browse files
authored
docs(self-hosted): cleanup troubleshooting section (#12204)
Self-hosted troubleshooting section is getting all over the place. I think it'd be better if we separate it per component.
1 parent eaaab61 commit 68e447a

File tree

8 files changed

+291
-253
lines changed

8 files changed

+291
-253
lines changed

develop-docs/self-hosted/index.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,7 @@ To apply new Docker daemon configuration, restart your Docker service with `syst
123123

124124
<Alert title="Note" level="info">
125125
The value `172.17.0.0/16` is the default IP pools for Docker. If you are customizing your Docker default IP pools, please modify the value accordingly.
126-
Further information regarding Docker default IP pools can be found on the [Troubleshooting guide](/self-hosted/troubleshooting/#docker-network-conflicting-ip-address).
126+
Further information regarding Docker default IP pools can be found on the [Troubleshooting guide](/self-hosted/troubleshooting/docker/#docker-network-conflicting-ip-address).
127127
</Alert>
128128

129129
## Configuration

develop-docs/self-hosted/troubleshooting.mdx

Lines changed: 0 additions & 252 deletions
This file was deleted.
Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
title: Troubleshooting Docker
3+
sidebar_title: Docker
4+
sidebar_order: 3
5+
---
6+
7+
## Container Healthcheck
8+
9+
There may be some circumstances which you may want to increase or decrease healthcheck interval, timeout or retries for your custom needs. This can be achieved by editing `HEALTHCHECK_INTERVAL`, `HEALTHCHECK_TIMEOUT`, `HEALTHCHECK_RETRIES` variables' values in `.env`.
10+
11+
Occasionally, you might see an error like this
12+
```
13+
container for service "${servicename}" is unhealthy
14+
```
15+
16+
This can usually be resolved by running `docker compose down` and `docker compose up --wait` or rerunning the install script.
17+
18+
## Docker Network Conflicting IP Address
19+
20+
Self-hosted Sentry is using Docker's bridge networking, in which use a specific private IP range. By default, Docker uses `172.17.0.0/16` range (`172.17.0.0`-`172.17.255.255`). This may cause conflict with your private network. You can change Docker's default IP range by configuring the `/etc/docker/daemon.json` file. If the file does not exists, you can create it yourself.
21+
22+
Assuming your safe IP range is `10.147.0.0/16` and `10.146.0.0/16`, your configuration would be:
23+
24+
```json
25+
{
26+
"default-address-pools": [
27+
{
28+
"base": "10.147.0.0/16",
29+
"size": 24
30+
},
31+
{
32+
"base": "10.146.0.0/16",
33+
"size": 24
34+
}
35+
]
36+
}
37+
```
38+
39+
To apply new Docker daemon configuration, restart your Docker service with `systemctl restart docker`.
40+
41+
Make sure you are using [valid private IP ranges](https://en.wikipedia.org/wiki/Reserved_IP_addresses), that is between these ranges:
42+
- `10.0.0.0/8` (address range of `10.0.0.0``10.255.255.255`)
43+
- `100.64.0.0/10` (address range of `100.64.0.0``100.127.255.255`)
44+
- `172.16.0.0/12` (address range of `172.16.0.0``172.31.255.255`)
45+
- `192.0.0.0/24` (address range of `192.0.0.0``192.0.0.255`)
46+
- `192.168.0.0/16` (address range of `192.168.0.0``192.168.255.255`)
47+
- `198.18.0.0/15` (address range of `198.18.0.0``198.19.255.255`)
48+
49+
For further reading, you can see Matthew Stratiotto's article on [The definitive guide to docker's default-address-pools option](https://straz.to/2021-09-08-docker-address-pools/).
50+
51+
## Logs Disk Usage
52+
53+
If you are suspecting persisted logs from Docker container logs consumes a lot of your disk space, you can configure the amount of persisted logs on Docker by configuring the `/etc/docker/daemon.json` file. If the file does not exists, you can create it yourself.
54+
55+
```json
56+
{
57+
"log-driver": "local",
58+
"log-opts": {"max-size": "10m", "max-file": "3"}
59+
}
60+
```
61+
62+
To apply new Docker daemon configuration, restart your Docker service with `systemctl restart docker`.
63+
64+
If you want to delete immediate Docker logs, you can execute this as `root` user:
65+
66+
```shell
67+
truncate -s 0 /var/lib/docker/containers/**/*-json.log
68+
```
69+
70+
## Image and Builder Cleanup
71+
72+
Executing `./install.sh` will build a new Sentry Docker container, executing it often might cause Docker to consume your disk space. You can safely prune old or unneeded Docker containers, image, or builder to re-acquire used disk space. Executing these will not affect current running containers and volumes.
73+
74+
```shell
75+
docker container prune
76+
docker builder prune
77+
docker image prune --all
78+
# WARNING: Executing "volume prune" might delete `sentry-vroom` volume as it's not an external volume.
79+
docker volume prune
80+
docker network prune
81+
```
82+
83+
Append `-f` flag for no confirmation on deletions.
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Self-Hosted Troubleshooting
3+
sidebar_title: Troubleshooting
4+
sidebar_order: 9000
5+
---
6+
7+
Please keep in mind that the [self-hosted repository](https://github.com/getsentry/self-hosted) is geared towards low traffic loads (less than ~1 million submitted Sentry events per month). Folks needing larger setups or having event spikes can expand from here based on their specific needs and environments. If this is not your cup of tea, you are always welcome to [try out hosted Sentry](https://sentry.io/signup/).
8+
9+
## General
10+
11+
You can see the logs of each service by running `docker compose logs <service_name>`. You can use the `-f` flag to "follow" the logs as they come in, and use the `-t` flag for timestamps. If you don't pass any service names, you will get the logs for all running services. See the [reference for the logs command](https://docs.docker.com/compose/reference/logs/) for more info.
12+
13+
## Component Specific
14+
15+
Visit the following pages for troubleshooting guides for each component:
16+
17+
<PageGrid />
18+
19+
## Other
20+
21+
If you are still stuck, you can always visit our [GitHub issues](https://github.com/getsentry/self-hosted/issues) to search for existing issues or create a new issue and ask for help. You can also visit [Sentry Community Discord server](https://discord.gg/sentry) on #self-hosted channel. Please keep in mind that we expect the community to help itself, but Sentry employees also try to monitor and answer questions when they have time.

0 commit comments

Comments
 (0)