heartbeat_agg() 函数

工具包TimescaleDB 工具包函数在 Timescale 社区版下可用。它们自动包含在 Timescale 中，但对于自托管的 TimescaleDB 必须单独安装。点击了解更多。

给定一系列带时间戳的心跳和活动间隔，确定系统的总体活动状态。此聚合可用于报告总正常运行时间或停机时间，以及报告系统处于活动或非活动状态的时间范围。

还可以组合多个心跳聚合来确定服务的总体健康状况。例如，可以组合来自主服务器和备用服务器的心跳聚合，以查看是否曾经出现过两台机器同时宕机的情况。

此组中的函数

heartbeat_agg: 从一组心跳创建活动状态聚合

dead_ranges: 从 heartbeat_agg 获取宕机间隔
downtime: 获取心跳聚合期间的总宕机时间
interpolate: 使用前置信息调整心跳聚合
interpolated_downtime: 从心跳聚合和前置信息获取总宕机时间
interpolated_uptime: 从心跳聚合和前置信息获取总正常运行时间
live_at: 测试聚合是否具有覆盖给定时间的心跳
live_ranges: 从 heartbeat_agg 获取活动间隔
num_gaps: 计算活动范围之间的间隙数
num_live_ranges: 计算活动范围的数量
trim_to: 减少心跳聚合的覆盖间隔
uptime: 获取心跳聚合期间的总正常运行时间

rollup: 组合多个心跳聚合

函数详情

heartbeat_agg(
    heartbeat TIMESTAMPTZ,
    agg_start TIMESTAMPTZ,
    agg_duration INTERVAL,
    heartbeat_liveness INTERVAL
) RETURNS HeartbeatAgg

这会获取一组心跳时间戳，并聚合指定时间范围内底层系统的活动状态。

必需参数

名称	类型	描述
`heartbeat`	`TIMESTAMPTZ`	包含心跳时间戳的列。
`agg_start`	`TIMESTAMPTZ`	聚合跟踪活动状态的时间范围的开始时间。
`agg_duration`	`INTERVAL`	聚合跟踪活动状态的时间范围的长度。此范围内的任何未紧跟心跳的点都被视为非活动状态。
`heartbeat_liveness`	`INTERVAL`	每次心跳后系统被视为活动状态的时长。

返回值

列	类型	描述
`heartbeat_agg`	`HeartbeatAgg`	在提供的间隔内，心跳系统的活动状态数据。

示例

给定一个名为 system_health 的表，其中包含 ping_time 列，构建从 2022 年 1 月 1 日开始的 10 天系统活动状态聚合。这假设如果在 5 分钟窗口内没有收到系统的心跳，则系统不健康


SELECT heartbeat_agg(
  ping_time,
  '01-01-2022 UTC',
  '10 days',
  '5 min')
FROM system_health;

dead_ranges(
    agg HEARTBEATAGG
) RETURNS TABLE (
    start TIMESTAMPTZ,
    end TIMESTAMPTZ
)

给定一个心跳聚合，这将返回一组 (start_time, end_time) 对，表示在聚合的时间间隔内，底层系统何时没有有效的心跳。

必需参数

名称	类型	描述
`agg`	`HeartbeatAgg`	要从中获取活动状态数据的心跳聚合。

返回值

列	类型	描述
`dead_ranges`	`TABLE (start TIMESTAMPTZ, end TIMESTAMPTZ)`	系统宕机时的 (start, end) 对。

示例

给定一个名为 liveness 的表，其中包含列 health 中的每周心跳聚合和时间戳列 date，我们可以使用以下方法来获取系统在 2022 年 1 月 9 日这一周内宕机的间隔


SELECT dead_ranges(health)
FROM liveness
WHERE date = '01-9-2022 UTC'


dead_ranges                     
-----------------------------------------------------
("2022-01-09 00:00:00+00","2022-01-09 00:00:30+00")
("2022-01-12 15:27:22+00","2022-01-12 15:31:17+00")

downtime(
    agg HEARTBEATAGG
) RETURNS INTERVAL

给定一个心跳聚合，这将对系统中没有最近心跳的所有范围进行求和。

