Consul 与 Prometheus 集成实战:服务自动发现与监控配置指南(含 ThinkPHP8 示例)

Consul 介绍

Consul 是基于 GO 语言开发的开源工具,主要面向分布式、服务化的系统提供服务注册、服务发现和配置管理功能。它具备服务注册/发现、健康检查、Key/Value 存储、多数据中心支持及分布式一致性保证等能力。

此前通过 Prometheus 实现监控时,新增 Target 需修改服务器配置文件,即便使用 file_sd_configs 配置,也需登录服务器修改对应 Json 文件,操作繁琐。而 Prometheus 官方支持多种自动服务发现类型,其中就包括 Consul。

为什么需要 Consul 与 Prometheus 配合?

Prometheus 与 Consul 配合实现服务发现,核心是借助 Consul 的服务注册/发现能力,让 Prometheus 动态获取待监控的服务实例列表,避免手动配置目标(尤其适合微服务动态扩缩容场景)。

核心原理

  1. Consul 角色:作为服务注册中心,接收服务实例的注册(包含地址、端口、标签、健康状态等元数据),并提供 HTTP API 供查询服务列表。
  2. Prometheus 角色:通过配置 consul_sd_configs,定期调用 Consul 的 API 获取服务实例信息,动态生成监控目标,自动抓取指标。

实现步骤

  1. 安装并启动 Consul(默认端口 8500,提供服务注册/发现 API)。
  2. 安装 Prometheus(默认端口 9090,用于配置服务发现)。
  3. 准备待监控的服务(需暴露 metrics 端点,如 /metrics)。

Consul 安装部署

源码安装

我们仅需要 consul 可执行文件即可

1
./consul agent -dev

Prometheus 安装

Prometheus安装非常简单,使用docker仅需要不到10分钟即可

健康检查脚本

启动 Consul

安装 pm2 脚本进程守护:

1
apt install npm

安装 pm2:

1
npm install pm2 -g

测试进程守护:

1
pm2 start "./consul agent -dev" --name "consul"

在这个启动项中,我们定义了配置文件目录 config-dir、监听地址 bind 以及预期启动节点 bootstrap-expect

1
pm2 start "./consul agent -config-dir=/etc/consul.d/ -client=0.0.0.0 --bind=192.168.87.250 -server  -bootstrap-expect=1" --name "consul"

为了安全,生成 Bootstrap:

安全是一种习惯

1
./consul acl bootstrap

生成 HTTP 检查(配置文件):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
service {
name = "ThinkPHP8"
id = "php8.1"
address = "192.168.87.177"
port = 8080
token = "d45af3b5-a433-fc4b-4ff8-b50411ca4bf3"
tags = ["thinkphp8", "php8.1", "manage"]
check {
name = "ThinkPHP8check"
http = "http://192.168.87.177:8080"
interval = "15s"
timeout = "15s"
status = "200-299"
}
}

重启进程

1
./consul reload -token=d45af3b5-a433-fc4b-4ff8-b50411ca4bf3

将 Consul 注册到 Prometheus

将 Prometheus 的配置文件复制出来,修改后再放回:

1
docker cp prometheus:/etc/prometheus/prometheus.yml $PWD

关键配置项:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
scrape_configs:
# The job name is added as a label `job=<job_name>` to any timeseries scraped from this config.
- job_name: "prometheus"

# metrics_path defaults to '/metrics'
# scheme defaults to 'http'.

static_configs:
- targets: ["localhost:9090"]
# The label name is added as a label `label_name=<label_value>` to any timeseries scraped from this config.
labels:
app: "prometheus"
- job_name: 'consul-prometheus'
consul_sd_configs:
- server: '192.168.87.250:8500'
services: []
token: d45af3b5-a433-fc4b-4ff8-b50411ca4bf3
relabel_configs:
- source_labels: [__meta_consul_service_tag_metrics_path]
action: replace
target_label: __metrics_path__
regex: 'metrics-path=(.*)'
- source_labels: [__meta_consul_service]
action: keep
regex: 'frontend.*'

