diff options
Diffstat (limited to 'addons/promex/README')
| -rw-r--r-- | addons/promex/README | 356 |
1 files changed, 356 insertions, 0 deletions
diff --git a/addons/promex/README b/addons/promex/README new file mode 100644 index 0000000..4e29e23 --- /dev/null +++ b/addons/promex/README @@ -0,0 +1,356 @@ +PROMEX: A Prometheus exporter for HAProxy +------------------------------------------- + +Prometheus is a monitoring and alerting system. More and more people use it to +monitor their environment (this is written February 2019). It collects metrics +from monitored targets by scraping metrics HTTP endpoints on these targets. For +HAProxy, The Prometheus team officially supports an exporter written in Go +(https://github.com/prometheus/haproxy_exporter). But it requires an extra +software to deploy and monitor. PROMEX, on its side, is a built-in Prometheus +exporter for HAProxy. It was developed as a service and is directly available in +HAProxy, like the stats applet. + +However, PROMEX is not built by default with HAProxy. It is provided as an extra +component for everyone want to use it. So you need to explicitly build HAProxy +with the PROMEX service, setting the Makefile variable "USE_PROMEX" to "1". For +instance: + + > make TARGET=linux-glibc USE_PROMEX=1 + +if HAProxy provides the PROMEX service, the following build option will be +reported by the command "haproxy -vv": + + Built with the Prometheus exporter as a service + +To be used, it must be enabled in the configuration with an "http-request" rule +and the corresponding HTTP proxy must enable the HTX support. For instance: + + frontend test + mode http + ... + http-request use-service prometheus-exporter if { path /metrics } + ... + + +This service has been developed as a third-party component because it could +become obsolete, depending on how much time Prometheus will remain heavily +used. This is said with no ulterior motive of course. Prometheus is a great +software and I hope all the well for it. But we involve in a environment moving +quickly and a solution may be obvious today could be deprecated the next +year. And because PROMEX is not integrated by default into the HAProxy codebase, +it will need some interest to be actively supported. All contribution of any +kind are welcome. + +You must also be careful if you use with huge configurations. Unlike the stats +applet, all metrics are not grouped by service (proxy, listener or server). With +PROMEX, all lines for a given metric are provided as one single group. So +instead of collecting all metrics for a proxy before moving to the next one, we +must loop on all proxies for each metric. Same for the servers. Thus, it will +spend much more resources to produce the Prometheus metrics than the CSV export +through the stats page. To give a comparison order, quick benchmarks shown that +a PROMEX dump is 5x slower and 20x more verbose than a CSV export. + + +metrics filtering +------------------- + +It is possible to dynamically select the metrics to export if you don't use all +of them passing parameters in the query-string. + +* Filtering on scopes + +The metrics may be filtered by scopes. Multiple parameters with "scope" as name +may be passed in the query-string to filter exported metrics, with one of those +values: global, frontend, backend, server or '*' (means all). A scope parameter +with no value means to filter out all scopes (nothing is returned). The scope +parameters are parsed in their appearance order in the query-string. So an empty +scope will reset all scopes already parsed. But it can be overridden by +following scope parameters in the query-string. By default everything is +exported. Here are examples: + + /metrics?scope=server # ==> server metrics will be exported + /metrics?scope=frontend&scope=backend # ==> Frontend and backend metrics will be exported + /metrics?scope=listener # ==> listener metrics will be exported + /metrics?scope=*&scope= # ==> no metrics will be exported + /metrics?scope=&scope=global # ==> global metrics will be exported + /metrics?scope=sticktable # ==> stick tables metrics will be exported + +* How do I prevent my prometheus instance to explode? + +** Filtering on servers state + +It is possible to exclude from returned metrics all servers in maintenance mode +passing the parameter "no-maint" in the query-string. This parameter may help to +solve performance issues of configuration that use the server templates to +manage dynamic provisionning. Note there is no consistency check on the servers +state. So, if the state of a server changes while the exporter is running, only +a part of the metrics for this server will be dumped. + +prometheus example config: + +For server-template users: +- <job> + params: + no-maint: + - empty + +** Scrap server health checks only + +All health checks status are dump through `state` label values. If you want to +scrap server health check status but prevent all server metrics to be saved, +except the server_check_status, you may configure prometheus that way: + +- <job> + metric_relabel_configs: + - source_labels: ['__name__'] + regex: 'haproxy_(process_|frontend_|listener_|backend_|server_check_status).*' + action: keep + +Exported metrics +------------------ + +See prometheus export for the description of each field. + +* Globals metrics + ++------------------------------------------------+ +| Metric name | ++------------------------------------------------+ +| haproxy_process_nbthread | +| haproxy_process_nbproc | +| haproxy_process_relative_process_id | +| haproxy_process_uptime_seconds | +| haproxy_process_pool_failures_total | +| haproxy_process_max_fds | +| haproxy_process_max_sockets | +| haproxy_process_max_connections | +| haproxy_process_hard_max_connections | +| haproxy_process_current_connections | +| haproxy_process_connections_total | +| haproxy_process_requests_total | +| haproxy_process_max_ssl_connections | +| haproxy_process_current_ssl_connections | +| haproxy_process_ssl_connections_total | +| haproxy_process_max_pipes | +| haproxy_process_pipes_used_total | +| haproxy_process_pipes_free_total | +| haproxy_process_current_connection_rate | +| haproxy_process_limit_connection_rate | +| haproxy_process_max_connection_rate | +| haproxy_process_current_session_rate | +| haproxy_process_limit_session_rate | +| haproxy_process_max_session_rate | +| haproxy_process_current_ssl_rate | +| haproxy_process_limit_ssl_rate | +| haproxy_process_max_ssl_rate | +| haproxy_process_current_frontend_ssl_key_rate | +| haproxy_process_max_frontend_ssl_key_rate | +| haproxy_process_frontend_ssl_reuse | +| haproxy_process_current_backend_ssl_key_rate | +| haproxy_process_max_backend_ssl_key_rate | +| haproxy_process_ssl_cache_lookups_total | +| haproxy_process_ssl_cache_misses_total | +| haproxy_process_http_comp_bytes_in_total | +| haproxy_process_http_comp_bytes_out_total | +| haproxy_process_limit_http_comp | +| haproxy_process_current_zlib_memory | +| haproxy_process_max_zlib_memory | +| haproxy_process_current_tasks | +| haproxy_process_current_run_queue | +| haproxy_process_idle_time_percent | +| haproxy_process_stopping | +| haproxy_process_jobs | +| haproxy_process_unstoppable_jobs | +| haproxy_process_listeners | +| haproxy_process_active_peers | +| haproxy_process_connected_peers | +| haproxy_process_dropped_logs_total | +| haproxy_process_busy_polling_enabled | +| haproxy_process_failed_resolutions | +| haproxy_process_bytes_out_total | +| haproxy_process_spliced_bytes_out_total | +| haproxy_process_bytes_out_rate | +| haproxy_process_recv_logs_total | +| haproxy_process_build_info | +| haproxy_process_max_memory_bytes | +| haproxy_process_pool_allocated_bytes | +| haproxy_process_pool_used_bytes | +| haproxy_process_start_time_seconds | ++------------------------------------------------+ + +* Frontend metrics + ++-------------------------------------------------+ +| Metric name | ++-------------------------------------------------+ +| haproxy_frontend_current_sessions | +| haproxy_frontend_max_sessions | +| haproxy_frontend_limit_sessions | +| haproxy_frontend_sessions_total | +| haproxy_frontend_bytes_in_total | +| haproxy_frontend_bytes_out_total | +| haproxy_frontend_requests_denied_total | +| haproxy_frontend_responses_denied_total | +| haproxy_frontend_request_errors_total | +| haproxy_frontend_status | +| haproxy_frontend_limit_session_rate | +| haproxy_frontend_max_session_rate | +| haproxy_frontend_http_responses_total | +| haproxy_frontend_http_requests_rate_max | +| haproxy_frontend_http_requests_total | +| haproxy_frontend_http_comp_bytes_in_total | +| haproxy_frontend_http_comp_bytes_out_total | +| haproxy_frontend_http_comp_bytes_bypassed_total | +| haproxy_frontend_http_comp_responses_total | +| haproxy_frontend_connections_rate_max | +| haproxy_frontend_connections_total | +| haproxy_frontend_intercepted_requests_total | +| haproxy_frontend_denied_connections_total | +| haproxy_frontend_denied_sessions_total | +| haproxy_frontend_failed_header_rewriting_total | +| haproxy_frontend_http_cache_lookups_total | +| haproxy_frontend_http_cache_hits_total | +| haproxy_frontend_internal_errors_total | ++-------------------------------------------------+ + +* Listener metrics + ++-------------------------------------------------+ +| Metric name | ++-------------------------------------------------+ +| haproxy_listener_current_sessions | +| haproxy_listener_max_sessions | +| haproxy_listener_limit_sessions | +| haproxy_listener_sessions_total | +| haproxy_listener_bytes_in_total | +| haproxy_listener_bytes_out_total | +| haproxy_listener_requests_denied_total | +| haproxy_listener_responses_denied_total | +| haproxy_listener_request_errors_total | +| haproxy_listener_status | +| haproxy_listener_denied_connections_total | +| haproxy_listener_denied_sessions_total | +| haproxy_listener_failed_header_rewriting_total | +| haproxy_listener_internal_errors_total | ++-------------------------------------------------+ + +* Backend metrics + ++-----------------------------------------------------+ +| Metric name | ++-----------------------------------------------------+ +| haproxy_backend_current_queue | +| haproxy_backend_max_queue | +| haproxy_backend_current_sessions | +| haproxy_backend_max_sessions | +| haproxy_backend_limit_sessions | +| haproxy_backend_sessions_total | +| haproxy_backend_bytes_in_total | +| haproxy_backend_bytes_out_total | +| haproxy_backend_requests_denied_total | +| haproxy_backend_responses_denied_total | +| haproxy_backend_connection_errors_total | +| haproxy_backend_response_errors_total | +| haproxy_backend_retry_warnings_total | +| haproxy_backend_redispatch_warnings_total | +| haproxy_backend_status | +| haproxy_backend_weight | +| haproxy_backend_active_servers | +| haproxy_backend_backup_servers | +| haproxy_backend_check_up_down_total | +| haproxy_backend_check_last_change_seconds | +| haproxy_backend_downtime_seconds_total | +| haproxy_backend_loadbalanced_total | +| haproxy_backend_max_session_rate | +| haproxy_backend_http_responses_total | +| haproxy_backend_http_requests_total | +| haproxy_backend_client_aborts_total | +| haproxy_backend_server_aborts_total | +| haproxy_backend_http_comp_bytes_in_total | +| haproxy_backend_http_comp_bytes_out_total | +| haproxy_backend_http_comp_bytes_bypassed_total | +| haproxy_backend_http_comp_responses_total | +| haproxy_backend_last_session_seconds | +| haproxy_backend_queue_time_average_seconds | +| haproxy_backend_connect_time_average_seconds | +| haproxy_backend_response_time_average_seconds | +| haproxy_backend_total_time_average_seconds | +| haproxy_backend_failed_header_rewriting_total | +| haproxy_backend_connection_attempts_total | +| haproxy_backend_connection_reuses_total | +| haproxy_backend_http_cache_lookups_total | +| haproxy_backend_http_cache_hits_total | +| haproxy_backend_max_queue_time_seconds | +| haproxy_backend_max_connect_time_seconds | +| haproxy_backend_max_response_time_seconds | +| haproxy_backend_max_total_time_seconds | +| haproxy_backend_internal_errors_total | +| haproxy_backend_uweight | +| haproxy_backend_agg_server_status | +| haproxy_backend_agg_check_status | ++-----------------------------------------------------+ + +* Server metrics + ++----------------------------------------------------+ +| Metric name | ++----------------------------------------------------+ +| haproxy_server_current_queue | +| haproxy_server_max_queue | +| haproxy_server_current_sessions | +| haproxy_server_max_sessions | +| haproxy_server_limit_sessions | +| haproxy_server_sessions_total | +| haproxy_server_bytes_in_total | +| haproxy_server_bytes_out_total | +| haproxy_server_responses_denied_total | +| haproxy_server_connection_errors_total | +| haproxy_server_response_errors_total | +| haproxy_server_retry_warnings_total | +| haproxy_server_redispatch_warnings_total | +| haproxy_server_status | +| haproxy_server_weight | +| haproxy_server_check_failures_total | +| haproxy_server_check_up_down_total | +| haproxy_server_check_last_change_seconds | +| haproxy_server_downtime_seconds_total | +| haproxy_server_queue_limit | +| haproxy_server_current_throttle | +| haproxy_server_loadbalanced_total | +| haproxy_server_max_session_rate | +| haproxy_server_check_status | +| haproxy_server_check_code | +| haproxy_server_check_duration_seconds | +| haproxy_server_http_responses_total | +| haproxy_server_client_aborts_total | +| haproxy_server_server_aborts_total | +| haproxy_server_last_session_seconds | +| haproxy_server_queue_time_average_seconds | +| haproxy_server_connect_time_average_seconds | +| haproxy_server_response_time_average_seconds | +| haproxy_server_total_time_average_seconds | +| haproxy_server_failed_header_rewriting_total | +| haproxy_server_connection_attempts_total | +| haproxy_server_connection_reuses_total | +| haproxy_server_idle_connections_current | +| haproxy_server_idle_connections_limit | +| haproxy_server_max_queue_time_seconds | +| haproxy_server_max_connect_time_seconds | +| haproxy_server_max_response_time_seconds | +| haproxy_server_max_total_time_seconds | +| haproxy_server_internal_errors_total | +| haproxy_server_unsafe_idle_connections_current | +| haproxy_server_safe_idle_connections_current | +| haproxy_server_used_connections_current | +| haproxy_server_need_connections_current | +| haproxy_server_uweight | ++----------------------------------------------------+ + +* Stick table metrics + ++----------------------------------------------------+ +| Metric name | ++----------------------------------------------------+ +| haproxy_sticktable_size | +| haproxy_sticktable_used | ++----------------------------------------------------+ |