{"id":19756827,"url":"https://github.com/imiphp/imi-prometheus","last_synced_at":"2025-04-30T12:30:53.850Z","repository":{"id":61806597,"uuid":"555235484","full_name":"imiphp/imi-prometheus","owner":"imiphp","description":null,"archived":false,"fork":false,"pushed_at":"2022-11-23T06:17:24.000Z","size":49,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"2.1","last_synced_at":"2024-05-23T01:31:12.447Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/imiphp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-10-21T07:30:09.000Z","updated_at":"2022-12-02T05:09:40.000Z","dependencies_parsed_at":"2023-01-22T06:02:58.120Z","dependency_job_id":null,"html_url":"https://github.com/imiphp/imi-prometheus","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imiphp%2Fimi-prometheus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imiphp%2Fimi-prometheus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imiphp%2Fimi-prometheus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imiphp%2Fimi-prometheus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imiphp","download_url":"https://codeload.github.com/imiphp/imi-prometheus/tar.gz/refs/heads/2.1","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224107282,"owners_count":17256923,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T03:17:06.266Z","updated_at":"2024-11-12T03:17:06.803Z","avatar_url":"https://github.com/imiphp.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# imi-prometheus\n\n[![Latest Version](https://img.shields.io/packagist/v/imiphp/imi-prometheus.svg)](https://packagist.org/packages/imiphp/imi-prometheus)\n[![Php Version](https://img.shields.io/badge/php-%3E=7.4-brightgreen.svg)](https://secure.php.net/)\n[![Swoole Version](https://img.shields.io/badge/swoole-%3E=4.8.0-brightgreen.svg)](https://github.com/swoole/swoole-src)\n[![imi License](https://img.shields.io/badge/license-MulanPSL%202.0-brightgreen.svg)](https://github.com/imiphp/imi-prometheus/blob/2.1/LICENSE)\n\n## 介绍\n\n此项目是 imi 框架的普罗米修斯（Prometheus）服务监控指标组件。\n\n普罗米修斯官方文档：\u003chttps://prometheus.io/docs/introduction/overview/\u003e\n\n\u003e 正在开发中，随时可能修改，请勿用于生产环境！\n\n## 安装\n\n`composer require imiphp/imi-prometheus:~2.1.0`\n\n## 使用说明\n\n普罗米修斯组件只支持以实例为单位上报，不支持以 Worker 进程为单位。\n\n### 配置\n\n首先需要配置 Redis 连接，可以参考文档，这里不再赘述。\n\n**配置监控指标：**\n\n`@app.beans`：\n\n```php\n[\n    'MeterRegistry' =\u003e [\n        'driver'  =\u003e \\Imi\\Prometheus\\PrometheusMeterRegistry::class,\n        'options' =\u003e [\n            'adapter' =\u003e [\n                'class'   =\u003e \\Imi\\Prometheus\\Storage\\Redis::class,\n                'options' =\u003e [\n                    // 'poolName' =\u003e null, // 连接池名称，如果为 null 则使用默认 Redis 连接池\n                    // 'prefix' =\u003e 'PROMETHEUS_', // 键名前缀\n                ],\n            ],\n            // 所有标签如设为空字符串或 null 则忽略该标签\n            'resultTag' =\u003e 'result', // 标签名-结果\n            'exceptionTag' =\u003e 'exception', // 标签名-异常类名\n            'instanceTag' =\u003e 'instance', // 标签名-实例\n            'workerTag' =\u003e 'worker', // 标签名-WorkerId\n            'instance' =\u003e 'imi', // 当前实例名称，每个实例要设置不同\n        ],\n    ],\n]\n```\n\n### 使用\n\n#### 内置监控\n\n##### 连接池监控\n\n`@app.beans`：\n\n```php\n// 连接池监控\n'PoolMonitor' =\u003e [\n    'enable'         =\u003e true, // 启用\n    // 'pools'       =\u003e null, // 监控的连接池名称数组。如果为 null 则代表监控所有连接池\n    // 'interval'    =\u003e 10, // 上报时间间隔，单位：秒\n    // 'countKey'    =\u003e 'pool_count', // 连接总数量键名\n    // 'usedKey'     =\u003e 'pool_used', // 忙碌连接数量键名\n    // 'freeKey'     =\u003e 'pool_free', // 空间连接数量键名\n    // 'workerIdTag' =\u003e 'worker_id', // 工作进程 ID 标签名\n    // 'poolNameTag' =\u003e 'pool_name', // 连接池标签名\n],\n```\n\n##### Swoole 服务器指标监控\n\n`@app.beans`：\n\n```php\n// Swoole 服务器指标监控\n'SwooleServerMonitor' =\u003e [\n    'enable'         =\u003e true, // 启用\n    // 要监控的指标名称数组\n    // 详见：https://wiki.swoole.com/#/server/methods?id=stats\n    // 格式1：stats() 指标名称 =\u003e 实际指标名称\n    // 格式2：stats() 指标名称同时作为实际指标名称\n    'stats'          =\u003e [\n        'connection_num' =\u003e 'swoole_connection',\n        'request_count'  =\u003e 'swoole_request_count',\n        'coroutine_num'  =\u003e 'swoole_coroutine_num',\n        'coroutine_num',\n    ],\n    // 'interval'    =\u003e 10, // 上报时间间隔，单位：秒\n    // 'workerIdTag' =\u003e 'worker_id', // 工作进程 ID 标签名\n],\n```\n\n#### 注解\n\n##### @Counted\n\n类名：`\\Imi\\Meter\\Annotation\\Counted`\n\n计数统计，适合只累加，不减少的统计数据类型。\n\n例如：访问次数统计。\n\n| 参数名 | 类型 | 默认值  | 描述 |\n| ------ | ------ | ------ | ------ |\n| name | `string` | `imi.counted` | 指标名称 |\n| recordFailuresOnly | `false` | `bool` | 是否只在抛出异常时记录 |\n| tags | `array` | `[]` | 标签，键值数组 |\n| description | `string` |  | 描述 |\n| options | `array` | `[]` | 额外参数，每个驱动不同 |\n\n##### @Gauged\n\n类名：`\\Imi\\Meter\\Annotation\\Gauged`\n\n适合数字有上下波动的统计。\n\n例如：CPU 占用率统计。\n\n| 参数名 | 类型 | 默认值  | 描述 |\n| ------ | ------ | ------ | ------ |\n| name | `string` | `imi.counted` | 指标名称 |\n| recordFailuresOnly | `false` | `bool` | 是否只在抛出异常时记录 |\n| tags | `array` | `[]` | 标签，键值数组 |\n| description | `string` |  | 描述 |\n| value | `string\\|float` | `{returnValue}` | 写入的值；`{returnValue}` 表示方法返回值；`{returnValue.xxx}` 表示方法返回值的属性值；`{params.0}` 表示方法参数值；`{params.0.xxx}` 表示方法参数值的属性值；也可以是固定的 `float` 值 |\n| operation | `int` | `\\Imi\\Meter\\Enum\\GaugeOperation::SET` | 操作类型。设置`GaugeOperation::SET`；增加`GaugeOperation::INCREMENT`；减少`GaugeOperation::DECREMENT` |\n| options | `array` | `[]` | 额外参数，每个驱动不同 |\n\n##### @Timed\n\n类名：`\\Imi\\Meter\\Annotation\\Timed`\n\n耗时统计。\n\n例如：方法执行耗时\n\n| 参数名 | 类型 | 默认值  | 描述 |\n| ------ | ------ | ------ | ------ |\n| name | `string` | `imi.counted` | 指标名称 |\n| tags | `array` | `[]` | 标签，键值数组 |\n| description | `string` |  | 描述 |\n| baseTimeUnit | `int` | `\\Imi\\Meter\\Enum\\TimeUnit::NANO_SECOND` | 基础时间单位，默认纳秒，可以使用 `\\Imi\\Meter\\Enum\\TimeUnit::XXX` 常量设置。 |\n| options | `array` | `[]` | 额外参数，每个驱动不同 |\n\n`options` 在普罗米修斯的特定配置：\n\n```php\n[\n    'histogram' =\u003e true, // 设置为柱状图，否则默认为 Summary\n    'buckets' =\u003e [], // 桶，仅柱状图\n    'maxAgeSeconds' =\u003e 600, // Summary 最大生存时间\n    'percentile' =\u003e [], // Summary 百分位\n]\n```\n\n##### @Histogram\n\n类名：`\\Imi\\Meter\\Annotation\\Histogram`\n\n柱状图，一般人用不懂，如无特殊需求可以无视。\n\n| 参数名 | 类型 | 默认值  | 描述 |\n| ------ | ------ | ------ | ------ |\n| name | `string` | `imi.counted` | 指标名称 |\n| tags | `array` | `[]` | 标签，键值数组 |\n| description | `string` |  | 描述 |\n| buckets | `array` | `[]` | 桶，例如：`[100, 500, 1000]` |\n| baseTimeUnit | `int` | `\\Imi\\Meter\\Enum\\TimeUnit::NANO_SECOND` | 基础时间单位，默认纳秒，可以使用 `\\Imi\\Meter\\Enum\\TimeUnit::XXX` 常量设置。 |\n| value | `string\\|float` | `{returnValue}` | 写入的值；`{returnValue}` 表示方法返回值；`{returnValue.xxx}` 表示方法返回值的属性值；`{params.0}` 表示方法参数值；`{params.0.xxx}` 表示方法参数值的属性值；也可以是固定的 `float` 值 |\n| options | `array` | `[]` | 额外参数，每个驱动不同 |\n\n##### @Summary\n\n类名：`\\Imi\\Meter\\Annotation\\Summary`\n\n采样点分位图，一般人用不懂，如无特殊需求可以无视。\n\n| 参数名 | 类型 | 默认值  | 描述 |\n| ------ | ------ | ------ | ------ |\n| name | `string` | `imi.counted` | 指标名称 |\n| tags | `array` | `[]` | 标签，键值数组 |\n| description | `string` |  | 描述 |\n| percentile | `array` | `[]` | 百分位数，例如：`[0.01, 0.5, 0.99]` |\n| baseTimeUnit | `int` | `\\Imi\\Meter\\Enum\\TimeUnit::NANO_SECOND` | 基础时间单位，默认纳秒，可以使用 `\\Imi\\Meter\\Enum\\TimeUnit::XXX` 常量设置。 |\n| value | `string\\|float` | `{returnValue}` | 写入的值；`{returnValue}` 表示方法返回值；`{returnValue.xxx}` 表示方法返回值的属性值；`{params.0}` 表示方法参数值；`{params.0.xxx}` 表示方法参数值的属性值；也可以是固定的 `float` 值 |\n| options | `array` | `[]` | 额外参数，每个驱动不同 |\n\n**代码示例：**\n\n```php\nuse Imi\\Meter\\Annotation\\Gauged;\nuse Imi\\Meter\\Annotation\\Histogram;\nuse Imi\\Meter\\Annotation\\Summary;\nuse Imi\\Meter\\Annotation\\Timed;\nuse Imi\\Meter\\Enum\\TimeUnit;\n\n/**\n * @Gauged(name=\"test_memory_usage\", description=\"memory usage\", tags={\"workerId\"=\"{returnValue.workerId}\"}, value=\"{returnValue.memory}\")\n */\npublic function recordMemoryUsage(): array\n{\n    return [\n        'workerId' =\u003e Worker::getWorkerId(),\n        'memory'   =\u003e memory_get_usage(),\n    ];\n}\n\n/**\n * @Timed(name=\"test_timed\", description=\"memory usage\", baseTimeUnit=TimeUnit::MILLI_SECONDS, options={\"quantiles\"={0.1, 0.5, 0.99}})\n */\npublic function testTimed(): int\n{\n    $ms = mt_rand(10, 1000);\n    usleep($ms * 1000);\n\n    return $ms;\n}\n\n/**\n * @Timed(name=\"test_timed_histogram\", description=\"memory usage\", baseTimeUnit=TimeUnit::MILLI_SECONDS, options={\"histogram\"=true, \"buckets\"={50, 100, 300, 600, 800, 1000}})\n */\npublic function testTimedHistogram(): int\n{\n    $ms = mt_rand(10, 1000);\n    usleep($ms * 1000);\n\n    return $ms;\n}\n\n/**\n * @Histogram(name=\"test_histogram\", baseTimeUnit=TimeUnit::MILLI_SECONDS, buckets={50, 100, 300, 600, 800, 1000})\n */\npublic function testHistogram(): int\n{\n    return mt_rand(10, 1000);\n}\n\n/**\n * @Summary(name=\"test_summary\", baseTimeUnit=TimeUnit::MILLI_SECONDS, percentile={0.1, 0.5, 0.99})\n */\npublic function testSummary(): int\n{\n    return mt_rand(10, 1000);\n}\n```\n\n#### 手动操作\n\n```php\nuse \\Imi\\Meter\\Facade\\MeterRegistry;\nuse \\Imi\\Meter\\Enum\\TimeUnit;\n\n$description = '我是描述';\n$tags = ['result' =\u003e 'success'];\n\n// counter\nMeterRegistry::getDriverInstance()-\u003ecounter('testCounterManual', $tags, $description)-\u003eincrement();\n\n// gauge\nMeterRegistry::getDriverInstance()-\u003egauge('testGaugeManual', $tags, $description)-\u003erecord(114514);\n\n// timer\n$timer = MeterRegistry::getDriverInstance()-\u003etimer('testTimedManual', $tags, $description, TimeUnit::MILLI_SECONDS);\n$timerSample = $timer-\u003estart();\nusleep(mt_rand(10, 1000) * 1000);\n$timerSample-\u003estop($timer);\n\n// timer Histogram\n$timer = MeterRegistry::getDriverInstance()-\u003etimer('testTimedHistogramManual', $tags, $description, TimeUnit::MILLI_SECONDS, [\n    'histogram' =\u003e true,\n    'buckets'   =\u003e [100, 500, 1500],\n]);\n$timerSample = $timer-\u003estart();\nusleep(mt_rand(10, 1000) * 1000); // 你的耗时代码\n$timerSample-\u003estop($timer);\n\n// Histogram\n$value = 114514;\n$buckets = [100, 500, 1500];\nMeterRegistry::getDriverInstance()-\u003ehistogram('testHistogramManual', $tags, $description, $buckets)-\u003erecord($value);\n\n// Summary\n$value = 114514;\n$percentile = [0.1, 0.5, 0.99];\nMeterRegistry::getDriverInstance()-\u003esummary('testHistogramManual', $tags, $description, $percentile)-\u003erecord($value);\n```\n\n#### 清除 Redis 驱动存储数据\n\n如果你的同名指标，修改了 `tags`，那么必须清理存储数据，否则会报错。\n\n`vendor/bin/imi-swoole prometheus/wipe`\n\n## 免费技术支持\n\nQQ群：17916227 [![点击加群](https://pub.idqqimg.com/wpa/images/group.png \"点击加群\")](https://jq.qq.com/?_wv=1027\u0026k=5wXf4Zq)，如有问题会有人解答和修复。\n\n## 运行环境\n\n* [PHP](https://php.net/) \u003e= 7.4\n* [Composer](https://getcomposer.org/) \u003e= 2.0\n* [Swoole](https://www.swoole.com/) \u003e= 4.8.0\n* [imi](https://www.imiphp.com/) \u003e= 2.1\n\n## 版权信息\n\n`imi-prometheus` 遵循 MulanPSL-2.0 开源协议发布，并提供免费使用。\n\n## 捐赠\n\n\u003cimg src=\"https://cdn.jsdelivr.net/gh/imiphp/imi@2.1/res/pay.png\"/\u003e\n\n开源不求盈利，多少都是心意，生活不易，随缘随缘……\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimiphp%2Fimi-prometheus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimiphp%2Fimi-prometheus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimiphp%2Fimi-prometheus/lists"}