GitLab
Introduction
Collects GitLab health, performance, and operational metrics from the native GitLab Prometheus metrics endpoint. Supports monitoring of Puma/Ruby process memory, Sidekiq background jobs, HTTP request activity, database connection pools, and Redis/cache performance.
Getting Started
Compatibility
Works with GitLab Omnibus (Linux package) and other self-managed GitLab installations — on-premises servers, virtual machines, or cloud-hosted instances. Supports both HTTP and HTTPS; HTTPS is strongly recommended for production environments.
Requirement: the GitLab Prometheus metrics endpoint (/-/metrics) must be reachable from the machine running the Telegraf agent, and that agent's IP address must be added to GitLab's monitoring allowlist (see "Configuring the Target" for steps).
Data Collection Method
vuSmartMaps uses Telegraf, a lightweight data-collection agent, to gather health and performance data from GitLab. It collects data by scraping GitLab's Prometheus metrics endpoint.
Telegraf periodically reads GitLab's built-in metrics page (/-/metrics), which is in Prometheus format. This gives performance data such as request counts, response times, error rates, and job queue sizes — no login required, but GitLab must allow the agent's IP to access this page.
Prerequisites
Inputs for Configuring Data Source
- Data Source Name: The display name for this GitLab data source.
- GitLab Server URL: Full base URL of the GitLab server. Example: http://gitlab-host or https://gitlab.example.com. Do NOT include a trailing slash.
- GitLab Prometheus Metrics URL: Full URL of the GitLab Prometheus metrics endpoint. Example: http://gitlab-host/-/metrics. This is used by Telegraf Prometheus input.
- Poll Interval (seconds): How frequently GitLab metrics are scraped. Recommended: 60–300 seconds.
- Authentication Method: Select the authentication method for the GitLab Prometheus metrics endpoint. The endpoint usually needs no authentication when the agent's IP is allowlisted; use Basic or Private Token only if it is protected (for example, behind a reverse proxy).
- Username: GitLab username for Basic Authentication. Shown only when Basic Auth is selected.
- Password / Token: GitLab password or token for Basic Authentication. Prefer personal access token in production.
- Private Token: GitLab Personal Access Token sent in the PRIVATE-TOKEN header when scraping the metrics endpoint.
Firewall Requirement
To collect data from this O11ySource, ensure the following ports are opened:
| Source IP | Destination IP | Destination Port | Protocol | Direction |
|---|---|---|---|---|
| vuSmartMaps agent | GitLab Server | 443 (HTTPS, recommended) or 80 (HTTP), or a custom port if GitLab's external_url uses one | TCP | Inbound |
*Before providing the firewall requirements, please update the port based on the customer environment.
Configuring the Target
Follow these steps on the GitLab server before adding it as a data source. Replace with your server's domain or IP, and use https:// wherever your GitLab instance is configured for HTTPS (recommended for production).
-
Confirm GitLab is running: sudo gitlab-ctl status All services should show "run", not "down" or "fail".
-
Confirm the GitLab web UI is reachable: curl -I https:// A response starting with HTTP/1.1 200 OK (or a redirect) confirms GitLab is reachable.
-
Allow the vuSmartMaps agent to read the metrics endpoint. By default, GitLab only accepts /-/metrics requests from allowlisted IPs. On the GitLab server, edit /etc/gitlab/gitlab.rb and add the agent's IP: gitlab_rails['monitoring_whitelist'] = ['127.0.0.0/8', ''] Then apply the change: sudo gitlab-ctl reconfigure
-
Verify the metrics endpoint responds from the agent host: curl https:///-/metrics | head You should see plain-text metric lines (for example, starting with gitlab_ or process_).
Production checklist: use HTTPS end-to-end, allowlist only the vuSmartMaps agent's IP (avoid opening the metrics endpoint to all hosts), and, if authentication is enabled, use a read-only token instead of a password and rotate it periodically.
Configuration Steps
- In vuSmartMaps, add GitLab as a new data source.
- Enter the GitLab Server URL, for example https://gitlab.example.com (use HTTPS in production; avoid a trailing slash).
- Enter the Prometheus Metrics Endpoint URL. Default: https:///-/metrics.
- Set the poll interval — how often metrics are collected. Recommended: 60 seconds for production, up to 300 seconds for lighter monitoring needs.
- If the metrics endpoint is protected, choose an authentication method (Basic or Private Token).
- For token-based authentication, paste a GitLab Personal Access Token.
- Save. vuSmartMaps immediately starts scraping GitLab Prometheus metrics.
Production best practices: always use HTTPS, use a read-only token (never an admin password), allowlist only the vuSmartMaps agent's IP on the GitLab server, and review/rotate the access token on a regular schedule.
Metrics Collected
| Name | Description | Data Type |
|---|---|---|
| @timestamp | Timestamp string when the metric was collected | String |
| timestamp | Detailed timestamp with milliseconds | DateTime64(3) |
| host | Host that collected the metric | LowCardinality(String) |
| target | Target GitLab instance being monitored | LowCardinality(String) |
| gitlab_cache_misses_total | Total number of Rails cache misses | Nullable(Float64) |
| gitlab_cache_operations_total | Total number of Rails cache operations | Nullable(Float64) |
| gitlab_cache_operation_duration_seconds_bucket | Rails cache operation duration histogram bucket count | Nullable(Float64) |
| gitlab_cache_operation_duration_seconds_count | Number of observations in the Rails cache operation duration histogram | Nullable(Float64) |
| gitlab_cache_operation_duration_seconds_sum | Sum of all observed Rails cache operation durations in seconds | Nullable(Float64) |
| gitlab_redis_client_requests_total | Total number of Redis client requests | Nullable(Float64) |
| gitlab_redis_client_requests_duration_seconds_bucket | Redis client request latency histogram bucket count | Nullable(Float64) |
| gitlab_redis_client_requests_duration_seconds_count | Number of observations in the Redis client request latency histogram | Nullable(Float64) |
| gitlab_redis_client_requests_duration_seconds_sum | Sum of all observed Redis client request latencies in seconds | Nullable(Float64) |
| gitlab_redis_client_requests_pipelined_commands_bucket | Pipelined commands per Redis request histogram bucket count | Nullable(Float64) |
| gitlab_redis_client_requests_pipelined_commands_count | Number of observations in the Redis pipelined commands histogram | Nullable(Float64) |
| gitlab_redis_client_requests_pipelined_commands_sum | Sum of all pipelined commands sent to Redis | Nullable(Float64) |
| gitlab_transaction_cache_read_hit_count_total | Total number of cache read hits in Rails transactions | Nullable(Float64) |
| gitlab_transaction_cache_read_miss_count_total | Total number of cache read misses in Rails transactions | Nullable(Float64) |
| gitlab_transaction_new_redis_connections_total | Total number of new Redis connections opened | Nullable(Float64) |
| db_load_balancing_hosts | Number of database hosts in the load balancer pool | Nullable(Float64) |
| gitlab_connection_pool_available_count | Number of available connections in the connection pool | Nullable(Float64) |
| gitlab_connection_pool_size | Configured size of the connection pool | Nullable(Float64) |
| gitlab_database_connection_pool_busy | Number of busy connections in the database connection pool | Nullable(Float64) |
| gitlab_database_connection_pool_connections | Current number of connections in the database connection pool | Nullable(Float64) |
| gitlab_database_connection_pool_dead | Number of dead connections in the database connection pool | Nullable(Float64) |
| gitlab_database_connection_pool_idle | Number of idle connections in the database connection pool | Nullable(Float64) |
| gitlab_database_connection_pool_size | Configured maximum size of the database connection pool | Nullable(Float64) |
| gitlab_database_connection_pool_waiting | Number of threads waiting for a database connection | Nullable(Float64) |
| gitlab_database_transaction_seconds_bucket | Database transaction duration histogram bucket count | Nullable(Float64) |
| gitlab_database_transaction_seconds_count | Number of observations in the database transaction duration histogram | Nullable(Float64) |
| gitlab_database_transaction_seconds_sum | Sum of all observed database transaction durations in seconds | Nullable(Float64) |
| gitlab_sql_duration_seconds_bucket | SQL execution time histogram bucket count | Nullable(Float64) |
| gitlab_sql_duration_seconds_count | Number of observations in the SQL execution time histogram | Nullable(Float64) |
| gitlab_sql_duration_seconds_sum | Sum of all observed SQL execution times in seconds | Nullable(Float64) |
| gitlab_sql_primary_duration_seconds_bucket | SQL execution time on primary database histogram bucket count | Nullable(Float64) |
| gitlab_sql_primary_duration_seconds_count | Number of observations in the primary SQL execution time histogram | Nullable(Float64) |
| gitlab_sql_primary_duration_seconds_sum | Sum of all observed SQL execution times on primary database in seconds | Nullable(Float64) |
| gitlab_transaction_db_count_total | Total number of SQL calls in Rails transactions | Nullable(Float64) |
| gitlab_transaction_db_write_count_total | Total number of SQL write calls in Rails transactions | Nullable(Float64) |
| gitlab_transaction_db_primary_count_total | Total number of SQL calls on primary database | Nullable(Float64) |
| gitlab_transaction_db_primary_write_count_total | Total number of SQL write calls on primary database | Nullable(Float64) |
| gitlab_transaction_db_cached_count_total | Total number of cached SQL calls | Nullable(Float64) |
| gitlab_transaction_db_primary_cached_count_total | Total number of cached SQL calls on primary database | Nullable(Float64) |
| gitlab_transaction_duration_seconds_bucket | Rails transaction duration histogram bucket count | Nullable(Float64) |
| gitlab_transaction_duration_seconds_count | Number of observations in the Rails transaction duration histogram | Nullable(Float64) |
| gitlab_transaction_duration_seconds_sum | Sum of all observed Rails transaction durations in seconds | Nullable(Float64) |
| gitlab_transaction_rails_queue_duration_total | Total time requests spent queued before Rails processing | Nullable(Float64) |
| gitlab_transaction_view_duration_total | Total time spent rendering views | Nullable(Float64) |
| gitlab_ruby_threads_max_expected_threads | Maximum number of threads expected to run | Nullable(Float64) |
| gitlab_ruby_threads_running_threads | Number of running Ruby threads | Nullable(Float64) |
| ruby_file_descriptors | Number of file descriptors used by the Ruby process | Nullable(Float64) |
| ruby_gc_duration_seconds_bucket | Ruby GC duration histogram bucket count | Nullable(Float64) |
| ruby_gc_duration_seconds_count | Number of observations in the Ruby GC duration histogram | Nullable(Float64) |
| ruby_gc_duration_seconds_sum | Sum of all observed Ruby GC durations in seconds | Nullable(Float64) |
| ruby_gc_stat_compact_count | Number of GC heap compactions | Nullable(Float64) |
| ruby_gc_stat_count | Total number of GC runs | Nullable(Float64) |
| ruby_gc_stat_ext_heap_fragmentation | Heap fragmentation ratio | Nullable(Float64) |
| ruby_gc_stat_heap_allocatable_pages | Number of heap pages that can be allocated without GC | Nullable(Float64) |
| ruby_gc_stat_heap_allocated_pages | Number of heap pages currently allocated | Nullable(Float64) |
| ruby_gc_stat_heap_available_slots | Number of available object slots in the heap | Nullable(Float64) |
| ruby_gc_stat_heap_eden_pages | Number of eden heap pages (pages with live objects) | Nullable(Float64) |
| ruby_gc_stat_heap_final_slots | Number of object slots awaiting finalization | Nullable(Float64) |
| ruby_gc_stat_heap_free_slots | Number of free object slots in the heap | Nullable(Float64) |
| ruby_gc_stat_heap_live_slots | Number of live object slots in the heap | Nullable(Float64) |
| ruby_gc_stat_heap_marked_slots | Number of object slots marked in the last GC | Nullable(Float64) |
| ruby_gc_stat_heap_sorted_length | Length of the sorted heap page list | Nullable(Float64) |
| ruby_gc_stat_heap_tomb_pages | Number of tomb heap pages (pages with no live objects) | Nullable(Float64) |
| ruby_gc_stat_major_gc_count | Number of major GC runs | Nullable(Float64) |
| ruby_gc_stat_malloc_increase_bytes | Bytes allocated via malloc since last GC | Nullable(Float64) |
| ruby_gc_stat_malloc_increase_bytes_limit | malloc increase threshold that triggers GC | Nullable(Float64) |
| ruby_gc_stat_minor_gc_count | Number of minor GC runs | Nullable(Float64) |
| ruby_gc_stat_old_objects | Number of old-generation objects | Nullable(Float64) |
| ruby_gc_stat_old_objects_limit | Old-object threshold that triggers major GC | Nullable(Float64) |
| ruby_gc_stat_oldmalloc_increase_bytes | Bytes allocated via malloc for old objects since last major GC | Nullable(Float64) |
| ruby_gc_stat_oldmalloc_increase_bytes_limit | Old malloc increase threshold that triggers major GC | Nullable(Float64) |
| ruby_gc_stat_read_barrier_faults | Number of read barrier faults during compaction | Nullable(Float64) |
| ruby_gc_stat_remembered_wb_unprotected_objects | Number of remembered write-barrier-unprotected objects | Nullable(Float64) |
| ruby_gc_stat_remembered_wb_unprotected_objects_limit | Limit of remembered write-barrier-unprotected objects | Nullable(Float64) |
| ruby_gc_stat_time | Total time spent in GC in milliseconds | Nullable(Float64) |
| ruby_gc_stat_total_allocated_objects | Total number of objects allocated | Nullable(Float64) |
| ruby_gc_stat_total_allocated_pages | Total number of heap pages allocated | Nullable(Float64) |
| ruby_gc_stat_total_freed_objects | Total number of objects freed | Nullable(Float64) |
| ruby_gc_stat_total_freed_pages | Total number of heap pages freed | Nullable(Float64) |
| ruby_gc_stat_total_moved_objects | Total number of objects moved by compaction | Nullable(Float64) |
| ruby_process_cpu_seconds_total | Total user and system CPU time spent in seconds | Nullable(Float64) |
| ruby_process_max_fds | Maximum number of open file descriptors | Nullable(Float64) |
| ruby_process_proportional_memory_bytes | Proportional set size (PSS) memory in bytes | Nullable(Float64) |
| ruby_process_resident_anon_memory_bytes | Resident anonymous memory in bytes | Nullable(Float64) |
| ruby_process_resident_file_memory_bytes | Resident file-backed memory in bytes | Nullable(Float64) |
| ruby_process_resident_memory_bytes | Resident memory size (RSS) in bytes | Nullable(Float64) |
| ruby_process_start_time_seconds | Start time of the process since Unix epoch in seconds | Nullable(Float64) |
| ruby_process_unique_memory_bytes | Unique set size (USS) memory in bytes | Nullable(Float64) |
| ruby_sampler_duration_seconds_total | Total time spent collecting Ruby sampler stats in seconds | Nullable(Float64) |
| gitlab_sli_global_search_total | Total number of global search operations measured for the SLI | Nullable(Float64) |
| gitlab_sli_global_search_error_total | Total number of failed global search operations | Nullable(Float64) |
| gitlab_sli_global_search_apdex_total | Total number of global search operations measured for Apdex | Nullable(Float64) |
| gitlab_sli_global_search_apdex_success_total | Total number of global search operations meeting the Apdex target | Nullable(Float64) |
| gitlab_sli_glql_total | Total number of GLQL query operations measured for the SLI | Nullable(Float64) |
| gitlab_sli_glql_error_total | Total number of failed GLQL query operations | Nullable(Float64) |
| gitlab_sli_glql_apdex_total | Total number of GLQL query operations measured for Apdex | Nullable(Float64) |
| gitlab_sli_glql_apdex_success_total | Total number of GLQL query operations meeting the Apdex target | Nullable(Float64) |
| gitlab_sli_graphql_query_total | Total number of GraphQL query operations measured for the SLI | Nullable(Float64) |
| gitlab_sli_graphql_query_error_total | Total number of failed GraphQL query operations | Nullable(Float64) |
| gitlab_sli_graphql_query_apdex_total | Total number of GraphQL query operations measured for Apdex | Nullable(Float64) |
| gitlab_sli_graphql_query_apdex_success_total | Total number of GraphQL query operations meeting the Apdex target | Nullable(Float64) |
| gitlab_sli_path_traversal_check_request_apdex_total | Total number of path traversal check requests measured for Apdex | Nullable(Float64) |
| gitlab_sli_path_traversal_check_request_apdex_success_total | Total number of path traversal check requests meeting the Apdex target | Nullable(Float64) |
| gitlab_sli_rails_request_total | Total number of Rails request operations measured for the SLI | Nullable(Float64) |
| gitlab_sli_rails_request_error_total | Total number of failed Rails request operations | Nullable(Float64) |
| gitlab_sli_rails_request_apdex_total | Total number of Rails request operations measured for Apdex | Nullable(Float64) |
| gitlab_sli_rails_request_apdex_success_total | Total number of Rails request operations meeting the Apdex target | Nullable(Float64) |
| action_cable_active_connections | Number of active ActionCable WebSocket connections | Nullable(Float64) |
| action_cable_pool_current_size | Current number of worker threads in the ActionCable pool | Nullable(Float64) |
| action_cable_pool_largest_size | Largest number of worker threads observed in the ActionCable pool | Nullable(Float64) |
| action_cable_pool_max_size | Maximum number of worker threads in the ActionCable pool | Nullable(Float64) |
| action_cable_pool_min_size | Minimum number of worker threads in the ActionCable pool | Nullable(Float64) |
| action_cable_pool_pending_tasks | Number of tasks waiting in the ActionCable pool queue | Nullable(Float64) |
| action_cable_pool_tasks_total | Total number of tasks executed in the ActionCable pool | Nullable(Float64) |
| gitlab_rails_boot_time_seconds | Time taken for Rails to boot in seconds | Nullable(Float64) |
| gitlab_rails_queue_duration_seconds_bucket | Workhorse request queue duration histogram bucket count | Nullable(Float64) |
| gitlab_rails_queue_duration_seconds_count | Number of observations in the Rails queue duration histogram | Nullable(Float64) |
| gitlab_rails_queue_duration_seconds_sum | Sum of all observed Rails queue durations in seconds | Nullable(Float64) |
| http_requests_total | Total number of HTTP requests | Nullable(Float64) |
| http_request_duration_seconds_bucket | HTTP request duration histogram bucket count | Nullable(Float64) |
| http_request_duration_seconds_count | Number of observations in the HTTP request duration histogram | Nullable(Float64) |
| http_request_duration_seconds_sum | Sum of all observed HTTP request durations in seconds | Nullable(Float64) |
| http_health_requests_total | Total number of health check requests | Nullable(Float64) |
| puma_active_connections | Number of Puma threads processing requests | Nullable(Float64) |
| puma_idle_threads | Number of spawned Puma threads not processing requests | Nullable(Float64) |
| puma_max_threads | Maximum number of Puma worker threads | Nullable(Float64) |
| puma_pool_capacity | Number of requests the Puma worker can accept | Nullable(Float64) |
| puma_queued_connections | Number of connections queued in Puma awaiting a thread | Nullable(Float64) |
| puma_running | Number of running Puma threads | Nullable(Float64) |
| puma_running_workers | Number of booted Puma workers | Nullable(Float64) |
| puma_stale_workers | Number of old Puma workers | Nullable(Float64) |
| puma_workers | Total number of Puma workers | Nullable(Float64) |
| rack_requests_total | Total number of Rack requests | Nullable(Float64) |
| deployments | Number of GitLab deployments | Nullable(Float64) |
| gitlab_memwd_max_memory_limit | Maximum memory limit set by the memory watchdog | Nullable(Float64) |
| gitlab_application_rate_limiter_throttle_utilization_ratio_bucket | Rate limiter throttle utilization ratio histogram bucket count | Nullable(Float64) |
| gitlab_application_rate_limiter_throttle_utilization_ratio_count | Number of observations in the rate limiter throttle utilization histogram | Nullable(Float64) |
| gitlab_application_rate_limiter_throttle_utilization_ratio_sum | Sum of all observed rate limiter throttle utilization ratios | Nullable(Float64) |
| gitlab_snowplow_events_total | Total number of Snowplow events emitted | Nullable(Float64) |
| gitlab_snowplow_successful_events_total | Total number of Snowplow events emitted successfully | Nullable(Float64) |
| sidekiq_enqueued_jobs_total | Total number of Sidekiq jobs enqueued | Nullable(Float64) |
| url | Metrics endpoint URL scraped by Telegraf | String |
| instance | Instance (host:port) of the scraped endpoint | String |
| job | Prometheus job name | String |
| pid | GitLab process identifier (e.g. puma_0, sidekiq_0) | String |
| le | Upper bound label of the histogram bucket | String |
| controller | Rails controller that handled the request | String |
| action | Rails controller action that handled the request | String |
| feature_category | GitLab feature category of the request | String |
| endpoint_id | Endpoint identifier of the request | String |
| storage | Redis storage instance name (e.g. cache, shared_state, queues) | String |
| operation | Rails cache operation type (e.g. read, write, fetch) | String |
| store | Rails cache store name | String |
| cache_hit | Whether the cache operation was a hit | String |
| db_config_name | Database configuration name (e.g. main, ci) | String |
| class | Connection pool class name | String |
| db_host | Database host of the connection pool | String |
| port | Database port of the connection pool | String |
| urgency | Urgency level of the SLI endpoint | String |
| method | HTTP method of the request | String |
| status | HTTP response status code of the request | String |
| worker | Sidekiq worker class | String |
| queue | Sidekiq queue name | String |
| _raw_message | Raw message received from Kafka before parsing | String |
| _error | Parsing/ingestion error message, if any | String |
