From 5d055d4459a341a3f5ce2226cc0b45d013e2a834 Mon Sep 17 00:00:00 2001 From: Dennis Zhuang Date: Sun, 23 Aug 2026 04:00:56 +0800 Subject: [PATCH] feat(semantic-graph): let the generic container yield to k8s.container MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A container inside a Kubernetes pod reaches the graph twice: as the k8s.container entity kube-state-metrics describes, identified by [pod uid, container name], and as the generic container the OTel resource attributes describe, identified by container.id. One physical container, two nodes. Kubernetes is the primary scenario, so k8s.container keeps its identity and the generic type stands down where it applies. Conventions gain a row-level condition for that: `suppressed_by` withdraws a declaration on rows where any of the named columns has a value. The test has to be per row, not per table — one descriptor table holds both pod rows and bare-runtime rows. Every branch that turns a declaration into rows now shares one guard (`declaration_predicate`), so the condition cannot apply to entities but not to the edges they carry. Signed-off-by: Dennis Zhuang --- src/frontend/src/instance/entity_graph.rs | 30 +++++++ src/operator/src/statement/semantic_graph.rs | 80 +++++++++++++++++-- .../statement/semantic_graph/conventions.rs | 16 ++++ .../statement/semantic_graph/conventions.yaml | 9 +++ .../statement/semantic_graph/relationships.rs | 19 ++--- .../common/system/semantic_graph.result | 24 ++++-- .../common/system/semantic_graph.sql | 16 ++-- 7 files changed, 166 insertions(+), 28 deletions(-) diff --git a/src/frontend/src/instance/entity_graph.rs b/src/frontend/src/instance/entity_graph.rs index a0817cf2806..b6cc263283a 100644 --- a/src/frontend/src/instance/entity_graph.rs +++ b/src/frontend/src/instance/entity_graph.rs @@ -179,6 +179,7 @@ impl EntityGraphProviderImpl { entity_type, id_columns, id_qualifier: None, + suppressed_by_columns: vec![], descriptive_columns, scope_columns, }) @@ -323,6 +324,14 @@ impl EntityGraphProviderImpl { .qualified_by .clone() .filter(|c| schema.column_schema_by_name(c).is_some()); + // A column the table does not have suppresses nothing, and must + // not reach the derivation plan as an unresolvable reference. + let suppressed_by_columns = implicit + .suppressed_by + .iter() + .filter(|c| schema.column_schema_by_name(c).is_some()) + .cloned() + .collect(); declarations.push(EntityDeclaration { schema: table_info.schema_name.clone(), table: table_info.name.clone(), @@ -330,6 +339,7 @@ impl EntityGraphProviderImpl { entity_type: implicit.entity.clone(), id_columns: implicit.id.clone(), id_qualifier, + suppressed_by_columns, descriptive_columns, scope_columns: vec![], }); @@ -1027,6 +1037,14 @@ mod tests { "service.instance" ] ); + // A pod's container belongs to k8s.container; the generic type yields + // on those rows instead of doubling the node. + assert_eq!(declarations[0].entity_type, "container"); + assert_eq!( + declarations[0].suppressed_by_columns, + vec!["k8s.pod.uid"], + "the generic container must yield to k8s.container per row" + ); assert_eq!(declarations[1].id_columns, vec!["host.id"]); assert_eq!(declarations[1].descriptive_columns, vec!["host.name"]); assert_eq!(declarations[3].id_columns, vec!["job"]); @@ -1037,6 +1055,18 @@ mod tests { assert_eq!(declarations[4].id_columns, vec!["job", "instance"]); assert!(declarations[4].descriptive_columns.is_empty()); + // A deployment that never reports pods has no `k8s.pod.uid` column at + // all: the suppression drops out instead of reaching the derivation + // plan as an unresolvable column reference. + let no_k8s = prom_table_info( + "greptime_otel_resource_info", + &["job", "container.id"], + OTEL_STAMPS, + ); + let declarations = sorted_declarations(&no_k8s); + assert_eq!(declarations[0].entity_type, "container"); + assert!(declarations[0].suppressed_by_columns.is_empty()); + let partial = prom_table_info( "greptime_otel_resource_info", &["job", "service.name", "host.id"], diff --git a/src/operator/src/statement/semantic_graph.rs b/src/operator/src/statement/semantic_graph.rs index 86827cf8c7a..aae5530f181 100644 --- a/src/operator/src/statement/semantic_graph.rs +++ b/src/operator/src/statement/semantic_graph.rs @@ -61,7 +61,7 @@ use datafusion::dataframe::DataFrame; use datafusion::functions::{core as core_fns, datetime as datetime_fns, string as string_fns}; use datafusion::functions_nested::expr_fn::make_array; use datafusion_common::{Column, Result as DfResult, ScalarValue}; -use datafusion_expr::{Case, Expr, LogicalPlan, ScalarUDF, cast, ident, lit}; +use datafusion_expr::{Case, Expr, LogicalPlan, ScalarUDF, cast, ident, lit, not}; pub use relationships::{ CallsSource, CoDeclaredSource, DeclaredSource, RelationshipSources, build_relationships_plan, }; @@ -292,6 +292,11 @@ pub struct EntityDeclaration { /// carrying the parts separately (a trace table's `service.namespace`) /// yields the same id as one carrying them pre-composed (`job`). pub id_qualifier: Option, + /// Columns whose presence on a row suppresses this declaration for that + /// row, so a more specific entity type can own it (a pod's container is + /// the `k8s.container`, not a generic `container`). Empty for explicit + /// declarations: a user who declares a type means it unconditionally. + pub suppressed_by_columns: Vec, /// Descriptive columns snapshotted into the `descriptive` JSON (may be empty). pub descriptive_columns: Vec, /// Scope columns (namespace/environment). One column → scope verbatim; @@ -434,6 +439,20 @@ pub(crate) fn identifies(column: &str) -> Expr { .and(cast(ident(column), DataType::Utf8).not_eq(lit(""))) } +/// The row-level guard a declaration carries: every identity component present, +/// and no suppressing column present. Every branch that turns a declaration +/// into rows applies this, so the guard cannot drift between them. +pub(crate) fn declaration_predicate(declaration: &EntityDeclaration) -> Expr { + let mut predicate = lit(true); + for column in &declaration.id_columns { + predicate = predicate.and(identifies(column)); + } + for column in &declaration.suppressed_by_columns { + predicate = predicate.and(not(identifies(column))); + } + predicate +} + const ID_SEPARATOR: &str = ","; const ID_ESCAPE: &str = "\\"; /// Left unescaped: `/` is how Prometheus renders `job`. @@ -694,10 +713,7 @@ fn registry_source( // Keep this predicate per declaration so an absent identity for one // entity does not remove other entities on the row. - let valid = decl - .id_columns - .iter() - .fold(lit(true), |predicate, id| predicate.and(identifies(id))); + let valid = declaration_predicate(decl); rows.push(vec![ valid, @@ -889,6 +905,7 @@ mod tests { entity_type: entity_type.to_string(), id_columns: id_columns.iter().map(|s| s.to_string()).collect(), id_qualifier: None, + suppressed_by_columns: vec![], descriptive_columns: vec![], scope_columns: vec![], } @@ -1154,6 +1171,59 @@ mod tests { assert_eq!(ids, vec!["h2"]); } + #[tokio::test] + async fn registry_suppression_is_per_row() { + // One descriptor table holds both pod rows and bare-runtime rows, so a + // schema-level test could only keep or drop the whole table; the + // generic container entity must yield on exactly the pod rows. + let schema = Arc::new(Schema::new(vec![ + Field::new( + "ts", + DataType::Timestamp(TimeUnit::Millisecond, None), + false, + ), + Field::new("container_id", DataType::Utf8, false), + Field::new("pod_uid", DataType::Utf8, true), + ])); + let batch = RecordBatch::try_new( + schema.clone(), + vec![ + Arc::new(TimestampMillisecondArray::from(vec![1_000, 2_000, 3_000])) as ArrayRef, + Arc::new(StringArray::from(vec!["c-pod", "c-docker", "c-empty"])), + Arc::new(StringArray::from(vec![Some("uid-1"), None, Some("")])), + ], + ) + .unwrap(); + let ctx = SessionContext::new(); + ctx.register_table( + "descriptors", + Arc::new(MemTable::try_new(schema, vec![vec![batch]]).unwrap()), + ) + .unwrap(); + + let mut declaration = decl("container", &["container_id"]); + declaration.table = "descriptors".to_string(); + declaration.suppressed_by_columns = vec!["pod_uid".to_string()]; + let plan = build_registry_plan( + vec![RegistrySource { + declarations: vec![declaration], + scan: ctx.table("descriptors").await.unwrap(), + }], + &test_window(), + ) + .unwrap() + .unwrap(); + + let mut ids: Vec = collect(&ctx, plan) + .await + .iter() + .flat_map(|b| strings(b, 5)) + .collect(); + ids.sort(); + // An empty uid is no uid: it suppresses nothing. + assert_eq!(ids, vec!["c-docker", "c-empty"]); + } + #[tokio::test] async fn registry_expands_declarations_with_one_source_scan() { let ctx = metric_table_ctx(); diff --git a/src/operator/src/statement/semantic_graph/conventions.rs b/src/operator/src/statement/semantic_graph/conventions.rs index 9ec6f52e158..b664a8b4c90 100644 --- a/src/operator/src/statement/semantic_graph/conventions.rs +++ b/src/operator/src/statement/semantic_graph/conventions.rs @@ -57,6 +57,12 @@ pub struct ImplicitEntity { /// Skipped when the column is absent or empty. #[serde(default)] pub qualified_by: Option, + /// Columns whose presence on a row suppresses this declaration *for that + /// row*. The judgement has to be row-level: one descriptor table holds both + /// Kubernetes and bare-runtime rows, so a schema-level test cannot separate + /// them. + #[serde(default)] + pub suppressed_by: Vec, /// Descriptive label columns, filtered to those present (kube-state-metrics /// label sets vary across versions). #[serde(default)] @@ -243,6 +249,12 @@ fn validate(conventions: &Conventions) -> Result<(), String> { implicit.entity )); } + if implicit.suppressed_by.iter().any(String::is_empty) { + return Err(format!( + "entity `{}` of info metric `{table}` has an empty suppressed_by column", + implicit.entity + )); + } if implicit.qualified_by.as_ref().is_some_and(String::is_empty) { return Err(format!( "entity `{}` of info metric `{table}` has an empty qualified_by", @@ -317,6 +329,10 @@ mod tests { ) .contains("descriptive_rest") ); + assert!( + err("", "t: [{entity: host, id: [x], suppressed_by: ['']}]", "") + .contains("suppressed_by") + ); // the otel map runs through the same per-table validation assert!(err("", "", "t: [{entity: hosts, id: [x]}]").contains("unknown entity type")); // ids of a different arity for one type can never match each other diff --git a/src/operator/src/statement/semantic_graph/conventions.yaml b/src/operator/src/statement/semantic_graph/conventions.yaml index 808fe0f2658..92573c422f6 100644 --- a/src/operator/src/statement/semantic_graph/conventions.yaml +++ b/src/operator/src/statement/semantic_graph/conventions.yaml @@ -51,8 +51,13 @@ otlp_trace_entities: id: [resource_attributes.host.id] descriptive: - resource_attributes.host.name + # A container inside a pod is already the k8s.container entity, identified by + # [pod uid, container name]; a generic container beside it would be a second + # node for one physical container. The generic type therefore yields whenever + # the row carries a pod uid. - entity: container id: [resource_attributes.container.id] + suppressed_by: [resource_attributes.k8s.pod.uid] descriptive: - resource_attributes.container.name - entity: k8s.pod @@ -152,8 +157,12 @@ otel_info_metrics: id: [host.id] descriptive: - host.name + # Yields to k8s.container on pod rows, as on the trace side above. One + # descriptor table holds both pod rows and bare-runtime rows, so the test + # is per row, not per table. - entity: container id: [container.id] + suppressed_by: [k8s.pod.uid] descriptive: - container.name - entity: k8s.pod diff --git a/src/operator/src/statement/semantic_graph/relationships.rs b/src/operator/src/statement/semantic_graph/relationships.rs index 257c844a9a8..da59b87be3e 100644 --- a/src/operator/src/statement/semantic_graph/relationships.rs +++ b/src/operator/src/statement/semantic_graph/relationships.rs @@ -41,8 +41,8 @@ use crate::statement::semantic_graph::conventions::{ }; use crate::statement::semantic_graph::{ DECLARED_EDGE_IDENTITY_COLUMNS, EntityDeclaration, GraphQueryWindow, bin_interval, bin_ms, - conventions, entity_id_expr, identifies, interval, null_json, parse_json_expr, qcol, union_all, - unnest_rows, + conventions, declaration_predicate, entity_id_expr, interval, null_json, parse_json_expr, qcol, + union_all, unnest_rows, }; /// The embedded conventions, with a broken file surfaced as a plan error. @@ -188,11 +188,7 @@ fn co_declared_branch( .map(|(src, dst, rel_type, provenance)| { // Both endpoints must identify something on the row for the // row to witness the edge. - let valid = src - .id_columns - .iter() - .chain(&dst.id_columns) - .fold(lit(true), |predicate, id| predicate.and(identifies(id))); + let valid = declaration_predicate(src).and(declaration_predicate(dst)); vec![ valid, bin.clone(), @@ -484,7 +480,7 @@ fn virtual_attrs_expr() -> DfResult { /// side's timestamp and cannot prune this side's scan on their own). fn span_predicate(service: &EntityDeclaration, window: &GraphQueryWindow, strict: bool) -> Expr { let ts = ident(TRACE_TIMESTAMP_COLUMN); - let mut predicate = if strict { + let window_predicate = if strict { ts.clone() .gt_eq(window.source_start()) .and(ts.lt(window.source_end())) @@ -494,10 +490,7 @@ fn span_predicate(service: &EntityDeclaration, window: &GraphQueryWindow, strict .and(ts.lt(window.source_end() + interval(CHILD_SPAN_LATE_NANOS))) }; // An absent identity component identifies nothing, on either endpoint. - for id in &service.id_columns { - predicate = predicate.and(identifies(id)); - } - predicate + window_predicate.and(declaration_predicate(service)) } /// One trace table's client spans, normalized to @@ -878,6 +871,7 @@ mod tests { entity_type: "service".to_string(), id_columns: id_columns.iter().map(|s| s.to_string()).collect(), id_qualifier: None, + suppressed_by_columns: vec![], descriptive_columns: vec![], scope_columns: vec![], } @@ -1331,6 +1325,7 @@ mod tests { entity_type: entity_type.to_string(), id_columns: id_columns.iter().map(|s| s.to_string()).collect(), id_qualifier: None, + suppressed_by_columns: vec![], descriptive_columns: vec![], scope_columns: vec![], } diff --git a/tests/cases/standalone/common/system/semantic_graph.result b/tests/cases/standalone/common/system/semantic_graph.result index f8894319842..5697dfc04eb 100644 --- a/tests/cases/standalone/common/system/semantic_graph.result +++ b/tests/cases/standalone/common/system/semantic_graph.result @@ -633,7 +633,9 @@ Affected Rows: 0 -- the stable ids only, so rows with an empty host.id / container.id link no -- infrastructure, and a row without an instance value declares no -- service.instance. The same table name stamped source=prometheus is not --- whitelisted. +-- whitelisted. The pod row shows the row-level suppression: a container inside +-- a pod is the k8s.container entity, so the generic container (and every edge +-- it would carry) yields on that row while the bare-runtime row keeps its own. create table greptime_otel_resource_info ( greptime_timestamp timestamp(3) time index, job string, @@ -644,9 +646,12 @@ create table greptime_otel_resource_info ( "host.name" string, "container.id" string, "container.name" string, + "k8s.pod.uid" string, + "k8s.pod.name" string, greptime_value double, primary key (job, instance, "service.name", "service.namespace", - "host.id", "host.name", "container.id", "container.name") + "host.id", "host.name", "container.id", "container.name", + "k8s.pod.uid", "k8s.pod.name") ) with ( 'greptime.semantic.signal_type' = 'metric', 'greptime.semantic.source' = 'opentelemetry', @@ -656,11 +661,12 @@ create table greptime_otel_resource_info ( Affected Rows: 0 insert into greptime_otel_resource_info values - (now(), 'shop/api', 'inst-1', 'api', 'shop', 'h-1', 'node-a', 'c-1', 'api-ctr', 1), - (now(), 'shop/api', 'inst-2', 'api', 'shop', '', 'laptop', '', '', 1), - (now(), 'worker', '', 'worker', '', 'h-1', 'node-a', '', '', 1); + (now(), 'shop/api', 'inst-1', 'api', 'shop', 'h-1', 'node-a', 'c-1', 'api-ctr', '', '', 1), + (now(), 'shop/api', 'inst-2', 'api', 'shop', '', 'laptop', '', '', '', '', 1), + (now(), 'worker', '', 'worker', '', 'h-1', 'node-a', '', '', '', '', 1), + (now(), 'shop/api', 'inst-3', 'api', 'shop', 'h-2', 'node-b', 'c-2', 'api-ctr', 'uid-1', 'api-pod', 1); -Affected Rows: 3 +Affected Rows: 4 -- SQLNESS PROTOCOL MYSQL select entity_type, entity_id, source_tables @@ -672,10 +678,13 @@ order by entity_type, entity_id, source_tables; +------------------+-----------------+----------------------------------------+ | container | c-1 | ["public.greptime_otel_resource_info"] | | host | h-1 | ["public.greptime_otel_resource_info"] | +| host | h-2 | ["public.greptime_otel_resource_info"] | +| k8s.pod | uid-1 | ["public.greptime_otel_resource_info"] | | service | shop/api | ["public.greptime_otel_resource_info"] | | service | worker | ["public.greptime_otel_resource_info"] | | service.instance | shop/api,inst-1 | ["public.greptime_otel_resource_info"] | | service.instance | shop/api,inst-2 | ["public.greptime_otel_resource_info"] | +| service.instance | shop/api,inst-3 | ["public.greptime_otel_resource_info"] | +------------------+-----------------+----------------------------------------+ -- SQLNESS PROTOCOL MYSQL @@ -688,9 +697,12 @@ order by rel_type, src_id, dst_id; +------------------+-----------------+-----------+----------+----------+------------+ | service.instance | shop/api,inst-1 | service | shop/api | part_of | attribute | | service.instance | shop/api,inst-2 | service | shop/api | part_of | attribute | +| service.instance | shop/api,inst-3 | service | shop/api | part_of | attribute | | container | c-1 | host | h-1 | runs_on | attribute | | service.instance | shop/api,inst-1 | container | c-1 | runs_on | attribute | | service.instance | shop/api,inst-1 | host | h-1 | runs_on | attribute | +| service.instance | shop/api,inst-3 | host | h-2 | runs_on | attribute | +| service.instance | shop/api,inst-3 | k8s.pod | uid-1 | runs_on | attribute | +------------------+-----------------+-----------+----------+----------+------------+ drop table greptime_otel_resource_info; diff --git a/tests/cases/standalone/common/system/semantic_graph.sql b/tests/cases/standalone/common/system/semantic_graph.sql index 60d95630d91..ff8a055ac1b 100644 --- a/tests/cases/standalone/common/system/semantic_graph.sql +++ b/tests/cases/standalone/common/system/semantic_graph.sql @@ -394,7 +394,9 @@ drop table http_requests_total; -- the stable ids only, so rows with an empty host.id / container.id link no -- infrastructure, and a row without an instance value declares no -- service.instance. The same table name stamped source=prometheus is not --- whitelisted. +-- whitelisted. The pod row shows the row-level suppression: a container inside +-- a pod is the k8s.container entity, so the generic container (and every edge +-- it would carry) yields on that row while the bare-runtime row keeps its own. create table greptime_otel_resource_info ( greptime_timestamp timestamp(3) time index, job string, @@ -405,9 +407,12 @@ create table greptime_otel_resource_info ( "host.name" string, "container.id" string, "container.name" string, + "k8s.pod.uid" string, + "k8s.pod.name" string, greptime_value double, primary key (job, instance, "service.name", "service.namespace", - "host.id", "host.name", "container.id", "container.name") + "host.id", "host.name", "container.id", "container.name", + "k8s.pod.uid", "k8s.pod.name") ) with ( 'greptime.semantic.signal_type' = 'metric', 'greptime.semantic.source' = 'opentelemetry', @@ -415,9 +420,10 @@ create table greptime_otel_resource_info ( ); insert into greptime_otel_resource_info values - (now(), 'shop/api', 'inst-1', 'api', 'shop', 'h-1', 'node-a', 'c-1', 'api-ctr', 1), - (now(), 'shop/api', 'inst-2', 'api', 'shop', '', 'laptop', '', '', 1), - (now(), 'worker', '', 'worker', '', 'h-1', 'node-a', '', '', 1); + (now(), 'shop/api', 'inst-1', 'api', 'shop', 'h-1', 'node-a', 'c-1', 'api-ctr', '', '', 1), + (now(), 'shop/api', 'inst-2', 'api', 'shop', '', 'laptop', '', '', '', '', 1), + (now(), 'worker', '', 'worker', '', 'h-1', 'node-a', '', '', '', '', 1), + (now(), 'shop/api', 'inst-3', 'api', 'shop', 'h-2', 'node-b', 'c-2', 'api-ctr', 'uid-1', 'api-pod', 1); -- SQLNESS PROTOCOL MYSQL select entity_type, entity_id, source_tables