将修改好的配置放回容器并重启容器

1
2
docker cp $PWD/prometheus.yml prometheus:/etc/prometheus/prometheus.yml
docker restart prometheus

到这里,Prometheus 已能识别 Consul 中注册的服务。但需在待检查的服务中配置控制器,以应对 Prometheus 的检查。此过程中,Consul 仅作为服务发现工具,实际检查由 Prometheus 执行。

创建 ThinkPHP8 检查示例

我们尝试在中间件中统计关于请求的花销、请求次数以及花费时间等参数。

中间件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
<?php
namespace app\middleware;


use think\facade\Cache;
use think\facade\Request;


class MetricsMiddleware
{
public function handle($request, \Closure $next)
{
$startTime = microtime(true);
$response = $next($request);


Cache::inc('http_requests_total');


$method = $request->method();
$path = $request->pathinfo();
$key = "http_requests_by_path{method=\"$method\",path=\"$path\"}";
Cache::inc($key);


$responseTime = round(microtime(true) - $startTime, 4);
Cache::set("http_response_time{path=\"$path\"}", $responseTime);


$costTime = ($startTime - $_SERVER['REQUEST_TIME_FLOAT']) * 1000;
Cache::set("http_consumer_cost_time",$costTime);


return $response;
}
}

控制器

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
<?php
namespace app\controller;


use think\facade\Cache;
use think\Response;


class Metrics
{
public function index()
{
$metrics = $this->collectMetrics();
return Response::create($metrics, 'html')
->header(['Content-Type' => 'text/plain; charset=utf-8']);
}


private function collectMetrics()
{
$totalRequests = Cache::get('http_requests_total', 0);
$onlineUsers = rand(50, 200);
$startTime = Cache::remember('app_start_time', function () {
return time();
}, 86400);


$pathMethodMetrics = $this->getHttpRequestsByPath();
$responseTimeMetrics = $this->getHttpResponseTime();
$consumerCostTime = Cache::get('http_consumer_cost_time', 0);


$metrics = <<<METRICS
# HELP http_requests_total 应用总请求数
# TYPE http_requests_total counter
http_requests_total $totalRequests


# HELP online_users 当前在线用户数
# TYPE online_users gauge
online_users $onlineUsers


# HELP app_start_time_seconds 应用启动时间(Unix时间戳)
# TYPE app_start_time_seconds gauge
app_start_time_seconds $startTime


{$pathMethodMetrics}


{$responseTimeMetrics}


# HELP http_consumer_cost_time 请求从到达至响应完成的总耗时(毫秒)
# TYPE http_consumer_cost_time gauge
http_consumer_cost_time $consumerCostTime
METRICS;


return $metrics;
}


/**
* 处理按路径和方法统计的请求数指标
*/
private function getHttpRequestsByPath()
{
$keys = Cache::handler()->keys('http_requests_by_path*');
$metrics = [];


$metrics[] = "# HELP http_requests_by_path 按请求方法和路径统计的请求数";
$metrics[] = "# TYPE http_requests_by_path counter";


foreach ($keys as $key) {
if (preg_match('/http_requests_by_path\{method="([^"]+)",path="([^"]+)"\}/', $key, $matches)) {
$method = $matches[1];
$path = $matches[2];
$value = Cache::get($key, 0);
$metrics[] = "http_requests_by_path{method=\"{$method}\",path=\"{$path}\"} {$value}";
}
}


return implode("\n", $metrics);
}


/**
* 处理按路径的响应时间指标
*/
private function getHttpResponseTime()
{
$keys = Cache::handler()->keys('http_response_time*');
$metrics = [];


$metrics[] = "# HELP http_response_time 按路径统计的响应时间(秒,保留4位小数)";
$metrics[] = "# TYPE http_response_time gauge";


foreach ($keys as $key) {
if (preg_match('/http_response_time\{path="([^"]+)"\}/', $key, $matches)) {
$path = $matches[1];
$value = Cache::get($key, 0);
$metrics[] = "http_response_time{path=\"{$path}\"} {$value}";
}
}


return implode("\n", $metrics);
}
}

