docs: update accesslog design doc (#1449)

* docs: update accesslog design doc Signed-off-by: hejianpeng <hejianpeng2@huawei.com>
envoyproxy · May 26, 2023 · 56edaba · 56edaba
1 parent 1b565db
commit 56edaba
Showing 1 changed file with 57 additions and 48 deletions.
diff --git a/docs/latest/design/accesslogging.md b/docs/latest/design/accesslogging.md
@@ -47,23 +47,26 @@ const (
 	// TODO: support format type "mix" in the future.
 )
 
+// ProxyAccessLoggingFormat defines the format of access logging.
+// +union
 type ProxyAccessLoggingFormat struct {
 	// Type defines the type of access logging format.
 	// +kubebuilder:validation:Enum=Text;JSON
+	// +unionDiscriminator
 	Type ProxyAccessLoggingFormatType `json:"type,omitempty"`
 	// Text defines the text access logging format, following Envoy access logging formatting,
 	// empty value results in proxy's default access log format.
-	// It's required when the format type is "text".
+	// It's required when the format type is "Text".
 	// Envoy [command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) may be used in the format.
 	// The [format string documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format-strings) provides more information.
 	// +optional
 	Text *string `json:"text,omitempty"`
-	// Fields is additional attributes that describe the specific event occurrence.
+	// JSON is additional attributes that describe the specific event occurrence.
 	// Structured format for the envoy access logs. Envoy [command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators)
-	// can be used as values for fields within the Struct.
-	// It's required when the format type is "json".
+	// can be used as values for json within the Struct.
+	// It's required when the format type is "JSON".
 	// +optional
-	Fields map[string]string `json:"fields,omitempty"`
+	JSON map[string]string `json:"json,omitempty"`
 }
 
 type ProxyAccessLoggingSinkType string
@@ -72,19 +75,19 @@ const (
 	// ProxyAccessLoggingSinkTypeFile defines the file access logging sink.
 	ProxyAccessLoggingSinkTypeFile ProxyAccessLoggingSinkType = "File"
 	// ProxyAccessLoggingSinkTypeOpenTelemetry defines the OpenTelemetry access logging sink.
-	ProxyAccessLoggingSinkTypeOpenTelemetry ProxyAccessLoggingSinkType = "Opentelemetry"
+	ProxyAccessLoggingSinkTypeOpenTelemetry ProxyAccessLoggingSinkType = "OpenTelemetry"
 )
 
 type ProxyAccessLoggingSink struct {
 	// Type defines the type of access logging sink.
-	// +kubebuilder:validation:Enum=file;opentelemetry
+	// +kubebuilder:validation:Enum=File;OpenTelemetry
 	Type ProxyAccessLoggingSinkType `json:"type,omitempty"`
 	// File defines the file access logging sink.
 	// +optional
 	File *FileEnvoyProxyAccessLogging `json:"file,omitempty"`
 	// OpenTelemetry defines the OpenTelemetry access logging sink.
 	// +optional
-	OpenTelemetry *OpenTelemetryEnvoyProxyAccessLogging `json:"opentelemetry,omitempty"`
+	OpenTelemetry *OpenTelemetryEnvoyProxyAccessLogging `json:"openTelemetry,omitempty"`
 }
 
 type FileEnvoyProxyAccessLogging struct {
@@ -123,14 +126,15 @@ metadata:
   name: text-access-logging
 spec:
   accessLoggings:
-  - format:
-      type: text
-      text: |
-		[%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%" %RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% "%REQ(X-FORWARDED-FOR)%" "%REQ(USER-AGENT)%" "%REQ(X-REQUEST-ID)%" "%REQ(:AUTHORITY)%" "%UPSTREAM_HOST%"
-	sinks:
-	- type: "file"
-      file:
-	    path: /dev/stdout
+    - format:
+        type: text
+        text: |
+          [%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%" %RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% "%REQ(X-FORWARDED-FOR)%" "%REQ(USER-AGENT)%" "%REQ(X-REQUEST-ID)%" "%REQ(:AUTHORITY)%" "%UPSTREAM_HOST%"
+      sinks:
+        - type: "file"
+          file:
+            path: /dev/stdout
+
 ```
 
 1. The following is an example with json format access log.
@@ -142,15 +146,16 @@ metadata:
   name: json-access-logging
 spec:
   accessLoggings:
-  - format:
-      type: text
-      fields:
-        status: "%RESPONSE_CODE%"
-        message: "%LOCAL_REPLY_BODY%"
-	sinks:
-	- type: "file"
-	  file:
-	    path: /dev/stdout
+    - format:
+        type: text
+        json:
+          status: "%RESPONSE_CODE%"
+          message: "%LOCAL_REPLY_BODY%"
+      sinks:
+        - type: "file"
+          file:
+            path: /dev/stdout
+
 ```
 
 1. The following is an example with OpenTelemetry format access log.
@@ -161,16 +166,18 @@ kind: EnvoyProxy
 metadata:
   name: otel-access-logging
 spec:
-  - format:
-      type: text
-      text: |
-		[%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%" %RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% "%REQ(X-FORWARDED-FOR)%" "%REQ(USER-AGENT)%" "%REQ(X-REQUEST-ID)%" "%REQ(:AUTHORITY)%" "%UPSTREAM_HOST%"
-	sinks:
-	- type: "opentelemetry"
-      opentelemetry:
-	    address: otel-collector.monitoring.svc.cluster.local:4317
-		resources:
-          k8s.cluster.name: "cluster-1"
+  accessLoggings:
+    - format:
+        type: text
+        text: |
+          [%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%" %RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% "%REQ(X-FORWARDED-FOR)%" "%REQ(USER-AGENT)%" "%REQ(X-REQUEST-ID)%" "%REQ(:AUTHORITY)%" "%UPSTREAM_HOST%"
+      sinks:
+        - type: "opentelemetry"
+          opentelemetry:
+            address: otel-collector.monitoring.svc.cluster.local:4317
+          resources:
+            k8s.cluster.name: "cluster-1"
+
 ```
 
 1. The following is an example of sending same format to different sinks.
@@ -181,17 +188,19 @@ kind: EnvoyProxy
 metadata:
   name: multi-providers
 spec:
-  - format:
-      type: text
-      text: |
-		[%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%" %RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% "%REQ(X-FORWARDED-FOR)%" "%REQ(USER-AGENT)%" "%REQ(X-REQUEST-ID)%" "%REQ(:AUTHORITY)%" "%UPSTREAM_HOST%"
-	sinks:
-	- type: "file"
-      file:
-	    path: /dev/stdout
-    - type: "opentelemetry"
-      opentelemetry:
-	    address: otel-collector.monitoring.svc.cluster.local:4317
-		resources:
-          k8s.cluster.name: "cluster-1"
+  accessLoggings:
+    - format:
+        type: text
+        text: |
+          [%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%" %RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% "%REQ(X-FORWARDED-FOR)%" "%REQ(USER-AGENT)%" "%REQ(X-REQUEST-ID)%" "%REQ(:AUTHORITY)%" "%UPSTREAM_HOST%"
+      sinks:
+        - type: "file"
+          file:
+            path: /dev/stdout
+        - type: "opentelemetry"
+          opentelemetry:
+            address: otel-collector.monitoring.svc.cluster.local:4317
+            resources:
+              k8s.cluster.name: "cluster-1"
+
 ```