Skip to main content
Version: NG-2.16

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 IPDestination IPDestination PortProtocolDirection
vuSmartMaps agentGitLab Server443 (HTTPS, recommended) or 80 (HTTP), or a custom port if GitLab's external_url uses oneTCPInbound

*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).

  1. Confirm GitLab is running: sudo gitlab-ctl status All services should show "run", not "down" or "fail".

  2. 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.

  3. 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

  4. 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​

  1. In vuSmartMaps, add GitLab as a new data source.
  2. Enter the GitLab Server URL, for example https://gitlab.example.com (use HTTPS in production; avoid a trailing slash).
  3. Enter the Prometheus Metrics Endpoint URL. Default: https:///-/metrics.
  4. Set the poll interval — how often metrics are collected. Recommended: 60 seconds for production, up to 300 seconds for lighter monitoring needs.
  5. If the metrics endpoint is protected, choose an authentication method (Basic or Private Token).
  6. For token-based authentication, paste a GitLab Personal Access Token.
  7. 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​

NameDescriptionData Type
@timestampTimestamp string when the metric was collectedString
timestampDetailed timestamp with millisecondsDateTime64(3)
hostHost that collected the metricLowCardinality(String)
targetTarget GitLab instance being monitoredLowCardinality(String)
gitlab_cache_misses_totalTotal number of Rails cache missesNullable(Float64)
gitlab_cache_operations_totalTotal number of Rails cache operationsNullable(Float64)
gitlab_cache_operation_duration_seconds_bucketRails cache operation duration histogram bucket countNullable(Float64)
gitlab_cache_operation_duration_seconds_countNumber of observations in the Rails cache operation duration histogramNullable(Float64)
gitlab_cache_operation_duration_seconds_sumSum of all observed Rails cache operation durations in secondsNullable(Float64)
gitlab_redis_client_requests_totalTotal number of Redis client requestsNullable(Float64)
gitlab_redis_client_requests_duration_seconds_bucketRedis client request latency histogram bucket countNullable(Float64)
gitlab_redis_client_requests_duration_seconds_countNumber of observations in the Redis client request latency histogramNullable(Float64)
gitlab_redis_client_requests_duration_seconds_sumSum of all observed Redis client request latencies in secondsNullable(Float64)
gitlab_redis_client_requests_pipelined_commands_bucketPipelined commands per Redis request histogram bucket countNullable(Float64)
gitlab_redis_client_requests_pipelined_commands_countNumber of observations in the Redis pipelined commands histogramNullable(Float64)
gitlab_redis_client_requests_pipelined_commands_sumSum of all pipelined commands sent to RedisNullable(Float64)
gitlab_transaction_cache_read_hit_count_totalTotal number of cache read hits in Rails transactionsNullable(Float64)
gitlab_transaction_cache_read_miss_count_totalTotal number of cache read misses in Rails transactionsNullable(Float64)
gitlab_transaction_new_redis_connections_totalTotal number of new Redis connections openedNullable(Float64)
db_load_balancing_hostsNumber of database hosts in the load balancer poolNullable(Float64)
gitlab_connection_pool_available_countNumber of available connections in the connection poolNullable(Float64)
gitlab_connection_pool_sizeConfigured size of the connection poolNullable(Float64)
gitlab_database_connection_pool_busyNumber of busy connections in the database connection poolNullable(Float64)
gitlab_database_connection_pool_connectionsCurrent number of connections in the database connection poolNullable(Float64)
gitlab_database_connection_pool_deadNumber of dead connections in the database connection poolNullable(Float64)
gitlab_database_connection_pool_idleNumber of idle connections in the database connection poolNullable(Float64)
gitlab_database_connection_pool_sizeConfigured maximum size of the database connection poolNullable(Float64)
gitlab_database_connection_pool_waitingNumber of threads waiting for a database connectionNullable(Float64)
gitlab_database_transaction_seconds_bucketDatabase transaction duration histogram bucket countNullable(Float64)
gitlab_database_transaction_seconds_countNumber of observations in the database transaction duration histogramNullable(Float64)
gitlab_database_transaction_seconds_sumSum of all observed database transaction durations in secondsNullable(Float64)
gitlab_sql_duration_seconds_bucketSQL execution time histogram bucket countNullable(Float64)
gitlab_sql_duration_seconds_countNumber of observations in the SQL execution time histogramNullable(Float64)
gitlab_sql_duration_seconds_sumSum of all observed SQL execution times in secondsNullable(Float64)
gitlab_sql_primary_duration_seconds_bucketSQL execution time on primary database histogram bucket countNullable(Float64)
gitlab_sql_primary_duration_seconds_countNumber of observations in the primary SQL execution time histogramNullable(Float64)
gitlab_sql_primary_duration_seconds_sumSum of all observed SQL execution times on primary database in secondsNullable(Float64)
gitlab_transaction_db_count_totalTotal number of SQL calls in Rails transactionsNullable(Float64)
gitlab_transaction_db_write_count_totalTotal number of SQL write calls in Rails transactionsNullable(Float64)
gitlab_transaction_db_primary_count_totalTotal number of SQL calls on primary databaseNullable(Float64)
gitlab_transaction_db_primary_write_count_totalTotal number of SQL write calls on primary databaseNullable(Float64)
gitlab_transaction_db_cached_count_totalTotal number of cached SQL callsNullable(Float64)
gitlab_transaction_db_primary_cached_count_totalTotal number of cached SQL calls on primary databaseNullable(Float64)
gitlab_transaction_duration_seconds_bucketRails transaction duration histogram bucket countNullable(Float64)
gitlab_transaction_duration_seconds_countNumber of observations in the Rails transaction duration histogramNullable(Float64)
gitlab_transaction_duration_seconds_sumSum of all observed Rails transaction durations in secondsNullable(Float64)
gitlab_transaction_rails_queue_duration_totalTotal time requests spent queued before Rails processingNullable(Float64)
gitlab_transaction_view_duration_totalTotal time spent rendering viewsNullable(Float64)
gitlab_ruby_threads_max_expected_threadsMaximum number of threads expected to runNullable(Float64)
gitlab_ruby_threads_running_threadsNumber of running Ruby threadsNullable(Float64)
ruby_file_descriptorsNumber of file descriptors used by the Ruby processNullable(Float64)
ruby_gc_duration_seconds_bucketRuby GC duration histogram bucket countNullable(Float64)
ruby_gc_duration_seconds_countNumber of observations in the Ruby GC duration histogramNullable(Float64)
ruby_gc_duration_seconds_sumSum of all observed Ruby GC durations in secondsNullable(Float64)
ruby_gc_stat_compact_countNumber of GC heap compactionsNullable(Float64)
ruby_gc_stat_countTotal number of GC runsNullable(Float64)
ruby_gc_stat_ext_heap_fragmentationHeap fragmentation ratioNullable(Float64)
ruby_gc_stat_heap_allocatable_pagesNumber of heap pages that can be allocated without GCNullable(Float64)
ruby_gc_stat_heap_allocated_pagesNumber of heap pages currently allocatedNullable(Float64)
ruby_gc_stat_heap_available_slotsNumber of available object slots in the heapNullable(Float64)
ruby_gc_stat_heap_eden_pagesNumber of eden heap pages (pages with live objects)Nullable(Float64)
ruby_gc_stat_heap_final_slotsNumber of object slots awaiting finalizationNullable(Float64)
ruby_gc_stat_heap_free_slotsNumber of free object slots in the heapNullable(Float64)
ruby_gc_stat_heap_live_slotsNumber of live object slots in the heapNullable(Float64)
ruby_gc_stat_heap_marked_slotsNumber of object slots marked in the last GCNullable(Float64)
ruby_gc_stat_heap_sorted_lengthLength of the sorted heap page listNullable(Float64)
ruby_gc_stat_heap_tomb_pagesNumber of tomb heap pages (pages with no live objects)Nullable(Float64)
ruby_gc_stat_major_gc_countNumber of major GC runsNullable(Float64)
ruby_gc_stat_malloc_increase_bytesBytes allocated via malloc since last GCNullable(Float64)
ruby_gc_stat_malloc_increase_bytes_limitmalloc increase threshold that triggers GCNullable(Float64)
ruby_gc_stat_minor_gc_countNumber of minor GC runsNullable(Float64)
ruby_gc_stat_old_objectsNumber of old-generation objectsNullable(Float64)
ruby_gc_stat_old_objects_limitOld-object threshold that triggers major GCNullable(Float64)
ruby_gc_stat_oldmalloc_increase_bytesBytes allocated via malloc for old objects since last major GCNullable(Float64)
ruby_gc_stat_oldmalloc_increase_bytes_limitOld malloc increase threshold that triggers major GCNullable(Float64)
ruby_gc_stat_read_barrier_faultsNumber of read barrier faults during compactionNullable(Float64)
ruby_gc_stat_remembered_wb_unprotected_objectsNumber of remembered write-barrier-unprotected objectsNullable(Float64)
ruby_gc_stat_remembered_wb_unprotected_objects_limitLimit of remembered write-barrier-unprotected objectsNullable(Float64)
ruby_gc_stat_timeTotal time spent in GC in millisecondsNullable(Float64)
ruby_gc_stat_total_allocated_objectsTotal number of objects allocatedNullable(Float64)
ruby_gc_stat_total_allocated_pagesTotal number of heap pages allocatedNullable(Float64)
ruby_gc_stat_total_freed_objectsTotal number of objects freedNullable(Float64)
ruby_gc_stat_total_freed_pagesTotal number of heap pages freedNullable(Float64)
ruby_gc_stat_total_moved_objectsTotal number of objects moved by compactionNullable(Float64)
ruby_process_cpu_seconds_totalTotal user and system CPU time spent in secondsNullable(Float64)
ruby_process_max_fdsMaximum number of open file descriptorsNullable(Float64)
ruby_process_proportional_memory_bytesProportional set size (PSS) memory in bytesNullable(Float64)
ruby_process_resident_anon_memory_bytesResident anonymous memory in bytesNullable(Float64)
ruby_process_resident_file_memory_bytesResident file-backed memory in bytesNullable(Float64)
ruby_process_resident_memory_bytesResident memory size (RSS) in bytesNullable(Float64)
ruby_process_start_time_secondsStart time of the process since Unix epoch in secondsNullable(Float64)
ruby_process_unique_memory_bytesUnique set size (USS) memory in bytesNullable(Float64)
ruby_sampler_duration_seconds_totalTotal time spent collecting Ruby sampler stats in secondsNullable(Float64)
gitlab_sli_global_search_totalTotal number of global search operations measured for the SLINullable(Float64)
gitlab_sli_global_search_error_totalTotal number of failed global search operationsNullable(Float64)
gitlab_sli_global_search_apdex_totalTotal number of global search operations measured for ApdexNullable(Float64)
gitlab_sli_global_search_apdex_success_totalTotal number of global search operations meeting the Apdex targetNullable(Float64)
gitlab_sli_glql_totalTotal number of GLQL query operations measured for the SLINullable(Float64)
gitlab_sli_glql_error_totalTotal number of failed GLQL query operationsNullable(Float64)
gitlab_sli_glql_apdex_totalTotal number of GLQL query operations measured for ApdexNullable(Float64)
gitlab_sli_glql_apdex_success_totalTotal number of GLQL query operations meeting the Apdex targetNullable(Float64)
gitlab_sli_graphql_query_totalTotal number of GraphQL query operations measured for the SLINullable(Float64)
gitlab_sli_graphql_query_error_totalTotal number of failed GraphQL query operationsNullable(Float64)
gitlab_sli_graphql_query_apdex_totalTotal number of GraphQL query operations measured for ApdexNullable(Float64)
gitlab_sli_graphql_query_apdex_success_totalTotal number of GraphQL query operations meeting the Apdex targetNullable(Float64)
gitlab_sli_path_traversal_check_request_apdex_totalTotal number of path traversal check requests measured for ApdexNullable(Float64)
gitlab_sli_path_traversal_check_request_apdex_success_totalTotal number of path traversal check requests meeting the Apdex targetNullable(Float64)
gitlab_sli_rails_request_totalTotal number of Rails request operations measured for the SLINullable(Float64)
gitlab_sli_rails_request_error_totalTotal number of failed Rails request operationsNullable(Float64)
gitlab_sli_rails_request_apdex_totalTotal number of Rails request operations measured for ApdexNullable(Float64)
gitlab_sli_rails_request_apdex_success_totalTotal number of Rails request operations meeting the Apdex targetNullable(Float64)
action_cable_active_connectionsNumber of active ActionCable WebSocket connectionsNullable(Float64)
action_cable_pool_current_sizeCurrent number of worker threads in the ActionCable poolNullable(Float64)
action_cable_pool_largest_sizeLargest number of worker threads observed in the ActionCable poolNullable(Float64)
action_cable_pool_max_sizeMaximum number of worker threads in the ActionCable poolNullable(Float64)
action_cable_pool_min_sizeMinimum number of worker threads in the ActionCable poolNullable(Float64)
action_cable_pool_pending_tasksNumber of tasks waiting in the ActionCable pool queueNullable(Float64)
action_cable_pool_tasks_totalTotal number of tasks executed in the ActionCable poolNullable(Float64)
gitlab_rails_boot_time_secondsTime taken for Rails to boot in secondsNullable(Float64)
gitlab_rails_queue_duration_seconds_bucketWorkhorse request queue duration histogram bucket countNullable(Float64)
gitlab_rails_queue_duration_seconds_countNumber of observations in the Rails queue duration histogramNullable(Float64)
gitlab_rails_queue_duration_seconds_sumSum of all observed Rails queue durations in secondsNullable(Float64)
http_requests_totalTotal number of HTTP requestsNullable(Float64)
http_request_duration_seconds_bucketHTTP request duration histogram bucket countNullable(Float64)
http_request_duration_seconds_countNumber of observations in the HTTP request duration histogramNullable(Float64)
http_request_duration_seconds_sumSum of all observed HTTP request durations in secondsNullable(Float64)
http_health_requests_totalTotal number of health check requestsNullable(Float64)
puma_active_connectionsNumber of Puma threads processing requestsNullable(Float64)
puma_idle_threadsNumber of spawned Puma threads not processing requestsNullable(Float64)
puma_max_threadsMaximum number of Puma worker threadsNullable(Float64)
puma_pool_capacityNumber of requests the Puma worker can acceptNullable(Float64)
puma_queued_connectionsNumber of connections queued in Puma awaiting a threadNullable(Float64)
puma_runningNumber of running Puma threadsNullable(Float64)
puma_running_workersNumber of booted Puma workersNullable(Float64)
puma_stale_workersNumber of old Puma workersNullable(Float64)
puma_workersTotal number of Puma workersNullable(Float64)
rack_requests_totalTotal number of Rack requestsNullable(Float64)
deploymentsNumber of GitLab deploymentsNullable(Float64)
gitlab_memwd_max_memory_limitMaximum memory limit set by the memory watchdogNullable(Float64)
gitlab_application_rate_limiter_throttle_utilization_ratio_bucketRate limiter throttle utilization ratio histogram bucket countNullable(Float64)
gitlab_application_rate_limiter_throttle_utilization_ratio_countNumber of observations in the rate limiter throttle utilization histogramNullable(Float64)
gitlab_application_rate_limiter_throttle_utilization_ratio_sumSum of all observed rate limiter throttle utilization ratiosNullable(Float64)
gitlab_snowplow_events_totalTotal number of Snowplow events emittedNullable(Float64)
gitlab_snowplow_successful_events_totalTotal number of Snowplow events emitted successfullyNullable(Float64)
sidekiq_enqueued_jobs_totalTotal number of Sidekiq jobs enqueuedNullable(Float64)
urlMetrics endpoint URL scraped by TelegrafString
instanceInstance (host:port) of the scraped endpointString
jobPrometheus job nameString
pidGitLab process identifier (e.g. puma_0, sidekiq_0)String
leUpper bound label of the histogram bucketString
controllerRails controller that handled the requestString
actionRails controller action that handled the requestString
feature_categoryGitLab feature category of the requestString
endpoint_idEndpoint identifier of the requestString
storageRedis storage instance name (e.g. cache, shared_state, queues)String
operationRails cache operation type (e.g. read, write, fetch)String
storeRails cache store nameString
cache_hitWhether the cache operation was a hitString
db_config_nameDatabase configuration name (e.g. main, ci)String
classConnection pool class nameString
db_hostDatabase host of the connection poolString
portDatabase port of the connection poolString
urgencyUrgency level of the SLI endpointString
methodHTTP method of the requestString
statusHTTP response status code of the requestString
workerSidekiq worker classString
queueSidekiq queue nameString
_raw_messageRaw message received from Kafka before parsingString
_errorParsing/ingestion error message, if anyString