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
)

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

必需参数

名称	类型	描述
`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
)

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

必需参数

名称	类型	描述
`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`	`间隔`	结果聚合应涵盖的时间长度。如果没有提供，则返回的心跳聚合将在与开始时间相同的时间结束。

返回值

列	类型	描述
`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()

相关内容