Update tracing strategy types; fix outdated proposal

Author: sjberman

apis/v1alpha1/observabilitypolicy_types.go

@@ -50,9 +50,13 @@ type ObservabilityPolicySpec struct {
 }
 
 // Tracing allows for enabling and configuring OpenTelemetry tracing.
+//
+// +kubebuilder:validation:XValidation:message="ratio can only be specified if strategy is of type ratio",rule="!(has(self.ratio) && self.strategy != 'ratio')"
+//
+//nolint:lll
 type Tracing struct {
-	// Enable defines if tracing is enabled, disabled, or parent-based.
-	Enable TraceType `json:"enable"`
+	// Strategy defines if tracing is ratio-based or parent-based.
+	Strategy TraceStrategy `json:"strategy"`
 
 	// Ratio is the percentage of traffic that should be sampled. Integer from 0 to 100.
 	// By default, 100% of http requests are traced. Not applicable for parent-based tracing.
@@ -71,6 +75,7 @@ type Tracing struct {
 	// SpanName defines the name of the Otel span. By default is the name of the location for a request.
 	// If specified, applies to all locations that are created for a route.
 	// Format: must have all '"' escaped and must not contain any '$' or end with an unescaped '\'
+	// Examples of invalid names: some-$value, quoted-"value"-name, unescaped\
 	//
 	// +optional
 	// +kubebuilder:validation:MinLength=1
@@ -87,20 +92,17 @@ type Tracing struct {
 	SpanAttributes []SpanAttribute `json:"spanAttributes,omitempty"`
 }
 
-// TraceType defines if tracing is enabled.
+// TraceStrategy defines the tracing strategy.
 //
-// +kubebuilder:validation:Enum=on;off;parent
-type TraceType string
+// +kubebuilder:validation:Enum=ratio;parent
+type TraceStrategy string
 
 const (
-	// TraceTypeOn enables tracing.
-	TraceTypeOn TraceType = "on"
-
-	// TraceTypeOff disables tracing.
-	TraceTypeOff TraceType = "off"
+	// TraceStrategyOn enables ratio-based tracing, defaulting to 100% sampling rate.
+	TraceStrategyRatio TraceStrategy = "ratio"
 
-	// TraceTypeParent enables tracing and only records spans if the parent span was sampled.
-	TraceTypeParent TraceType = "parent"
+	// TraceStrategyParent enables tracing and only records spans if the parent span was sampled.
+	TraceStrategyParent TraceStrategy = "parent"
 )
 
 // TraceContext specifies how to propagate traceparent/tracestate headers.

config/crd/bases/gateway.nginx.org_observabilitypolicies.yaml

@@ -102,14 +102,6 @@ spec:
                     - propagate
                     - ignore
                     type: string
-                  enable:
-                    description: Enable defines if tracing is enabled, disabled, or
-                      parent-based.
-                    enum:
-                    - "on"
-                    - "off"
-                    - parent
-                    type: string
                   ratio:
                     description: |-
                       Ratio is the percentage of traffic that should be sampled. Integer from 0 to 100.
@@ -155,13 +147,23 @@ spec:
                       SpanName defines the name of the Otel span. By default is the name of the location for a request.
                       If specified, applies to all locations that are created for a route.
                       Format: must have all '"' escaped and must not contain any '$' or end with an unescaped '\'
+                      Examples of invalid names: some-$value, quoted-"value"-name, unescaped\
                     maxLength: 255
                     minLength: 1
                     pattern: ^([^"$\\]|\\[^$])*$
                     type: string
+                  strategy:
+                    description: Strategy defines if tracing is ratio-based or parent-based.
+                    enum:
+                    - ratio
+                    - parent
+                    type: string
                 required:
-                - enable
+                - strategy
                 type: object
+                x-kubernetes-validations:
+                - message: ratio can only be specified if strategy is of type ratio
+                  rule: '!(has(self.ratio) && self.strategy != ''ratio'')'
             required:
             - targetRef
             type: object

docs/proposals/observability.md

@@ -98,24 +98,21 @@ type Tracing struct {
     // SpanAttributes are custom key/value attributes that are added to each span.
     //
     // +optional
-    SpanAttributes map[string]string `json:"spanAttributes,omitempty"`
+    SpanAttributes []SpanAttribute `json:"spanAttributes,omitempty"`
 
-    // Enable defines if tracing is enabled, disabled, or parent-based.
-    Enable TraceType `json:"enable"`
+    // Strategy defines if tracing is ratio-based or parent-based.
+    Strategy TraceStrategy `json:"strategy"`
 }
 
-// TraceType defines if tracing is enabled.
-type TraceType string
+// TraceStrategy defines the tracing strategy.
+type TraceStrategy string
 
 const (
-    // TraceTypeOn enables tracing.
-    TraceTypeOn TraceType = "on"
+    // TraceStrategyOn enables ratio-based tracing, defaulting to 100% sampling rate.
+    TraceStrategyRatio TraceStrategy = "ratio"
 
-    // TraceTypeOff disables tracing.
-    TraceTypeOff TraceType = "off"
-
-    // TraceTypeParent enables tracing and only records spans if the parent span was sampled.
-    TraceTypeParent TraceType = "parent"
+    // TraceStrategyParent enables tracing and only records spans if the parent span was sampled.
+    TraceStrategyParent TraceStrategy = "parent"
 )
 
 // TraceContext specifies how to propagate traceparent/tracestate headers.
@@ -135,6 +132,15 @@ const (
     // TraceContextIgnore skips context headers processing.
     TraceContextIgnore TraceContext = "ignore"
 )
+
+// SpanAttribute is a key value pair to be added to a tracing span.
+type SpanAttribute struct {
+	// Key is the key for a span attribute.
+	Key string `json:"key"`
+
+	// Value is the value for a span attribute.
+	Value string `json:"value"`
+}
 ```
 
 ### YAML
@@ -152,15 +158,16 @@ spec:
     group: gateway.networking.k8s.io
     kind: HTTPRoute
     name: example-route
-    sectionName: example-section
   tracing:
+    strategy: ratio
     ratio: 10
     context: inject
     spanName: example-span
     spanAttributes:
-      attribute1: value1
-      attribute2: value2
-    enable: "on"
+    - key: attribute1
+      value: value1
+    - key: attribute2
+      value: value2
 status:
   ancestors:
     ancestorRef:
@@ -175,29 +182,6 @@ status:
         message: Policy is accepted
 ```
 
-and the HTTPRoute it is attached to:
-
-```yaml
-apiVersion: gateway.networking.k8s.io/v1
-kind: HTTPRoute
-metadata:
-  name: example-route
-spec:
-  gatewayClassName: nginx
-  listeners:
-  - name: example-section
-    port: 80
-    protocol: HTTP
-    hostname: "*.example.com"
-status:
-  conditions:
-  ...
-  - type: gateway.nginx.org/ObservabilityPolicyAffected # new condition
-    status: "True"
-    reason: PolicyAffected
-    message: Object affected by an ObservabilityPolicy.
-```
-
 ### Status
 
 #### CRD Label