heartbeat_agg() 函数

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

Timescale Cloud：性能、规模、企业级

自托管产品

MST

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

还可以组合多个心跳聚合来确定服务的整体健康状况。例如，可以将主服务器和备用服务器的心跳聚合组合起来，查看是否存在两台机器同时停机的时间窗口。

此组中的函数

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`	已更新以包含任何超出 `pred` 结束的心跳间隔的 `agg` 副本。

示例

给定一个名为 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`	`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()

相关内容