Skip to content

Commit

Permalink
doc/user: document new history relations
Browse files Browse the repository at this point in the history
  • Loading branch information
@teskje
teskje committed Aug 28, 2024
1 parent 042f476 commit eab0341
Show file tree
Hide file tree
Showing 2 changed files with 64 additions and 5 deletions.
47 changes: 42 additions & 5 deletions doc/user/content/sql/system-catalog/mz_catalog.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,10 +63,28 @@ Field | Type | Meaning
---------------|------------|----------
`id` | [`text`] | The ID of the type.

### `mz_cluster_replica_metrics_history`

{{< warn-if-unreleased v0.115 >}}
The `mz_cluster_replica_metrics_history` table records CPU, memory, and disk utilization metrics
for all processes of all extant cluster replicas.

At this time, we do not make any guarantees about the exactness or freshness of these numbers.

<!-- RELATION_SPEC mz_catalog.mz_cluster_replica_metrics_history -->
| Field | Type | Meaning
| ---------------- | --------- | --------
| `replica_id` | [`text`] | The ID of a cluster replica.
| `process_id` | [`uint8`] | An identifier of a process within the replica.
| `cpu_nano_cores` | [`uint8`] | Approximate CPU usage in billionths of a vCPU core.
| `memory_bytes` | [`uint8`] | Approximate memory usage in bytes.
| `disk_bytes` | [`uint8`] | Approximate disk usage in bytes.
| `occurred_at` | [`timestamp with time zone`] | Wall-clock timestamp at which the event occurred.

### `mz_cluster_replica_sizes`

The `mz_cluster_replica_sizes` table contains a mapping of logical sizes
(e.g. `100cc`) to physical sizes (number of processes, and CPU and memory allocations per process).
(e.g. `100cc`) to physical sizes (number of processes and resource allocations per process).

This table was previously in the `mz_internal` schema. All queries previously referencing
`mz_internal.mz_cluster_replica_sizes` should now reference `mz_catalog.mz_cluster_replica_sizes`.
Expand All @@ -77,16 +95,34 @@ any kind of capacity planning.
{{< /warning >}}

<!-- RELATION_SPEC mz_catalog.mz_cluster_replica_sizes -->
| Field | Type | Meaning |
| Field | Type | Meaning
|------------------------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `size` | [`text`] | The human-readable replica size. |
| `processes` | [`uint8`] | The number of processes in the replica. |
| `workers` | [`uint8`] | The number of Timely Dataflow workers per process. |
| `cpu_nano_cores` | [`uint8`] | The CPU allocation per process, in billionths of a vCPU core. |
| `memory_bytes` | [`uint8`] | The RAM allocation per process, in billionths of a vCPU core. |
| `disk_bytes` | [`uint8`] | The disk allocation per process. |
| `cpu_nano_cores` | [`uint8`] | The CPU allocation per process in billionths of a vCPU core. |
| `memory_bytes` | [`uint8`] | The RAM allocation per process in bytes. |
| `disk_bytes` | [`uint8`] | The disk allocation per process in bytes. |
| `credits_per_hour` | [`numeric`] | The number of compute credits consumed per hour. |

### `mz_cluster_replica_utilization_history`

{{< warn-if-unreleased v0.115 >}}
The `mz_cluster_replica_utilization_history` view records CPU, memory, and disk utilization metrics
for all processes of all extant cluster replicas, as a percentage of the total resource allocation.

At this time, we do not make any guarantees about the exactness or freshness of these numbers.

<!-- RELATION_SPEC mz_catalog.mz_cluster_replica_utilization_history -->
| Field | Type | Meaning
|------------------|----------------------|--------
| `replica_id` | [`text`] | The ID of a cluster replica.
| `process_id` | [`uint8`] | An identifier of a compute process within the replica.
| `cpu_percent` | [`double precision`] | Approximate CPU usage in percent of the total allocation.
| `memory_percent` | [`double precision`] | Approximate RAM usage in percent of the total allocation.
| `disk_percent` | [`double precision`] | Approximate disk usage in percent of the total allocation.
| `occurred_at` | [`timestamp with time zone`] | Wall-clock timestamp at which the event occurred.

### `mz_cluster_replicas`

The `mz_cluster_replicas` table contains a row for each cluster replica in the system.
Expand Down Expand Up @@ -614,6 +650,7 @@ Field | Type | Meaning

[`bigint`]: /sql/types/bigint
[`boolean`]: /sql/types/boolean
[`double precision`]: /sql/types/double-precision
[`integer`]: /sql/types/integer/
[`interval`]: /sql/types/interval
[`jsonb`]: /sql/types/jsonb
Expand Down
22 changes: 22 additions & 0 deletions test/sqllogictest/autogenerated/mz_catalog.slt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,16 @@ SELECT position, name, type FROM objects WHERE schema = 'mz_catalog' AND object
----
1 id text

query ITT
SELECT position, name, type FROM objects WHERE schema = 'mz_catalog' AND object = 'mz_cluster_replica_metrics_history' ORDER BY position
----
1 replica_id text
2 process_id uint8
3 cpu_nano_cores uint8
4 memory_bytes uint8
5 disk_bytes uint8
6 occurred_at timestamp␠with␠time␠zone

query ITT
SELECT position, name, type FROM objects WHERE schema = 'mz_catalog' AND object = 'mz_cluster_replica_sizes' ORDER BY position
----
Expand All @@ -67,6 +77,16 @@ SELECT position, name, type FROM objects WHERE schema = 'mz_catalog' AND object
6 disk_bytes uint8
7 credits_per_hour numeric

query ITT
SELECT position, name, type FROM objects WHERE schema = 'mz_catalog' AND object = 'mz_cluster_replica_utilization_history' ORDER BY position
----
1 replica_id text
2 process_id uint8
3 cpu_percent double␠precision
4 memory_percent double␠precision
5 disk_percent double␠precision
6 occurred_at timestamp␠with␠time␠zone

query ITT
SELECT position, name, type FROM objects WHERE schema = 'mz_catalog' AND object = 'mz_cluster_replicas' ORDER BY position
----
Expand Down Expand Up @@ -411,7 +431,9 @@ mz_array_types
mz_audit_events
mz_aws_privatelink_connections
mz_base_types
mz_cluster_replica_metrics_history
mz_cluster_replica_sizes
mz_cluster_replica_utilization_history
mz_cluster_replicas
mz_clusters
mz_columns
Expand Down

0 comments on commit eab0341

Please sign in to comment.