This is an automated email from the ASF dual-hosted git repository.
liujiapeng pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/skywalking-satellite.git
The following commit(s) were added to refs/heads/main by this push:
new ad503ba add plugin doc generator (#14)
ad503ba is described below
commit ad503ba8cfdc459f9c2624204c79c482abacf138
Author: Evan <[email protected]>
AuthorDate: Wed Jan 13 17:26:03 2021 +0800
add plugin doc generator (#14)
* add plugin doc generator
* add generate doc
* polish script
* polish script
* polish script
* polish script
* polish script
Co-authored-by: Evan <[email protected]>
---
.github/workflows/build-and-test.yaml | 4 +-
Makefile | 2 +
cmd/command.go | 19 +++--
cmd/main.go | 1 +
docs/plugin-description.md | 104 ++++++++++++++++++++++++
internal/pkg/plugin/registry.go | 10 +--
internal/satellite/tools/generate_plugin_doc.go | 89 ++++++++++++++++++++
plugins/fallbacker/timer/timer_fallbacker.go | 2 +-
plugins/queue/mmap/queue.go | 2 +-
9 files changed, 216 insertions(+), 17 deletions(-)
diff --git a/.github/workflows/build-and-test.yaml
b/.github/workflows/build-and-test.yaml
index edf6fc9..41823d3 100644
--- a/.github/workflows/build-and-test.yaml
+++ b/.github/workflows/build-and-test.yaml
@@ -47,8 +47,8 @@ jobs:
- name: Get dependencies
run: make deps
- - name: Check generate codes
- run: make gen && make check
+ - name: Check generate
+ run: make gen && make build && make check
- name: Lint
run: make lint
diff --git a/Makefile b/Makefile
index 097c632..95bf1a7 100644
--- a/Makefile
+++ b/Makefile
@@ -24,6 +24,7 @@ RELEASE_SRC = skywalking-satellite-$(VERSION)-src
OS = $(shell uname)
+SH = sh
GO = go
GIT = git
PROTOC = protoc
@@ -85,6 +86,7 @@ build: deps linux darwin
.PHONY: check
check:
$(MAKE) clean
+ $(OUT_DIR)/skywalking-satellite-latest-linux-amd64 docs
$(GO) mod tidy &> /dev/null
@if [ ! -z "`git status -s |grep -v 'go.mod\|go.sum'`" ]; then \
echo "Following files are not consistent with CI:"; \
diff --git a/cmd/command.go b/cmd/command.go
index 0fe3c18..e8c3f0b 100644
--- a/cmd/command.go
+++ b/cmd/command.go
@@ -22,6 +22,7 @@ import (
"github.com/apache/skywalking-satellite/internal/satellite/boot"
"github.com/apache/skywalking-satellite/internal/satellite/config"
+ "github.com/apache/skywalking-satellite/internal/satellite/tools"
)
var (
@@ -37,15 +38,17 @@ var (
},
},
Action: func(c *cli.Context) error {
-
- cfg := loadConfig(c)
+ configPath := c.String("config")
+ cfg := config.Load(configPath)
return boot.Start(cfg)
},
}
-)
-func loadConfig(c *cli.Context) *config.SatelliteConfig {
- configPath := c.String("config")
- cfg := config.Load(configPath)
- return cfg
-}
+ cmdDocs = cli.Command{
+ Name: "docs",
+ Usage: "generate satellite plugin docs",
+ Action: func(c *cli.Context) error {
+ return tools.GeneratePluginDoc()
+ },
+ }
+)
diff --git a/cmd/main.go b/cmd/main.go
index 0b51788..cbe819c 100644
--- a/cmd/main.go
+++ b/cmd/main.go
@@ -36,6 +36,7 @@ func main() {
app.Description = "A lightweight collector/sidecar could be deployed
closing to the target monitored system, to collect metrics, traces, and logs."
app.Commands = []*cli.Command{
&cmdStart,
+ &cmdDocs,
}
app.Action = cli.ShowAppHelp
_ = app.Run(os.Args)
diff --git a/docs/plugin-description.md b/docs/plugin-description.md
new file mode 100755
index 0000000..b5c977b
--- /dev/null
+++ b/docs/plugin-description.md
@@ -0,0 +1,104 @@
+# api.Client
+## kafka-client
+### description
+```this is a sharing client to delivery the data to Kafka.```
+### defaultConfig
+```
+# The Kafka broker addresses (default localhost:9092). Multiple values are
separated by commas.
+brokers: localhost:9092
+
+# The Kakfa version should follow this pattern, which is
major_minor_veryMinor_patch (default 1.0.0.0).
+version: 1.0.0.0
+
+# The TLS switch (default false).
+enable_TLS: false
+
+# The file path of client.pem. The config only works when opening the TLS
switch.
+client_pem_path: ""
+
+# The file path of client.key. The config only works when opening the TLS
switch.
+client_key_path: ""
+
+# The file path oca.pem. The config only works when opening the TLS switch.
+ca_pem_path: ""
+
+# 0 means NoResponse, 1 means WaitForLocal and -1 means WaitForAll (default 1).
+required_acks: 1
+
+# The producer max retry times (default 3).
+producer_max_retry: 3
+
+# The meta max retry times (default 3).
+meta_max_retry: 3
+
+# How long to wait for the cluster to settle between retries (default 100ms).
Time unit is ms.
+retry_backoff: 100
+
+# The max message bytes.
+max_message_bytes: 1000000
+
+# If enabled, the producer will ensure that exactly one copy of each message
is written (default false).
+idempotent_writes: false
+
+# A user-provided string sent with every request to the brokers for logging,
debugging, and auditing purposes (default Satellite).
+client_id: Satellite
+
+# Compression codec represents the various compression codecs recognized by
Kafka in messages. 0 : None, 1 : Gzip, 2 : Snappy, 3 : LZ4, 4 : ZSTD
+compression_codec: 0
+
+# How frequently to refresh the cluster metadata in the background. Defaults
to 10 minutes. The unit is minute.
+# refresh_period: 10
+
+# InsecureSkipVerify controls whether a client verifies the server's
certificate chain and host name.
+insecure_skip_verify: true
+```
+# api.Fallbacker
+## timer-fallbacker
+### description
+```this is a timer fallback trigger when forward fails.```
+### defaultConfig
+```
+max_times: 3
+latency_factor: 2000
+```
+# api.Forwarder
+## log-kafka-forwarder
+### description
+```this is a synchronization Kafka log forwarder.```
+### defaultConfig
+```
+# The remote topic.
+topic: "log-topic"
+```
+# api.Queue
+## mmap-queue
+### description
+```this is a memory mapped queue to provide the persistent storage.```
+### defaultConfig
+```
+# The size of each segment. Default value is 128K. The unit is Byte.
+segment_size: 131072
+# The max num of segments in memory. Default value is 10.
+max_in_mem_segments: 10
+# The capacity of Queue = segment_size * queue_capacity_segments.
+queue_capacity_segments: 4000
+# The period flush time. The unit is ms. Default value is 1 second.
+flush_period: 1000
+# The max number in one flush time. Default value is 10000.
+flush_ceiling_num: 10000
+# Contains all files in the queue.
+queue_dir: satellite-mmap-queue
+# The max size of the input event. Default value is 20k.
+max_event_size: 20480
+```
+# api.Server
+## prometheus-server
+### description
+```this is a prometheus server to export the metrics in Satellite.```
+### defaultConfig
+```
+# The prometheus server address.
+address: ":9299"
+# The prometheus server metrics endpoint.
+endpoint: "/metrics"
+```
diff --git a/internal/pkg/plugin/registry.go b/internal/pkg/plugin/registry.go
index edd6d11..cd6ffc9 100644
--- a/internal/pkg/plugin/registry.go
+++ b/internal/pkg/plugin/registry.go
@@ -30,16 +30,16 @@ import (
// the global plugin registry
var (
- reg map[reflect.Type]map[string]reflect.Value
+ Reg map[reflect.Type]map[string]reflect.Value
)
func init() {
- reg = make(map[reflect.Type]map[string]reflect.Value)
+ Reg = make(map[reflect.Type]map[string]reflect.Value)
}
// RegisterPluginCategory register the RegInfo to the global type registry.
func RegisterPluginCategory(pluginType reflect.Type) {
- reg[pluginType] = map[string]reflect.Value{}
+ Reg[pluginType] = map[string]reflect.Value{}
}
// RegisterPlugin registers the pluginType as plugin.
@@ -47,7 +47,7 @@ func RegisterPluginCategory(pluginType reflect.Type) {
func RegisterPlugin(plugin Plugin) {
v := reflect.ValueOf(plugin)
success := false
- for pCategory, pReg := range reg {
+ for pCategory, pReg := range Reg {
if v.Type().Implements(pCategory) {
pReg[plugin.Name()] = v
log.Logger.Infof("register %s %s successfully",
plugin.Name(), v.Type().String())
@@ -62,7 +62,7 @@ func RegisterPlugin(plugin Plugin) {
// Get an initialized specific plugin according to the pluginCategory and
config.
func Get(category reflect.Type, cfg Config) Plugin {
pluginName := nameFinder(cfg)
- value, ok := reg[category][pluginName]
+ value, ok := Reg[category][pluginName]
if !ok {
panic(fmt.Errorf("cannot find %s plugin, and the category of
plugin is %s", pluginName, category))
}
diff --git a/internal/satellite/tools/generate_plugin_doc.go
b/internal/satellite/tools/generate_plugin_doc.go
new file mode 100644
index 0000000..14ca5ad
--- /dev/null
+++ b/internal/satellite/tools/generate_plugin_doc.go
@@ -0,0 +1,89 @@
+// Licensed to Apache Software Foundation (ASF) under one or more contributor
+// license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright
+// ownership. Apache Software Foundation (ASF) licenses this file to you under
+// the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package tools
+
+import (
+ "fmt"
+ "io/ioutil"
+ "os"
+ "reflect"
+ "sort"
+ "strings"
+
+ "github.com/apache/skywalking-satellite/internal/pkg/log"
+ "github.com/apache/skywalking-satellite/internal/pkg/plugin"
+ "github.com/apache/skywalking-satellite/plugins"
+)
+
+const (
+ docDir = "docs"
+ docPath = docDir + "/plugin-description.md"
+ topLevel = "# "
+ SecondLevel = "## "
+ thirdLevel = "### "
+ LF = "\n"
+ codeQuote = "```"
+ descStr = "description"
+ confStr = "defaultConfig"
+)
+
+func GeneratePluginDoc() error {
+ log.Init(&log.LoggerConfig{})
+ plugins.RegisterPlugins()
+ // the generated doc content
+ var doc string
+ // sort categories by dictionary sequence
+ var categories []reflect.Type
+ for c := range plugin.Reg {
+ categories = append(categories, c)
+ }
+ sort.Slice(categories, func(i, j int) bool {
+ return strings.Compare(categories[i].String(),
categories[j].String()) <= 0
+ })
+ for _, category := range categories {
+ mapping := plugin.Reg[category]
+ var keys []string
+ for k := range mapping {
+ keys = append(keys, k)
+ }
+ sort.Strings(keys)
+ for _, key := range keys {
+ p := plugin.Get(category,
plugin.Config{plugin.NameField: key})
+ doc += topLevel + category.String() + LF
+ doc += SecondLevel + key + LF
+ doc += thirdLevel + descStr + LF + codeQuote +
p.Description() + codeQuote + LF
+ doc += thirdLevel + confStr + LF + codeQuote +
p.DefaultConfig() + codeQuote + LF
+ }
+ }
+ if err := createDir(docDir); err != nil {
+ return fmt.Errorf("create docs dir error: %v", err)
+ }
+ if err := ioutil.WriteFile(docPath, []byte(doc), os.ModePerm); err !=
nil {
+ return fmt.Errorf("cannot init the plugin doc: %v", err)
+ }
+ log.Logger.Info("Successfully generate documentation!")
+ return nil
+}
+
+func createDir(path string) error {
+ fileInfo, err := os.Stat(path)
+ if os.IsNotExist(err) || fileInfo.Size() == 0 {
+ return os.Mkdir(docDir, os.ModePerm)
+ }
+ return err
+}
diff --git a/plugins/fallbacker/timer/timer_fallbacker.go
b/plugins/fallbacker/timer/timer_fallbacker.go
index 8398098..324f4b0 100644
--- a/plugins/fallbacker/timer/timer_fallbacker.go
+++ b/plugins/fallbacker/timer/timer_fallbacker.go
@@ -38,7 +38,7 @@ func (t *Fallbacker) Name() string {
}
func (t *Fallbacker) Description() string {
- return "this is a timer trigger when forward fails."
+ return "this is a timer fallback trigger when forward fails."
}
func (t *Fallbacker) DefaultConfig() string {
diff --git a/plugins/queue/mmap/queue.go b/plugins/queue/mmap/queue.go
index 98f85c7..22b76b0 100644
--- a/plugins/queue/mmap/queue.go
+++ b/plugins/queue/mmap/queue.go
@@ -79,7 +79,7 @@ func (q *Queue) Name() string {
}
func (q *Queue) Description() string {
- return "this is a mmap queue"
+ return "this is a memory mapped queue to provide the persistent
storage."
}
func (q *Queue) DefaultConfig() string {