此时,Prometheus 关于 ThinkPHP 的检查已经可以正常进行了。在后续的检查中,我们可以使用 Consul 的 API,通过创建相应的业务完成自动化注册的流程。


过滤以及重写规则

我们发现,有一些不需要监测的项目被顺带放进面板中,此时可以使用 relabel_configs 进行重写。例如在本次例子中,我们可以以 Consul 的标签为例,去掉 Consul 本身的检查。

在 Prometheus 中,relabel_configs 是用于对服务发现获取的目标(Target)元数据进行标签重写、过滤、新增或删除的核心配置。它在目标被实际抓取前生效,能灵活处理服务发现(如 Consul、K8s 等)返回的元数据,实现目标筛选、标签标准化等需求。

核心配置项

relabel_configs 由一系列重写规则组成,每个规则包含以下关键参数(常用):

参数 作用
source_labels 从目标的元数据中提取的标签列表(如 [__meta_consul_tags, __address__]),多个标签用逗号分隔。
separator source_labels 有多个标签时,用于拼接它们的分隔符(默认是 ;)。
regex 用于匹配 source_labels 拼接后的值的正则表达式(默认是 (.*),即匹配任意内容)。
modulus source_labels 拼接后的值做哈希取模,用于分片(较少用)。
target_label 重写后要生成的目标标签名(仅在 action: replace 等需要生成新标签的场景使用)。
replacement 正则匹配后的替换值,可通过 $1$2 引用正则中的分组(默认是 $1)。
action 重写动作(核心),决定对匹配的目标做什么操作(如保留、丢弃、替换标签等)。

常用 action 动作及示例

action 是重写规则的核心,决定了对目标的处理逻辑,常见动作如下:

1. keep:保留匹配的目标

仅保留 source_labels 拼接后的值能匹配 regex 的目标,其他目标会被过滤掉。

示例:只保留 Consul 服务标签中包含 php 的目标(对应你之前的配置):

1
2
3
4
relabel_configs:
- source_labels: [__meta_consul_tags] # 从Consul元数据中获取服务标签(如"php8.1,web")
regex: .*php.* # 匹配包含"php"的标签
action: keep # 保留匹配的目标

2. drop:丢弃匹配的目标

keep 相反,丢弃 source_labels 拼接后的值匹配 regex 的目标,保留其他目标。

示例:丢弃标签中包含 test 的目标(不监控测试环境服务):

1
2
3
4
relabel_configs:
- source_labels: [__meta_consul_tags]
regex: .*test.*
action: drop # 丢弃匹配的目标

3. replace:替换/新增标签

source_labels 匹配 regex 的值,通过 replacement 生成新值,并写入 target_label 指定的标签(若标签不存在则新增)。

示例1:将 Consul 服务名(__meta_consul_service)作为 app 标签:

1
2
3
4
5
6
relabel_configs:
- source_labels: [__meta_consul_service] # Consul服务名(如"thinkphp8")
regex: (.*) # 匹配整个服务名
target_label: app # 生成标签"app"
replacement: $1 # 用服务名作为标签值($1引用regex的第一个分组)
action: replace

示例2:从目标地址(__address__,格式 ip:port)中提取 IP 作为 instance_ip 标签:

1
2
3
4
5
6
relabel_configs:
- source_labels: [__address__] # 目标地址,如"192.168.87.177:8080"
regex: ([0-9]+\.[0-9]+\.[0-9]+\.[0-9]+):(.*) # 分组1:IP,分组2:端口
target_label: instance_ip # 生成标签"instance_ip"
replacement: $1 # 用IP作为标签值
action: replace

