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