在聚合的开始和第一个心跳之间似乎存在一些宕机时间。如果存在覆盖前一个时期的心跳聚合，您可以使用其最后一个心跳来使用 interpolated_downtime() 进行更正。

必需参数

名称	类型	描述
`agg`	`HeartbeatAgg`	要从中获取活动状态数据的心跳聚合。

返回值

列	类型	描述
`downtime`	`INTERVAL`	聚合中所有宕机范围的总和。

示例

给定一个名为 liveness 的表，其中包含列 health 中的每周心跳聚合和时间戳列 date，我们可以使用以下方法来获取系统在 2022 年 1 月 9 日这一周内的总宕机时间


SELECT downtime(health)
FROM liveness
WHERE date = '01-9-2022 UTC'


downtime     
--------
00:04:25

interpolate(
    agg HEARTBEATAGG,
    pred HEARTBEATAGG
) RETURNS HEARTBEATAGG

这会获取一个心跳聚合以及紧随其后的前一个聚合。它会更新聚合以包含应从前置信息中的最后一个心跳延续的任何活动范围，即使此聚合覆盖的间隔中没有该范围的心跳。它返回更新后的聚合，然后可以将其与任何心跳聚合访问器一起使用。

必需参数

名称	类型	描述
`agg`	`HeartbeatAgg`	包含特定间隔的活动状态数据的心跳聚合。

可选参数

名称	类型	描述
`pred`	`HeartbeatAgg`	前一个间隔的心跳聚合（如果存在）。

返回值

列	类型	描述
`interpolate`	`HeartbeatAgg`	`agg` 的副本，已更新为包含任何超出 `pred` 结尾的心跳间隔。

示例

给定一个名为 liveness 的表，其中包含列 health 中的每周心跳聚合和时间戳列 date，我们可以使用以下方法来获取系统在 2022 年 1 月 9 日这一周内不健康的间隔。这可以正确排除 1 月 2 日这一周结束时心跳覆盖的任何范围


SELECT dead_ranges(
  interpolate(
    health,
    LAG(health) OVER (ORDER BY date)
  )
)
FROM liveness
WHERE date = '01-9-2022 UTC'


dead_ranges                     
-----------------------------------------------------
("2022-01-12 15:27:22+00","2022-01-12 15:31:17+00")

interpolated_downtime(
    agg HEARTBEATAGG,
    pred HEARTBEATAGG
) RETURNS INTERVAL

这与 downtime() 的行为非常相似，但它也接受来自前一个间隔的心跳聚合。它检查前置信息中最后一次接收到心跳的时间，并确保不将该时间之后的心跳间隔视为不健康，即使它在第一个心跳之前延伸到当前聚合中。

必需参数

名称	类型	描述
`agg`	`HeartbeatAgg`	要从中获取活动状态数据的心跳聚合。

可选参数

名称	类型	描述
`pred`	`HeartbeatAgg`	被测间隔之前间隔的心跳聚合（如果存在）。

返回值

列	类型	描述
`interpolated_downtime`	`INTERVAL`	聚合中所有不健康范围的总和，不包括前一个间隔的最后一个心跳覆盖的范围。

示例

给定一个名为 liveness 的表，其中包含列 health 中的每周心跳聚合和时间戳列 date，您可以使用此命令来获取系统在 2022 年 1 月 9 日这一周内的总插值宕机时间


SELECT interpolated_downtime(
  health,
  LAG(health) OVER (ORDER BY date)
)
FROM liveness
WHERE date = '01-9-2022 UTC'


interpolated_downtime     
---------------------
       00:03:55

interpolated_uptime(
    agg HEARTBEATAGG,
    pred HEARTBEATAGG
) RETURNS INTERVAL

这与 uptime() 的行为非常相似，但它也接受来自前一个间隔的心跳聚合。它检查前置信息中最后一次接收到心跳的时间，并确保将该时间之后的整个心跳间隔都视为活动状态。这解决了 uptime 会将间隔的开始和第一个心跳之间的间隔视为非活动状态的问题。

必需参数

名称	类型	描述
`agg`	`HeartbeatAgg`	要从中获取活动状态数据的心跳聚合。

可选参数

