doc: add monitoring and logging api doc

Signed-off-by: Nhuanggze <loganhuang@yunify.com>

pkg/models/log/types.go

@@ -48,6 +48,6 @@ type FluentbitFiltersResult struct {
 }
 
 type FluentbitOutputsResult struct {
-	Status  int               `json:"status"`
-	Outputs []fb.OutputPlugin `json:"outputs,omitempty"`
+	Status  int               `json:"status" description:"response status"`
+	Outputs []fb.OutputPlugin `json:"outputs,omitempty" description:"array of fluent bit output plugins"`
 }

pkg/models/metrics/metrics.go

@@ -47,19 +47,19 @@ const (
 )
 
 type FormatedLevelMetric struct {
-	MetricsLevel string           `json:"metrics_level"`
-	Results      []FormatedMetric `json:"results"`
+	MetricsLevel string           `json:"metrics_level" description:"metrics level, eg. cluster"`
+	Results      []FormatedMetric `json:"results" description:"actual array of results"`
 }
 
 type FormatedMetric struct {
-	MetricName string             `json:"metric_name,omitempty"`
-	Status     string             `json:"status"`
-	Data       FormatedMetricData `json:"data,omitempty"`
+	MetricName string             `json:"metric_name,omitempty" description:"metrics name, eg. scheduler_up_sum"`
+	Status     string             `json:"status" description:"result status, one of error, success"`
+	Data       FormatedMetricData `json:"data,omitempty" description:"actual metrics result"`
 }
 
 type FormatedMetricData struct {
-	Result     []map[string]interface{} `json:"result"`
-	ResultType string                   `json:"resultType"`
+	Result     []map[string]interface{} `json:"result" description:"result presenting metric labels, a series of time points and their instant values"`
+	ResultType string                   `json:"resultType" description:"result type, one of matrix, vector"`
 }
 
 type MetricResultValues []MetricResultValue

pkg/simple/client/elasticsearch/esclient.go

@@ -286,49 +286,49 @@ func createQueryRequest(param QueryParameters) (int, []byte, error) {
 }
 
 type Response struct {
-	Status       int             `json:"status"`
-	Workspace    string          `json:"workspace,omitempty"`
-	Shards       Shards          `json:"_shards"`
-	Hits         Hits            `json:"hits"`
-	Aggregations json.RawMessage `json:"aggregations"`
+	Status       int             `json:"status" description:"query status"`
+	Workspace    string          `json:"workspace,omitempty" description:"workspace the query was performed against"`
+	Shards       Shards          `json:"_shards" description:"tells shard information"`
+	Hits         Hits            `json:"hits" description:"search results"`
+	Aggregations json.RawMessage `json:"aggregations" description:"aggregation results"`
 }
 
 type Shards struct {
-	Total      int64 `json:"total"`
-	Successful int64 `json:"successful"`
-	Skipped    int64 `json:"skipped"`
-	Failed     int64 `json:"failed"`
+	Total      int64 `json:"total" description:"tells how many shards were searched"`
+	Successful int64 `json:"successful" description:"count of the successful searched shards"`
+	Skipped    int64 `json:"skipped" description:"count of the skipped searched shards"`
+	Failed     int64 `json:"failed" description:"count of the failed searched shards"`
 }
 
 type Hits struct {
-	Total int64 `json:"total"`
-	Hits  []Hit `json:"hits"`
+	Total int64 `json:"total" description:"total number of documents matching our search criteria"`
+	Hits  []Hit `json:"hits" description:"actual array of search results"`
 }
 
 type Hit struct {
-	Source    Source    `json:"_source"`
-	HighLight HighLight `json:"highlight"`
-	Sort      []int64   `json:"sort"`
+	Source    Source    `json:"_source" description:"search result item"`
+	HighLight HighLight `json:"highlight" description:"highlighted log fragment"`
+	Sort      []int64   `json:"sort" description:"sort key for results"`
 }
 
 type Source struct {
-	Log        string     `json:"log"`
-	Time       string     `json:"time"`
-	Kubernetes Kubernetes `json:"kubernetes"`
+	Log        string     `json:"log" description:"the log message"`
+	Time       string     `json:"time" description:"log timestamp"`
+	Kubernetes Kubernetes `json:"kubernetes" description:"kubernetes addon information on the log"`
 }
 
 type Kubernetes struct {
-	Namespace string `json:"namespace_name"`
-	Pod       string `json:"pod_name"`
-	Container string `json:"container_name"`
-	Host      string `json:"host"`
+	Namespace string `json:"namespace_name" description:"the namespace the log is from"`
+	Pod       string `json:"pod_name" description:"the pod the log is from"`
+	Container string `json:"container_name" description:"the container the log is from"`
+	Host      string `json:"host" description:"the node the log if from"`
 }
 
 type HighLight struct {
-	LogHighLights       []string `json:"log,omitempty"`
-	NamespaceHighLights []string `json:"kubernetes.namespace_name.keyword,omitempty"`
-	PodHighLights       []string `json:"kubernetes.pod_name.keyword,omitempty"`
-	ContainerHighLights []string `json:"kubernetes.container_name.keyword,omitempty"`
+	LogHighLights       []string `json:"log,omitempty" description:"log messages to highlight"`
+	NamespaceHighLights []string `json:"kubernetes.namespace_name.keyword,omitempty" description:"namespaces to highlight"`
+	PodHighLights       []string `json:"kubernetes.pod_name.keyword,omitempty" description:"pods to highlight"`
+	ContainerHighLights []string `json:"kubernetes.container_name.keyword,omitempty" description:"containers to highlight"`
 }
 
 type LogRecord struct {

pkg/simple/client/fluentbit/fluentbitcrdclient.go

@@ -64,24 +64,24 @@ type FluentBitStatus struct {
 
 // Plugin struct for fluent-bit plugins
 type Plugin struct {
-	Type       string      `json:"type"`
-	Name       string      `json:"name"`
-	Parameters []Parameter `json:"parameters"`
+	Type       string      `json:"type" description:"output plugin type, eg. fluentbit-output-es"`
+	Name       string      `json:"name" description:"output plugin name, eg. fluentbit-output-es"`
+	Parameters []Parameter `json:"parameters" description:"output plugin configuration parameters"`
 }
 
 // Fluent-bit output plugins
 type OutputPlugin struct {
 	Plugin
-	Id         string    `json:"id"`
-	Enable     bool      `json:"enable"`
-	Updatetime time.Time `json:"updatetime,omitempty"`
+	Id         string    `json:"id,omitempty" description:"output plugin uuid"`
+	Enable     bool      `json:"enable" description:"current output plugin status, one of true, false"`
+	Updatetime time.Time `json:"updatetime,omitempty" description:"last updatetime of the output plugin"`
 }
 
 // Parameter generic parameter type to handle values from different sources
 type Parameter struct {
-	Name      string     `json:"name"`
+	Name      string     `json:"name" description:"configuration parameter key, eg. Name. refer to fluent bit official doc for more information."`
 	ValueFrom *ValueFrom `json:"valueFrom,omitempty"`
-	Value     string     `json:"value"`
+	Value     string     `json:"value" description:"configuration parameter value, eg. es. refer to fluent bit official doc for more information."`
 }
 
 // ValueFrom generic type to determine value origin