2020-06-04 03:08:05 +00:00
---
stage: Monitor
2022-01-27 18:14:37 +00:00
group: Respond
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-06-04 03:08:05 +00:00
---
2022-03-04 21:13:10 +00:00
# Self-monitoring project (DEPRECATED) **(FREE SELF)**
2020-01-28 15:08:36 +00:00
2022-02-10 00:15:43 +00:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32351) in GitLab 12.7 [with a flag](../../feature_flags.md) named `self_monitoring_project`. Disabled by default.
> - Generally available in GitLab 12.8. [Feature flag `self_monitoring_project`](https://gitlab.com/gitlab-org/gitlab/-/issues/198511) removed.
2022-03-31 00:08:33 +00:00
> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/348909) in GitLab 14.9. Planned for removal in GitLab 16.0.
2022-03-04 21:13:10 +00:00
WARNING:
This feature is in its end-of-life process. It is [deprecated ](https://gitlab.com/gitlab-org/gitlab/-/issues/348909 )
2022-04-19 00:08:51 +00:00
in GitLab 14.9, and is planned for removal in GitLab 16.0.
2020-01-28 15:08:36 +00:00
2021-07-26 18:09:51 +00:00
GitLab provides administrators insights into the health of their GitLab instance.
2020-09-30 21:10:09 +00:00
2021-07-26 18:09:51 +00:00
To provide a native experience (similar interacting with an application deployed using GitLab), a
project called **Monitoring** is created:
2020-01-28 15:08:36 +00:00
2022-03-18 18:07:26 +00:00
- With [internal visibility ](../../../user/public_access.md#internal-projects-and-groups ).
2021-07-26 18:09:51 +00:00
- Under a group called **GitLab Instance** .
2020-06-04 18:08:32 +00:00
2021-07-26 18:09:51 +00:00
The project is created specifically for visualizing and configuring the monitoring of your GitLab
instance.
2020-02-05 15:08:48 +00:00
2021-11-25 09:13:54 +00:00
When the project and group are created, all administrators are given the [Maintainer role ](../../../user/permissions.md ).
As an administrator, you can add new members to the group to give them the Maintainer role for the project.
2021-07-26 18:09:51 +00:00
This project can be used to:
- Self monitor your GitLab instance. The metrics dashboard of the project shows some basic resource
usage charts, such as CPU and memory usage of each server in
[Omnibus GitLab ](https://docs.gitlab.com/omnibus/ ) installations.
- Also configure your own [custom metrics ](../../../operations/metrics/index.md#adding-custom-metrics )
using metrics exposed by the [GitLab exporter ](../prometheus/gitlab_metrics.md#metrics-available ).
## Create the self monitoring project
2020-02-05 15:08:48 +00:00
2021-08-26 00:09:31 +00:00
1. On the top bar, select **Menu > Admin** .
2021-06-15 18:09:57 +00:00
1. On the left sidebar, select **Settings > Metrics and profiling** and expand **Self monitoring** .
2021-07-26 18:09:51 +00:00
1. Toggle **Self monitoring** on.
2021-06-10 18:10:05 +00:00
1. After your GitLab instance creates the project, GitLab displays a link to the
2021-07-26 18:09:51 +00:00
project in the text above the **Self monitoring** toggle. You can also find it
2021-06-10 18:10:05 +00:00
from the top bar by selecting **Menu > Project** , then selecting **Your projects** .
2020-02-05 15:08:48 +00:00
2021-07-26 18:09:51 +00:00
## Delete the self monitoring project
2020-02-05 15:08:48 +00:00
2020-12-04 21:09:29 +00:00
WARNING:
2020-11-19 00:09:41 +00:00
Deleting the self monitoring project removes any changes made to the project. If
you create the project again, it's created in its default state.
2020-01-28 15:08:36 +00:00
2021-08-26 00:09:31 +00:00
1. On the top bar, select **Menu > Admin** .
2021-06-15 18:09:57 +00:00
1. On the left sidebar, go to **Settings > Metrics and profiling** and expand **Self monitoring** .
2021-07-26 18:09:51 +00:00
1. Toggle **Self monitoring** off.
2022-05-26 18:08:09 +00:00
1. In the confirmation dialog that opens, select **Delete self monitoring project** .
2020-02-07 21:08:39 +00:00
It can take a few seconds for it to be deleted.
1. After the project is deleted, GitLab displays a message confirming your action.
2020-06-18 18:08:58 +00:00
## Dashboards available in Omnibus GitLab
Omnibus GitLab provides a dashboard that displays CPU and memory usage
of each GitLab server. To select the servers to be displayed in the
panels, provide a regular expression in the **Instance label regex** field.
The dashboard uses metrics available in
[Omnibus GitLab ](https://docs.gitlab.com/omnibus/ ) installations.
2020-07-30 21:09:35 +00:00
![GitLab self monitoring overview dashboard ](img/self_monitoring_overview_dashboard.png )
2020-06-18 18:08:58 +00:00
You can also
2020-07-20 18:09:27 +00:00
[create your own dashboards ](../../../operations/metrics/dashboards/index.md ).
2020-06-18 18:08:58 +00:00
2021-07-26 18:09:51 +00:00
## Connect to Prometheus
2020-01-28 15:08:36 +00:00
2020-11-18 15:09:08 +00:00
The project is automatically configured to connect to the
2021-07-26 18:09:51 +00:00
[internal Prometheus ](../prometheus/index.md ) instance if the Prometheus instance is present.
This should be the case if GitLab was installed using Omnibus GitLab and you haven't disabled it.
2020-01-28 15:08:36 +00:00
2021-07-26 18:09:51 +00:00
If that's not the case, or if you have an external Prometheus instance or a customized setup,
you [configure it manually ](../../../user/project/integrations/prometheus.md#manual-configuration-of-prometheus ).
2020-01-28 15:08:36 +00:00
2021-07-26 18:09:51 +00:00
## Take action on Prometheus alerts **(ULTIMATE)**
2020-01-28 15:08:36 +00:00
2022-05-23 15:08:42 +00:00
You can [add a Prometheus integration ](../../../operations/incident_management/integrations.md )
to GitLab to receive notifications of any alerts.
2020-01-28 15:08:36 +00:00
2022-05-23 15:08:42 +00:00
Once the integration is setup, you can
2020-09-07 15:09:04 +00:00
[take action on incoming alerts ](../../../operations/metrics/alerts.md#trigger-actions-from-alerts ).
2020-02-07 15:09:52 +00:00
2021-07-26 18:09:51 +00:00
## Add custom metrics to the self monitoring project
2020-02-07 15:09:52 +00:00
You can add custom metrics in the self monitoring project by:
2020-07-30 21:09:35 +00:00
1. [Duplicating ](../../../operations/metrics/dashboards/index.md#duplicate-a-gitlab-defined-dashboard ) the overview dashboard.
2020-07-20 18:09:27 +00:00
1. [Editing ](../../../operations/metrics/index.md ) the newly created dashboard file and configuring it with [dashboard YAML properties ](../../../operations/metrics/dashboards/yaml.md ).
2020-03-10 12:08:16 +00:00
## Troubleshooting
2021-07-26 18:09:51 +00:00
### Error message in logs: `Could not create instance administrators group. Errors: ["You don't have permission to create groups."]`
2020-03-10 12:08:16 +00:00
2021-07-26 18:09:51 +00:00
A [bug ](https://gitlab.com/gitlab-org/gitlab/-/issues/208676 ) causes project creation to fail with
the following error in the log file when the first administrator user is an
2020-09-07 15:09:04 +00:00
[external user ](../../../user/permissions.md#external-users ):
2020-03-10 12:08:16 +00:00
2020-05-20 03:08:04 +00:00
```plaintext
2021-03-17 15:09:03 +00:00
Could not create instance administrators group. Errors: ["You don't have permission to create groups."]
2020-03-10 12:08:16 +00:00
```
2021-02-16 00:09:01 +00:00
Run the following in a Rails console to check if the first administrator user is an external user:
2020-03-10 12:08:16 +00:00
```ruby
User.admins.active.first.external?
```
2021-02-16 00:09:01 +00:00
If this returns true, the first administrator user is an external user.
2020-03-10 12:08:16 +00:00
If you face this issue, you can temporarily
2021-02-16 00:09:01 +00:00
[make the administrator user a non-external user ](../../../user/permissions.md#external-users )
2020-03-10 12:08:16 +00:00
and then try to create the project.
2021-02-16 00:09:01 +00:00
Once the project is created, the administrator user can be changed back to an external user.