名称	类型	描述
`pred`	`HeartbeatAgg`	被测间隔之前间隔的心跳聚合（如果存在）。

返回值

列	类型	描述
`interpolated_uptime`	`INTERVAL`	聚合中所有活动范围的总和，包括前一个间隔的最后一个心跳覆盖的范围。

示例

给定一个名为 liveness 的表，其中包含列 health 中的每周心跳聚合和时间戳列 date，您可以使用此命令来获取系统在 2022 年 1 月 9 日这一周内的总插值正常运行时间


SELECT interpolated_uptime(
  health,
  LAG(health) OVER (ORDER BY date)
)
FROM liveness
WHERE date = '01-9-2022 UTC'


interpolated_uptime     
-------------------
  6 days 23:56:05

live_at(
    agg HEARTBEATAGG,
    test TIMESTAMPTZ
) RETURNS BOOL

给定一个心跳聚合和一个时间戳，这将返回聚合是否具有指示系统在给定时间处于活动状态的心跳。

请注意，对于聚合未覆盖的任何时间，这都会返回 false。

必需参数

名称	类型	描述
`agg`	`HeartbeatAgg`	要从中获取活动状态数据的心跳聚合。
`test`	`TimestampTz`	要测试活动状态的时间。

返回值

列	类型	描述
`live_at`	`bool`	如果心跳聚合在测试时间之前不久有心跳，则为 True。

示例

给定一个名为 liveness 的表，其中包含列 health 中的每周心跳聚合和时间戳列 date，我们可以使用以下方法来查看系统在特定时间是否处于活动状态


SELECT live_at(health, '2022-01-12 15:30:00+00')
FROM liveness
WHERE date = '01-9-2022 UTC'


live_at     
---------
 f

live_ranges(
    agg HEARTBEATAGG
) RETURNS TABLE (
    start TIMESTAMPTZ,
    end TIMESTAMPTZ
)

给定一个心跳聚合，这将返回一组 (start_time, end_time) 对，表示在聚合的时间间隔内，底层系统何时处于活动状态。

必需参数

名称	类型	描述
`agg`	`HeartbeatAgg`	要从中获取活动状态数据的心跳聚合。

返回值

列	类型	描述
`live_ranges`	`TABLE (start TIMESTAMPTZ, end TIMESTAMPTZ)`	系统活动时的 (start, end) 对。

示例

给定一个名为 liveness 的表，其中包含列 health 中的每周心跳聚合和时间戳列 date，我们可以使用以下方法来获取系统在 2022 年 1 月 9 日这一周内处于活动状态的间隔


SELECT live_ranges(health)
FROM liveness
WHERE date = '01-9-2022 UTC'


live_ranges                     
-----------------------------------------------------
("2022-01-09 00:00:30+00","2022-01-12 15:27:22+00")
("2022-01-12 15:31:17+00","2022-01-16 00:00:00+00")

num_gaps(
    agg HEARTBEATAGG
) RETURNS BIGINT

给定一个心跳聚合，这将返回活动周期之间的间隙数。此外，如果聚合在其覆盖间隔的开始或结束时未处于活动状态，则这些也被视为间隙。

必需参数

名称	类型	描述
`agg`	`HeartbeatAgg`	要从中获取间隙数的心跳聚合。

返回值

列	类型	描述
`num_gaps`	`bigint`	聚合中的间隙数。

示例

给定一个名为 liveness 的表，其中包含列 health 中的每周心跳聚合和时间戳列 date，使用此查询查看系统在特定一周内宕机了多少次：


SELECT num_gaps(health)
FROM liveness
WHERE date = '01-9-2022 UTC'


num_gaps
---------
4

num_live_ranges(
    agg HEARTBEATAGG
) RETURNS BIGINT

给定一个心跳聚合，这将返回活动周期的数量。

必需参数

名称	类型	描述
`agg`	`HeartbeatAgg`	要从中获取范围数的心跳聚合。

返回值

列	类型	描述
`num_live_ranges`	`bigint`	聚合中的活动范围数。

示例

给定一个名为 liveness 的表，其中包含列 health 中的每周心跳聚合和时间戳列 date，使用此查询查看系统在给定一周内启动了多少个间隔：


