icydb-core 0.145.2

IcyDB — A schema-first typed query engine and persistence runtime for Internet Computer canisters
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

//! Module: executor::plan_metrics
//! Responsibility: lightweight execution observability event helpers.
//! Does not own: execution behavior or route-selection logic.
//! Boundary: metric projection utilities for executor call sites.

use crate::{
    db::access::{AccessPathKind, AccessPlan},
    db::executor::planning::route::GroupedExecutionMode,
    metrics::sink::{GroupedPlanExecutionMode, MetricsEvent, PlanKind, Span, record},
    traits::EntityKind,
};

/// Records metrics for the chosen execution plan.
/// Must be called exactly once per execution.
pub(super) fn record_plan_metrics<K>(access: &AccessPlan<K>) {
    let kind = access_plan_kind(access);

    record(MetricsEvent::Plan {
        kind,
        grouped_execution_mode: None,
    });
}

/// Records metrics for one grouped execution plan with explicit grouped execution mode.
/// Must be called exactly once per grouped execution.
pub(super) fn record_grouped_plan_metrics<K>(
    access: &AccessPlan<K>,
    grouped_execution_mode: GroupedExecutionMode,
) {
    let kind = access_plan_kind(access);
    let grouped_execution_mode = match grouped_execution_mode {
        GroupedExecutionMode::HashMaterialized => GroupedPlanExecutionMode::HashMaterialized,
        GroupedExecutionMode::OrderedMaterialized => GroupedPlanExecutionMode::OrderedMaterialized,
    };

    record(MetricsEvent::Plan {
        kind,
        grouped_execution_mode: Some(grouped_execution_mode),
    });
}

// This metric is intentionally coarse and only reflects the top-level access shape.
fn access_plan_kind<K>(access: &AccessPlan<K>) -> PlanKind {
    match access {
        AccessPlan::Path(path) => match path.kind() {
            AccessPathKind::ByKey | AccessPathKind::ByKeys => PlanKind::Keys,
            AccessPathKind::KeyRange => PlanKind::Range,
            AccessPathKind::IndexPrefix
            | AccessPathKind::IndexMultiLookup
            | AccessPathKind::IndexRange => PlanKind::Index,
            AccessPathKind::FullScan => PlanKind::FullScan,
        },
        AccessPlan::Union(_) | AccessPlan::Intersection(_) => PlanKind::FullScan,
    }
}

/// Convenience: set span rows from a usize length.
pub(super) const fn set_rows_from_len<E: EntityKind>(span: &mut Span<E>, len: usize) {
    span.set_rows(len as u64);
}

/// Record per-request rows scanned metrics for one structural entity path.
pub(super) fn record_rows_scanned_for_path(entity_path: &'static str, rows_scanned: usize) {
    record(MetricsEvent::RowsScanned {
        entity_path,
        rows_scanned: u64::try_from(rows_scanned).unwrap_or(u64::MAX),
    });
}

/// Record per-request rows filtered metrics for one structural entity path.
pub(super) fn record_rows_filtered_for_path(entity_path: &'static str, rows_filtered: usize) {
    record(MetricsEvent::RowsFiltered {
        entity_path,
        rows_filtered: u64::try_from(rows_filtered).unwrap_or(u64::MAX),
    });
}

/// Record per-request rows aggregated metrics for one structural entity path.
pub(super) fn record_rows_aggregated_for_path(entity_path: &'static str, rows_aggregated: usize) {
    record(MetricsEvent::RowsAggregated {
        entity_path,
        rows_aggregated: u64::try_from(rows_aggregated).unwrap_or(u64::MAX),
    });
}

/// Record per-request rows emitted metrics for one structural entity path.
pub(super) fn record_rows_emitted_for_path(entity_path: &'static str, rows_emitted: usize) {
    record(MetricsEvent::RowsEmitted {
        entity_path,
        rows_emitted: u64::try_from(rows_emitted).unwrap_or(u64::MAX),
    });
}