From 648947ed7cd14bc58f2cb8655f40e2f121327393 Mon Sep 17 00:00:00 2001 From: Whitney Griffith Date: Wed, 15 Nov 2023 07:32:03 -0800 Subject: [PATCH] Update CEL documentation to capture type checking errors. (#2984) * Update CEL documentation to capture type checking errors. Signed-off-by: Whitney Griffith * address comments Signed-off-by: Whitney Griffith * accept rewording Signed-off-by: Whitney Griffith Co-authored-by: Craig Box * make gen Signed-off-by: Whitney Griffith --------- Signed-off-by: Whitney Griffith Co-authored-by: Craig Box --- .../stackdriver/config/v1alpha1/config.pb.go | 15 ++++++++++++++- .../stackdriver/config/v1alpha1/config.proto | 15 ++++++++++++++- telemetry/v1alpha1/telemetry.pb.go | 1 + telemetry/v1alpha1/telemetry.pb.html | 1 + telemetry/v1alpha1/telemetry.proto | 1 + 5 files changed, 31 insertions(+), 2 deletions(-) diff --git a/envoy/extensions/stackdriver/config/v1alpha1/config.pb.go b/envoy/extensions/stackdriver/config/v1alpha1/config.pb.go index 423c1063b83..8ced21cc457 100644 --- a/envoy/extensions/stackdriver/config/v1alpha1/config.pb.go +++ b/envoy/extensions/stackdriver/config/v1alpha1/config.pb.go @@ -231,7 +231,20 @@ type PluginConfig struct { AccessLogging PluginConfig_AccessLogging `protobuf:"varint,10,opt,name=access_logging,json=accessLogging,proto3,enum=stackdriver.config.v1alpha1.PluginConfig_AccessLogging" json:"access_logging,omitempty"` // CEL expression for filtering access logging. If the expression evaluates // to true, an access log entry will be generated. Otherwise, no access log - // entry will be generated. + // entry will be generated. If there are any type errors, the CEL expression + // is evaluated as false. More details on type checking can be found + // at https://kubernetes.io/docs/reference/using-api/cel/#type-checking. + // A common error is referring to a non-existent field in the log entry. + // It's crucial to note that in Envoy, the fields that appear in access log + // entries can vary. This variation is influenced by several factors, + // including the protocol in use (such as HTTP or TCP), the applied filters, + // and the specific configuration of the Envoy instance. Therefore, when + // using CEL expressions for filtering access logs, it's essential to ensure + // that the expressions accurately refer to existing fields in the log entry. + // The has() macro in CEL may be used in CEL expressions to check if a field + // is accessible before attempting to access the field's value. + // You can also quickly test CEL expressions at the CEL Playground + // at https://playcel.undistro.io/. // NOTE: Audit logs ignore configured filters. AccessLoggingFilterExpression string `protobuf:"bytes,17,opt,name=access_logging_filter_expression,json=accessLoggingFilterExpression,proto3" json:"access_logging_filter_expression,omitempty"` // (Optional) Collection of tag names and tag expressions to include in the diff --git a/envoy/extensions/stackdriver/config/v1alpha1/config.proto b/envoy/extensions/stackdriver/config/v1alpha1/config.proto index 9d25f322c16..103140e4e9e 100644 --- a/envoy/extensions/stackdriver/config/v1alpha1/config.proto +++ b/envoy/extensions/stackdriver/config/v1alpha1/config.proto @@ -127,7 +127,20 @@ message PluginConfig { // CEL expression for filtering access logging. If the expression evaluates // to true, an access log entry will be generated. Otherwise, no access log - // entry will be generated. + // entry will be generated. If there are any type errors, the CEL expression + // is evaluated as false. More details on type checking can be found + // at https://kubernetes.io/docs/reference/using-api/cel/#type-checking. + // A common error is referring to a non-existent field in the log entry. + // It's crucial to note that in Envoy, the fields that appear in access log + // entries can vary. This variation is influenced by several factors, + // including the protocol in use (such as HTTP or TCP), the applied filters, + // and the specific configuration of the Envoy instance. Therefore, when + // using CEL expressions for filtering access logs, it's essential to ensure + // that the expressions accurately refer to existing fields in the log entry. + // The has() macro in CEL may be used in CEL expressions to check if a field + // is accessible before attempting to access the field's value. + // You can also quickly test CEL expressions at the CEL Playground + // at https://playcel.undistro.io/. // NOTE: Audit logs ignore configured filters. string access_logging_filter_expression = 17; diff --git a/telemetry/v1alpha1/telemetry.pb.go b/telemetry/v1alpha1/telemetry.pb.go index 587d74c1e6f..f9215706eee 100644 --- a/telemetry/v1alpha1/telemetry.pb.go +++ b/telemetry/v1alpha1/telemetry.pb.go @@ -1620,6 +1620,7 @@ type AccessLogging_Filter struct { // // - `response.code >= 400` // - `connection.mtls && request.url_path.contains('v1beta3')` + // - `!has(request.useragent) || !(request.useragent.startsWith("Amazon-Route53-Health-Check-Service"))` Expression string `protobuf:"bytes,1,opt,name=expression,proto3" json:"expression,omitempty"` } diff --git a/telemetry/v1alpha1/telemetry.pb.html b/telemetry/v1alpha1/telemetry.pb.html index fed404f0e95..7d2779c59af 100644 --- a/telemetry/v1alpha1/telemetry.pb.html +++ b/telemetry/v1alpha1/telemetry.pb.html @@ -912,6 +912,7 @@

AccessLogging.Filter

  • response.code >= 400
  • connection.mtls && request.url_path.contains('v1beta3')
    • +
  • !has(request.useragent) || !(request.useragent.startsWith("Amazon-Route53-Health-Check-Service"))
diff --git a/telemetry/v1alpha1/telemetry.proto b/telemetry/v1alpha1/telemetry.proto index 6e1092ec6c7..75947e867bd 100644 --- a/telemetry/v1alpha1/telemetry.proto +++ b/telemetry/v1alpha1/telemetry.proto @@ -670,6 +670,7 @@ message AccessLogging { // // - `response.code >= 400` // - `connection.mtls && request.url_path.contains('v1beta3')` + // - `!has(request.useragent) || !(request.useragent.startsWith("Amazon-Route53-Health-Check-Service"))` string expression = 1; }