SELECT num_live_ranges(health)
FROM liveness
WHERE date = '01-9-2022 UTC'


num_live_ranges
---------
5

trim_to(
    agg HEARTBEATAGG,
    start TIMESTAMPTZ,
    duration INTERVAL
) RETURNS HEARTBEATAGG

给定一个心跳聚合，这将减少该聚合覆盖的时间范围。这只能用于缩小覆盖间隔，传递将超出初始聚合覆盖范围的参数会产生错误。

必需参数

名称	类型	描述
`agg`	`HeartbeatAgg`	要缩减的心跳聚合。

可选参数

名称	类型	描述
`start`	`TimestampTz`	修剪范围的开始时间。如果未提供，则返回的心跳聚合从与起始聚合相同的时间开始。
`duration`	`Interval`	生成的聚合应覆盖的时长。如果未提供，则返回的心跳聚合在与起始聚合相同的时间结束。

返回值

列	类型	描述
`trim_to`	`heartbeat_agg`	修剪后的聚合。

示例

给定一个名为 liveness 的表，其中包含列 health 中的每周心跳聚合和时间戳列 date，使用此查询来汇总几周，并将结果修剪为精确的一个月：


SELECT trim_to(rollup(health), '03-1-2022 UTC', '1 month')
FROM liveness
WHERE date > '02-21-2022 UTC' AND date < '3-7-2022 UTC'

uptime(
    agg HEARTBEATAGG
) RETURNS INTERVAL

给定一个心跳聚合，这将对系统中处于活动状态的所有范围进行求和，并返回总和。

在聚合的开始和第一个心跳之间似乎存在一些宕机时间。如果存在覆盖前一个时期的心跳聚合，您可以使用其最后一个心跳来使用 interpolated_uptime() 进行更正。

必需参数

名称	类型	描述
`agg`	`HeartbeatAgg`	要从中获取活动状态数据的心跳聚合。

返回值

列	类型	描述
`uptime`	`INTERVAL`	聚合中所有活动范围的总和。

示例

给定一个名为 liveness 的表，其中包含列 health 中的每周心跳聚合和时间戳列 date，您可以使用此命令来获取系统在 2022 年 1 月 9 日这一周内的总正常运行时间


SELECT uptime(health)
FROM liveness
WHERE date = '01-9-2022 UTC'


uptime     
-----------------
6 days 23:55:35

rollup(
  heartbeatagg HEARTBEATAGG
) RETURNS HEARTBEATAGG

这会将多个心跳聚合组合为一个。这可以用于将相邻间隔的聚合组合成一个更大的间隔，例如将每日聚合汇总为每周或每月聚合。

此功能的另一个用途是组合冗余系统的心跳聚合，以确定是否存在任何重叠的故障。例如，可以将主系统和备用系统的心跳组合在一起，以查看是否在任何间隔内两个系统都同时宕机。像这样将重叠的心跳汇总在一起的结果是一个心跳聚合，如果其任何组件聚合处于活动状态，则该时间将被视为活动状态。

必需参数

名称	类型	描述
`heartbeatagg`	`HeartbeatAgg`	要汇总的心跳聚合。

返回值

列	类型	描述
`rollup`	`HeartbeatAgg`	一个心跳聚合，覆盖从其组件聚合的最早开始时间到最晚结束时间的间隔。它组合了所有组件的活动范围。

heartbeat_agg() 函数

相关超级函数组

两步聚合

此组中的函数

聚合

访问器

汇总

函数详情

heartbeat_agg()

dead_ranges()

downtime()

interpolate()

interpolated_downtime()

interpolated_uptime()

live_at()

live_ranges()

num_gaps()

num_live_ranges()

trim_to()

uptime()

rollup()

heartbeat_agg() 函数

简介

相关超级函数组

两步聚合

此组中的函数

聚合

访问器

汇总

函数详情

heartbeat_agg()

dead_ranges()

downtime()

interpolate()

interpolated_downtime()

interpolated_uptime()

live_at()

live_ranges()

num_gaps()

num_live_ranges()

trim_to()

uptime()

rollup()

相关内容