HTTPLogger (Access logging)

apiVersion: core/v1
kind: HTTPLogger
metadata:
  name: "default"
  namespace: "default"
spec: {}

  1syntax = "proto3";
  2package core.v1;
  3
  4import "kernel/replacer.proto";
  5import "kernel/resource.proto";
  6
  7option go_package = "github.com/aileron-gateway/aileron-gateway/apis/core/v1";
  8
  9// HTTPLogger resource definition.
 10// apiVersion="core/v1", kind="HTTPLogger".
 11message HTTPLogger {
 12    string          APIVersion = 1 [json_name = "apiVersion"];
 13    string          Kind       = 2 [json_name = "kind"];
 14    kernel.Metadata Metadata   = 3 [json_name = "metadata"];
 15    HTTPLoggerSpec  Spec       = 4 [json_name = "spec"];
 16}
 17
 18// HTTPLoggerSpec is the specifications of the HTTPLogger object.
 19message HTTPLoggerSpec {
 20    // [OPTIONAL]
 21    // Logger is the reference to a Logger object.
 22    // Referred object must implement Logger interface.
 23    // Default Logger is used if not set.
 24    kernel.Reference Logger = 1 [json_name = "logger"];
 25
 26    // [OPTIONAL]
 27    // ErrorHandler is the reference to a ErrorHandler object.
 28    // Referred object must implement ErrorHandler interface.
 29    // Default error handler is used when not set.
 30    kernel.Reference ErrorHandler = 2 [json_name = "errorHandler"];
 31
 32    // [OPTIONAL]
 33    // Journal is the flag to log request and response bodies.
 34    // Note that not all bodies are logged by default.
 35    // Configure the target requests and responses to log
 36    // in the Request and Response field.
 37    // Default is [false].
 38    bool Journal = 3 [json_name = "journal"];
 39
 40    // [OPTIONAL]
 41    // TimeZone is the timezone of the access time timestamp.
 42    // For example, "UTC", "Local", "Asia/Tokyo".
 43    // See https://pkg.go.dev/time#LoadLocation for more details.
 44    // Default is ["Local"].
 45    string Timezone = 4 [json_name = "timezone"];
 46
 47    // [OPTIONAL]
 48    // TimeFormat is the format of the access time timestamp.
 49    // Check the following url for examples.
 50    // https://pkg.go.dev/time#pkg-constants
 51    // Default is ["2006-01-02 15:04:05.000"].
 52    string TimeFormat = 5 [json_name = "timeFormat"];
 53
 54    // [OPTIONAL]
 55    // Request is the logging configuration for requests.
 56    // Default values are used if not set.
 57    LoggingSpec Request = 6 [json_name = "request"];
 58
 59    // [OPTIONAL]
 60    // Response is the logging configuration for responses.
 61    // Default values are used if not set.
 62    LoggingSpec Response = 7 [json_name = "response"];
 63}
 64
 65message LoggingSpec {
 66    // [OPTIONAL]
 67    // Headers is the list of headers replacers.
 68    // Also, masking the header values can be configured in ths field.
 69    // "*" is the special name that represents all headers.
 70    // Set "*" to output all header values to log.
 71    // Note that the masking configuration for "*" is ignored.
 72    // Nothing is set by default.
 73    repeated LogHeaderSpec Headers = 1 [json_name = "headers"];
 74
 75    // [OPTIONAL]
 76    // Bodies is the list of body replacer.
 77    // Replacers can be used for masking, adding or removing content.
 78    // This field does not work when logging bodies to files.
 79    // Default is not set.
 80    repeated LogBodySpec Bodies = 2 [json_name = "bodies"];
 81
 82    // [Optional]
 83    // Queries is the list of query value replacers.
 84    // Replacers can be used for masking or removing query values.
 85    // All replacers are applied to the entire query string
 86    // with specified order.
 87    // If not set, query string is output as-is.
 88    // This field works only for request logs and not for response logs.
 89    // Default is not set.
 90    repeated kernel.ReplacerSpec Queries = 3 [json_name = "queries"];
 91
 92    // [OPTIONAL]
 93    // LogFormat is the customized log output format.
 94    // if not set, default formats determined by the logger is used.
 95    // Default is not set.
 96    string LogFormat = 4 [json_name = "logFormat"];
 97
 98    // [OPTIONAL]
 99    // BodyOutputPath is the body output directory path.
100    // If set, bodies that exceeds MaxContentLength and bodies with unknown size
101    // are logged to files in the specidied path.
102    // This feature of logging bodies to files is debugging use only
103    // because of the not enough implementation of error handling.
104    // To output all bodies to files, set MaxContentLength a negative value.
105    // Note that body replacers do not work for bodies output to files.
106    // This field is ignored when Journal mode is not enabled.
107    // Default is not set.
108    string BodyOutputPath = 5 [json_name = "bodyOutputPath"];
109
110    // [OPTIONAL]
111    // Base64 if enabled, encode body with base64 standard encoding.
112    // This field is ignored when output mode is not enabled or BodyOutputPath is set.
113    // Default is [false].
114    bool Base64 = 6 [json_name = "base64"];
115
116    // [OPTIONAL]
117    // MaxContentLength is the maximum content length in bytes to
118    // allow logging request and response bodies.
119    // Request and response bodies which exceeds this length are not logged.
120    // Requests and response bodies with unknown sizes are ignored and not logged.
121    // Streaming or HTTP2 requests and responses can have unknown sized body.
122    // Note that when bodies are logged, the entire body is temporarily load on memory.
123    // So do not set this value so large that can result in too much memory consumption.
124    // Use BodyOutputPath for logging large or streaming bodies.
125    // This field is ignored when Journal mode is not enabled.
126    // Default is [4096] or 4kiB.
127    int64 MaxContentLength = 7 [json_name = "maxContentLength"];
128
129    // [OPTIONAL]
130    // MIMEs is the list of mime types to log request and response bodies.
131    // When Journal mode is enabled, only requests and response bodies with
132    // listed mime types are logged.
133    // Mime types are evaluated with exact matching.
134    // So, list all mime types to log bodies.
135    // See MIME types at https://www.iana.org/assignments/media-types/media-types.xhtml.
136    // This field is ignored when Journal mode is not enabled.
137    // When not set, default value are used.
138    // Default values are
139    // ["application/json", "application/x-www-form-urlencoded", "application/xml",
140    // "application/soap+xml", "application/graphql+json",
141    // "text/plain", "text/html", "text/xml"].
142    repeated string MIMEs = 8 [json_name = "mimes"];
143}
144
145// LogValueSpec is the status of the LoggingMiddleware object.
146// Values are managed by the application and therefore should not be set by users.
147message LogHeaderSpec {
148    // [REQUIRED]
149    // Name is the HTTP header name.
150    // "*" is the special character to represent all header names.
151    string Name = 1 [json_name = "name"];
152
153    // [Optional]
154    // Replacers is the list of replace configurations.
155    // If not set, header values are output as is.
156    // Default is not set.
157    repeated kernel.ReplacerSpec Replacers = 2 [json_name = "replacers"];
158}
159
160// LogBodySpec is the HTTP body logging configuration.
161message LogBodySpec {
162    // [REQUIRED]
163    // Mime is the mime type string such as "application/json"
164    // that this configuration targets to.
165    // Default is not set.
166    string Mime = 1 [json_name = "mime"];
167
168    // [Optional]
169    // Replacers is the list of replace configurations.
170    // If not set, body is output as is.
171    // Default is not set.
172    repeated kernel.ReplacerSpec Replacers = 2 [json_name = "replacers"];
173
174    // [OPTIONAL]
175    // JSONFields is the list of json key names to be replaced.
176    // If set, replacers are applied to the obtained content.
177    // Default is not set.
178    repeated string JSONFields = 3 [json_name = "jsonFields"];
179}