You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by wu...@apache.org on 2023/07/12 09:49:07 UTC
[skywalking-go] branch main updated: Polish documentation (#70)
This is an automated email from the ASF dual-hosted git repository.
wusheng pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/skywalking-go.git
The following commit(s) were added to refs/heads/main by this push:
new ff0018b Polish documentation (#70)
ff0018b is described below
commit ff0018bcf57ee6d28d9d7e8b2a8a1faae19fa33e
Author: mrproliu <74...@qq.com>
AuthorDate: Wed Jul 12 09:49:01 2023 +0000
Polish documentation (#70)
---
CHANGES.md | 2 ++
docs/en/advanced-features/logging-setup.md | 30 ++++++++++++++++++-
docs/en/agent/support-plugins.md | 19 ++++++++++--
docs/en/agent/tracing-metrics-logging.md | 48 ++++++++++++++++++++++++++++++
docs/menu.yml | 12 +++++---
5 files changed, 103 insertions(+), 8 deletions(-)
diff --git a/CHANGES.md b/CHANGES.md
index aeb2ea2..ece6567 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -22,6 +22,8 @@ Release Notes.
* Support [Zap](https://github.com/uber-go/zap) log report to the backend.
#### Documentation
+* Combine `Supported Libraries` and `Performance Test` into `Plugins` section.
+* Add `Tracing, Metrics and Logging` document into `Plugins` section.
#### Bug Fixes
* Fix throw panic when log the tracing context before agent core initialized.
diff --git a/docs/en/advanced-features/logging-setup.md b/docs/en/advanced-features/logging-setup.md
index 4750a1a..6063359 100644
--- a/docs/en/advanced-features/logging-setup.md
+++ b/docs/en/advanced-features/logging-setup.md
@@ -15,6 +15,12 @@ When the log type is set to `auto`, it would choose the appropriate log based on
If there are multiple different logging systems in your current application, the last-called logging system would be chosen.
+The configuration information is as follows:
+
+| Name | Environment Key | Default Value | Description |
+|-----------|-----------------|---------------|---------------------------------------------------------------------------------------|
+| log.type | SW_LOG_TYPE | auto | The type of logging system. It currently supports `auto`, `logrus`, `zap`, and `std`. |
+
## Agent with Logging system
The integration of the Agent with logs includes the two parts as following.
@@ -51,4 +57,26 @@ The following is an example of a log output when using `Zap.NewProduction`:
```
{"level":"info","ts":1683641507.052247,"caller":"gin/main.go:45","msg":"test log","SW_CTX":"[Your_ApplicationName,681e4178ee7311ed864facde48001122@192.168.50.193,6f13069eee7311ed864facde48001122,6f13070cee7311ed864facde48001122,0]"}
-```
\ No newline at end of file
+```
+
+The configuration information is as follows:
+
+| Name | Environment Key | Default Value | Description |
+|--------------------|-----------------------------|---------------|-----------------------------------------------------------------------|
+| log.tracing.enable | SW_AGENT_LOG_TRACING_ENABLE | true | Whether to automatically integrate Tracing information into the logs. |
+| log.tracing.key | SW_AGENT_LOG_TRACING_KEY | SW_CTX | The key of the Tracing information in the log. |
+
+## Log Upload
+
+The Agent would report the following two types of logs to the SkyWalking backend for storage and querying:
+
+1. **Application Logs**: It provides [support for various logging frameworks](../agent/support-plugins.md#logging-plugins) and reports logs along with the corresponding distributed tracing information related to the current request.
+**Only the relevant logs matching the current system log level would be output**.
+2. **Agent Logs**: These are the logs generated by the Agent itself.
+
+The current configuration options available are as follows:
+
+| Name | Environment Key | Default Value | Description |
+|-------------------------|----------------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| log.reporter.enable | SW_LOG_REPORTER_ENABLE | true | Whether to enable log reporting. |
+| log.reporter.label_keys | SW_LOG_REPORTER_LABEL_KEYS | | **By default, all fields are not reported.** To specify the fields that need to be reported, please provide a comma-separated list of configuration item keys. |
\ No newline at end of file
diff --git a/docs/en/agent/support-plugins.md b/docs/en/agent/support-plugins.md
index 8ad0cab..35622d1 100644
--- a/docs/en/agent/support-plugins.md
+++ b/docs/en/agent/support-plugins.md
@@ -1,4 +1,6 @@
-# Supported Libraries
+# Tracing Plugins
+The following plugins provide the distributed tracing capability, and the OAP backend would analyze the topology and
+metrics based on the tracing data.
* HTTP Server
* `gin`: [Gin](https://github.com/gin-gonic/gin) tested v1.7.0 to v1.9.0.
@@ -8,7 +10,7 @@
* `http`: [Native HTTP](https://pkg.go.dev/net/http) tested go v1.17 to go v1.20.
* RPC Frameworks
* `dubbo`: [Dubbo](https://github.com/apache/dubbo-go) tested v3.0.1 to v3.0.5.
- * `kratosv2`: [Kratos](github.com/go-kratos/kratos) tested v2.3.1 to v2.6.2.
+ * `kratosv2`: [Kratos](https://github.com/go-kratos/kratos) tested v2.3.1 to v2.6.2.
* `microv4`: [Go-Micro](https://github.com/go-micro/go-micro) tested v4.6.0 to v4.10.2.
* Database Client
* `gorm`: [GORM](https://github.com/go-gorm/gorm) tested v1.22.0 to v1.25.1.
@@ -17,4 +19,15 @@
* `sql`: [Native SQL](https://pkg.go.dev/database/sql) tested go v1.17 to go v1.20.
* [MySQL Driver](https://github.com/go-sql-driver/mysql) tested v1.4.0 to v1.7.1.
* Cache Client
- * `go-redisv9`: [go-redis](https://github.com/redis/go-redis) tested v9.0.3 to v9.0.5.
\ No newline at end of file
+ * `go-redisv9`: [go-redis](https://github.com/redis/go-redis) tested v9.0.3 to v9.0.5.
+
+# Metrics Plugins
+The meter plugin provides the advanced metrics collections.
+
+* `runtimemetrics`: [Native Runtime Metrics](https://pkg.go.dev/runtime/metrics) tested go v1.17 to go v1.20.
+
+# Logging Plugins
+The logging plugin provides the advanced logging collections.
+
+* `logrus`: [Logrus](https://github.com/sirupsen/logrus) tested v1.8.2 to v1.9.3.
+* `zap`: [Zap](http://go.uber.org/zap) tested v1.17.0 to v1.24.0.
\ No newline at end of file
diff --git a/docs/en/agent/tracing-metrics-logging.md b/docs/en/agent/tracing-metrics-logging.md
new file mode 100644
index 0000000..4d540eb
--- /dev/null
+++ b/docs/en/agent/tracing-metrics-logging.md
@@ -0,0 +1,48 @@
+# Tracing, Metrics and Logging with Go Agent
+
+All plugins in SkyWalking Go Agent are designed to provide functionality for distributed tracing, metrics, and logging data.
+For a detailed list of supported plugins, [please refer to the documentation](./support-plugins.md).
+This document aims to provide you with some configuration information for your usage.
+Please ensure that you have followed the [documentation to successfully install the SkyWalking Go Agent into your application](../setup/gobuild.md).
+
+## Metadata Mechanism
+
+The Go Agent would be identified by the SkyWalking backend after startup and maintain a heartbeat to keep alive.
+
+| Name | Environment Key | Default Value | Description |
+|-------------------------|-----------------|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
+| agent.service_name | SW_AGENT_NAME | Your_Application_Name | The name of the service which showed in UI. |
+| agent.instance_env_name | | SW_AGENT_INSTANCE_NAME | To obtain the environment variable key for the instance name, if it cannot be obtained, an instance name will be automatically generated. |
+
+## Tracing
+
+Distributed tracing is the most common form of plugin in the Go Agent, and it becomes active with each new incoming request. By default, all plugins are enabled. For a specific list of plugins, please [refer to the documentation](./support-plugins.md#tracing-plugins).
+
+If you wish to disable a particular plugin to prevent enhancements related to that plugin, please consult the [documentation on how to disable plugins](../advanced-features/plugin-exclusion.md).
+
+The basic configuration is as follows:
+
+| Name | Environment Key | Default Value | Description |
+|-------------------------|-------------------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
+| agent.sampler | SW_AGENT_SAMPLER | 1 | Sampling rate of tracing data, which is a floating-point value that must be between 0 and 1. |
+
+## Metrics
+
+The metrics plugin can dynamically monitor the execution status of the current program and aggregate the data into corresponding metrics.
+Eventually, the data is reported to the SkyWalking backend at a specified interval. For a specific list of plugins, please [refer to the documentation](./support-plugins.md#metrics-plugins).
+
+The current configuration information is as follows:
+
+| Name | Environment Key | Default Value | Description |
+|------------------------------|---------------------------------|----------------|-------------------------------------------------|
+| agent.meter.collect_interval | SW_AGENT_METER_COLLECT_INTERVAL | 20 | The interval of collecting metrics, in seconds. |
+
+## Logging
+
+The logging plugin in SkyWalking Go Agent are used to handle agent and application logs, as well as application log querying. They primarily consist of the following three functionalities:
+
+1. **Agent Log Adaptation**: The plugin detects the logging framework used in the current system and integrates the agent's logs with the system's logging framework.
+2. **Distributed Tracing Enhancement**: It combines the distributed tracing information from the current request with the application logs, allowing you to have real-time visibility into all log contents related to specific requests.
+3. **Log Reporting**: The plugin reports both application and agent logs to the SkyWalking backend for data retrieval and display purposes.
+
+For more details, please [refer to the documentation to learn more detail](../advanced-features/logging-setup.md).
diff --git a/docs/menu.yml b/docs/menu.yml
index bccbc34..13d96b2 100644
--- a/docs/menu.yml
+++ b/docs/menu.yml
@@ -35,10 +35,14 @@ catalog:
path: /en/advanced-features/plugin-exclusion
- name: Plugin Configuration
path: /en/agent/plugin-configurations
- - name: Supported Libraries
- path: /en/agent/support-plugins
- - name: Performance Test
- path: /en/agent/performance-tests
+ - name: Plugins
+ catalog:
+ - name: Supported Libraries
+ path: /en/agent/support-plugins
+ - name: Tracing, Metrics and Logging
+ path: /en/agent/tracing-metrics-logging
+ - name: Go Agent Performance Test
+ path: /en/agent/performance-tests
- name: Development and Contribution
catalog:
- name: Plugin Development Guild