4. labelmap:批量映射标签

根据 regex 匹配现有标签名,将匹配的标签名替换为 replacement 中的值(常用于将元数据标签转为业务标签)。

示例:将 Consul 元数据中以 __meta_consul_tag_ 开头的标签(如 __meta_consul_tag_env=prod)转为 env=prod

1
2
3
4
relabel_configs:
- regex: __meta_consul_tag_(.+) # 匹配标签名(如"__meta_consul_tag_env")
replacement: $1 # 提取分组1作为新标签名(如"env")
action: labelmap # 批量映射标签

5. labeldrop:删除指定标签

删除所有标签名匹配 regex 的标签(常用于清理不需要的元数据标签)。

示例:删除所有以 __meta_consul_ 开头的元数据标签(避免冗余):

1
2
3
relabel_configs:
- regex: __meta_consul_.+ # 匹配所有Consul元数据标签
action: labeldrop # 删除匹配的标签

6. labelkeep:仅保留指定标签

labeldrop 相反,只保留标签名匹配 regex 的标签,删除其他所有标签。

示例:只保留 appinstancejob 三个标签:

1
2
3
relabel_configs:
- regex: (app|instance|job) # 仅匹配这三个标签
action: labelkeep # 保留匹配的标签,删除其他

7. hashmod:按哈希分片目标

将目标按 source_labels 哈希后取模,用于将目标分片到不同分组(如多 Prometheus 实例分片监控)。

示例:将目标按 __address__ 哈希后分为3组,只保留第1组:

1
2
3
4
5
6
7
8
relabel_configs:
- source_labels: [__address__]
modulus: 3 # 分为3组
target_label: __shard__ # 生成分片标签
action: hashmod
- source_labels: [__shard__]
regex: 0 # 只保留第1组(0是第1组,1是第2组,以此类推)
action: keep

关键元数据标签(以 Consul 为例)

当使用 Consul 服务发现时,Prometheus 会自动为目标添加以下元数据标签(可通过 source_labels 引用):

元数据标签 含义
__meta_consul_address 服务注册的IP地址
__meta_consul_port 服务注册的端口
__meta_consul_service 服务名称(如”ThinkPHP8”)
__meta_consul_tags 服务标签(逗号分隔,如”php8.1,web”)
__meta_consul_node 服务所在的Consul节点名称
__address__ 目标地址(自动拼接为 ip:port
__metrics_path__ 指标抓取路径(默认 /metrics

例如:在 relabel_configs 中,定义从 tags 进行过滤,通过正则匹配 php 标签(如 ThinkPHP8),通过 action 字段指定保留逻辑。

其中 action 字段的参数说明:

  • replace:根据 regex 匹配 source_labels 标签的值(多个标签值按 separator 拼接),将匹配结果写入 target_label;支持用 ${1}, ${2} 引用正则分组;未匹配则不修改标签(默认动作)。
  • keep:丢弃 source_labels 值未匹配 regex 的 Target 实例。
  • drop:丢弃 source_labels 值匹配 regex 的 Target 实例。
  • hashmod:将 target_label 设置为 source_labels 的哈希取模结果。
  • labelmap:用 regex 匹配标签名,捕获内容作为新标签名,原标签值作为新标签值。
  • labeldrop:删除所有匹配 regex 的标签。
  • labelkeep:删除所有不匹配 regex 的标签。
1
2
3
4
5
6
7
8
9
- job_name: 'consul-prometheus'
consul_sd_configs:
- server: '192.168.87.250:8500'
services: []
token: "d45af3b5-a433-fc4b-4ff8-b50411ca4bf3"
relabel_configs:
- source_labels: [__meta_consul_tags]
regex: .*php.*
action: keep

将配置文件更改后,发送回容器内部,会发现 Consul 本身不会出现在面板中:

1
2
docker cp $PWD/prometheus.yml prometheus:/etc/prometheus/prometheus.yml
docker restart prometheus