From 9ac0f0779372782c169686f0084ce0395e7c0862 Mon Sep 17 00:00:00 2001 From: Wu Sheng Date: Tue, 7 Aug 2018 20:25:11 +0800 Subject: [PATCH] Refactor documents. Delete all backend documents, cc @peng-yongsheng , considering backend refactored, then the documents should rebuild manually. --- docs/en/guides/How-to-release.md | 2 +- docs/en/setup/README.md | 4 +-- .../backend-language-agent-setup.md} | 0 docs/en/setup/backend/backend-token-auth.md | 0 docs/en/setup/istio/README.md | 0 .../java-agent/Applicaton-toolkit.md | 14 -------- .../service-agent/java-agent/Direct-uplink.md | 32 ------------------- .../service-agent/java-agent/Namespace.md | 25 +++------------ .../setup/service-agent/java-agent/README.md | 30 ++++++++--------- docs/en/setup/service-agent/java-agent/TLS.md | 27 ++-------------- .../service-agent/java-agent/Token-auth.md | 19 ++--------- ...Use-ShardingJDBC-as-storage-implementor.md | 21 ------------ 12 files changed, 25 insertions(+), 149 deletions(-) rename docs/en/setup/{service-agent/backend-setup.md => backend/backend-language-agent-setup.md} (100%) create mode 100644 docs/en/setup/backend/backend-token-auth.md create mode 100644 docs/en/setup/istio/README.md delete mode 100644 docs/en/setup/service-agent/java-agent/Applicaton-toolkit.md delete mode 100644 docs/en/setup/service-agent/java-agent/Direct-uplink.md delete mode 100644 docs/en/setup/service-agent/java-agent/Use-ShardingJDBC-as-storage-implementor.md diff --git a/docs/en/guides/How-to-release.md b/docs/en/guides/How-to-release.md index 44de715083..ca427f5734 100644 --- a/docs/en/guides/How-to-release.md +++ b/docs/en/guides/How-to-release.md @@ -307,7 +307,7 @@ enter your apache password 3. Public download URLs under `http://www.apache.org/dyn/closer.cgi/incubator/skywalking/x.y.z`. 4. Public KEYS, sigs and sha512 URLs under `https://www.apache.org/dist/incubator/skywalking/xxxx` 5. Re-tag on GitHub, tag `x.y.z-RCx` as `x.y.z`, and publish a GitHub release based on this tag. -5. Send ANNOUNCE mail to `general@incubator.apache.org`. +5. Send ANNOUNCE mail to `general@incubator.apache.org` and `dev@skywalking.apache.org`. ``` Mail title: [ANNOUNCE] Release Apache SkyWalking (incubating) version x.y.z diff --git a/docs/en/setup/README.md b/docs/en/setup/README.md index ca23bd6338..0bf613ab9a 100644 --- a/docs/en/setup/README.md +++ b/docs/en/setup/README.md @@ -3,10 +3,10 @@ Setup based on which kind of probes are you going to use. If you don't understan ## Language agents in Service - Install agents - - [Java agent](service-agent/java-agent/README.md). Introduce how to install java agent to your application, without change any codes. + - [Java agent](service-agent/java-agent/README.md). Introduce how to install java agent to your service, without change any codes. - [.NET Core agent](https://github.com/OpenSkywalking/skywalking-netcore). See .NET Core agent project document for more details. - [Node.js agent](https://github.com/OpenSkywalking/skywalking-nodejs). See Node.js server side agent project document for more details. - - [Setup backend](service-agent/backend-setup.md). Set the backend for language agents scenario. + - [Setup backend](backend/backend-language-agent-setup.md). Set the backend for language agents scenario. ## On Service Mesh - Istio diff --git a/docs/en/setup/service-agent/backend-setup.md b/docs/en/setup/backend/backend-language-agent-setup.md similarity index 100% rename from docs/en/setup/service-agent/backend-setup.md rename to docs/en/setup/backend/backend-language-agent-setup.md diff --git a/docs/en/setup/backend/backend-token-auth.md b/docs/en/setup/backend/backend-token-auth.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/setup/istio/README.md b/docs/en/setup/istio/README.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/setup/service-agent/java-agent/Applicaton-toolkit.md b/docs/en/setup/service-agent/java-agent/Applicaton-toolkit.md deleted file mode 100644 index a7644a6a81..0000000000 --- a/docs/en/setup/service-agent/java-agent/Applicaton-toolkit.md +++ /dev/null @@ -1,14 +0,0 @@ -# What's sky-walking application toolkit? -Sky-walking application toolkit is a batch of libraries, provided by skywalking APM. Using them, you have a bridge between your application and skywalking APM agent. - -_**Most important**_, they will not trigger any runtime or performance issues for your application, whether skywalking tracer is active or not. - -# What does bridge mean? -As you known, skywalking agent run by -javeagent VM parameter. So you definitely don't need to change even a single line of your codes. But in some cases, you want to do interop with tracing/APM system. This is the moment you want to use application toolkit. -e.g. -1. Integrate trace context(traceId) into your log component, e.g. log4j, log4j2 and logback. -1. Use CNCF OpenTracing for manually instrumentation. -1. Use Skywalking annotation and interactive APIs. - - -_**Notice**: all toolkits libraries are on bitray.com/jcenter. And make sure their version should be as same as the tracer's version._ \ No newline at end of file diff --git a/docs/en/setup/service-agent/java-agent/Direct-uplink.md b/docs/en/setup/service-agent/java-agent/Direct-uplink.md deleted file mode 100644 index 392c8fda64..0000000000 --- a/docs/en/setup/service-agent/java-agent/Direct-uplink.md +++ /dev/null @@ -1,32 +0,0 @@ -# Direct uplink -## Supported version -5.0.0-beta + - -## What is direct uplink? -In default, SkyWalking agent uses naming service to find all collector addresses. Then connect to gRPC services. - -In **direct uplink**, mean no naming service available or don't work well, set the gRPC addresses in agent directly. -The agent uses theses addresses to connect gRPC services. - -## Why need this? -Agent uplink data through the following network -1. VPCs in Cloud -1. Internet -1. Different subnet. -1. IPs and Ports proxy - -## Set the agent config -1. Remove `collector.servers` config item. -2. You can find the following settings in `agent.config` -``` -# Collector agent_gRPC/grpc service addresses. -# Secondary address setting, only effect when "collector.servers" is empty. -# By using this, no discovery mechanism provided. The agent only uses these addresses to uplink data. -# Recommend to use this only when collector cluster IPs are unreachable from agent side. Such as: -# 1. Agent and collector cluster are in different VPC in Cloud. -# 2. Agent uplinks data to collector cluster through Internet. -# collector.direct_servers=www.skywalking.service.io -``` - -3. Set `collector.direct_servers` to a domain name, IP:PORTs, with split by comma(,). - diff --git a/docs/en/setup/service-agent/java-agent/Namespace.md b/docs/en/setup/service-agent/java-agent/Namespace.md index 19582a8d57..a2732ddc4a 100644 --- a/docs/en/setup/service-agent/java-agent/Namespace.md +++ b/docs/en/setup/service-agent/java-agent/Namespace.md @@ -1,14 +1,12 @@ # Namespace -## Supported version -5.0.0-beta + ## Background SkyWalking is a monitoring tool, which collects metrics from a distributed system. In the real world, a very large distributed system -includes hundreds of application, thousands of application instance. In that case, more likely, more than one group, -even than one company are maintaining and monitoring the distributed system. Each one of them takes charge of different parts, -don't or can't share there metrics. +includes hundreds of services, thousands of service instances. In that case, most likely, more than one group, +even more than one company are maintaining and monitoring the distributed system. Each one of them takes charge of different parts, +don't want or shouldn't share there metrics. -Namespace is proposal from this.It is used for tracing and monitoring isolation. +Namespace is the proposal from this.It is used for tracing and monitoring isolation. ## Set the namespace ### Set agent.namespace in agent config @@ -21,19 +19,6 @@ The default value of `agent.namespace` is empty. **Influence** The default header key of SkyWalking is `sw3`, more in this [document](../../../protocols/Skywalking-Cross-Process-Propagation-Headers-Protocol-v1.md). -After `agent.namespace` set, the key changes to `namespace:sw3`. +After `agent.namespace` set, the key changes to `namespace-sw3`. The across process propagation chain breaks, when the two sides are using different namespace. - -### Set namespace in collector -```yml -configuration: - default: - namespace: xxxxx -``` - -**Influences** -1. If cluster model is active, with zookeeper implementation, The path in zookeeper is changed to include namespace prefix path. -1. If use Elasticsearch as storage implementation, all type names are changed to include namespace prefix. - - diff --git a/docs/en/setup/service-agent/java-agent/README.md b/docs/en/setup/service-agent/java-agent/README.md index e38602312d..abf1f363bb 100644 --- a/docs/en/setup/service-agent/java-agent/README.md +++ b/docs/en/setup/service-agent/java-agent/README.md @@ -1,6 +1,6 @@ # Setup java agent -1. Find `agent` folder in SkyWalking -2. Add `-javaagent:/path/to/skywalking-agent/skywalking-agent.jar` to VM argument. +1. Find `agent` folder in SkyWalking release package +2. Add `-javaagent:/path/to/skywalking-package/agent/skywalking-agent.jar` to JVM argument. And make sure to add it before the `-jar` argument. New agent package looks like this： ``` @@ -39,7 +39,7 @@ Change the first line of `tomcat/bin/catalina.bat`. set "CATALINA_OPTS=-javaagent:/path/to/skywalking-agent/skywalking-agent.jar" ``` - JAR file -Add `-javaagent` argument to command line in which you start your app. And make sure to add it before the `-jar` argument. eg: +Add `-javaagent` argument to command line in which you start your app. eg: ```shell java -javaagent:/path/to/skywalking-agent/skywalking-agent.jar -jar yourApp.jar ``` @@ -56,20 +56,16 @@ Now, we have the following known plugins. * [Filter traces through custom services](agent-optional-plugins/trace-ignore-plugin.md) ## Advanced Features -* [Override settings through System.properties](en/java-agent/Setting-override.md) -* [Direct uplink and disable naming discovery](en/java-agent/Direct-uplink.md) -* [Open TLS](en/java-agent/TLS.md) -* [Namespace Isolation](en/java-agent/Namespace.md) -* [Token Authentication](en/java-agent/Token-auth.md) -* Application Toolkit - * [Overview](en/java-agent/Applicaton-toolkit.md) - * [Use SkyWalking OpenTracing compatible tracer](en/java-agent/Opentracing.md) - * Integration with log frameworks - * [log4j](en/java-agent/Application-toolkit-log4j-1.x.md) - * [log4j2](en/java-agent/Application-toolkit-log4j-2.x.md) - * [logback](en/java-agent/Application-toolkit-logback-1.x.md) - * [Trace by SkyWalking manual APIs](en/java-agent/Application-toolkit-trace.md) - * [Trace across threads](en/java-agent/Application-toolkit-trace-cross-thread.md) +* Set the settings through system properties for config file override. Read [setting override](Setting-override.md). +* Use gRPC TLS to link backend. See [open TLS](TLS.md) +* Monitor a big cluster by different SkyWalking services. Use [Namespace](Namespace.md) to isolate the context propagation. +* Set client [token](Token-auth.md) if backend open [token authentication](../../backend/backend-token-auth.md). +* Application Toolkit, are a collection of libraries, provided by skywalking APM. Using them, you have a bridge between your application and skywalking APM agent. + * If you want to use OpenTracing Java APIs, try [SkyWalking OpenTracing compatible tracer](Opentracing.md). More details you could find at http://opentracing.io + * If you want to print trace context(e.g. traceId) in your logs, choose the log frameworks, [log4j](Application-toolkit-log4j-1.x.md), +[log4j2](Application-toolkit-log4j-2.x.md), [logback](Application-toolkit-logback-1.x.md) + * If you want to use annotations or SkyWalking native APIs to read context, try [SkyWalking manual APIs](Application-toolkit-trace.md) + * If you want to continue traces across thread manually, use [across thread solution APIs](Application-toolkit-trace-cross-thread.md). # Test If you are interested in plugin compatible tests or agent performance, see the following reports. diff --git a/docs/en/setup/service-agent/java-agent/TLS.md b/docs/en/setup/service-agent/java-agent/TLS.md index b95d6364be..cfdc9210e9 100644 --- a/docs/en/setup/service-agent/java-agent/TLS.md +++ b/docs/en/setup/service-agent/java-agent/TLS.md @@ -7,18 +7,9 @@ at the same time, the SkyWalking backend is in another region (VPC). > > Because of that, security requirement is very obvious. -## Requirement -Enable **direct uplink**, by following this [document](Direct-uplink.md). - -Because of uplink through internet, with security concern, the naming mechanism didn't fit. -So we didn't support TLS in naming service of HTTP service. - -## Supported version -5.0.0-beta + - ## Authentication Mode Only support **no mutual auth**. -- Use this [script](../../../tools/TLS/tls_key_generate.sh) if you are not familiar with how to generate key files. +- Use this [script](../../../../../tools/TLS/tls_key_generate.sh) if you are not familiar with how to generate key files. - Find `ca.crt`, and use it at client side - Find `server.crt` and `server.pem`. Use them at server side. @@ -29,18 +20,4 @@ Only support **no mutual auth**. Agent open TLS automatically after the `/ca/ca.crt` file detected. -### Collector config -Module `agent_gRPC/gRPC` supports TLS. And only this module for now. - -- Uncomment the `ssl_cert_chain_file` and `ssl_private_key_file` settings in `application.yml` -- `ssl_cert_chain_file` value is the absolute path of `server.crt` -- `ssl_private_key_file` value is the absolute path of `server.pem` - -## Avoid port share -In most cases, we recommend sharing port for all gRPC services in `agent_gRPC/gRPC` and `remote/gRPC` modules. -But don't do this when you open TLS in `agent_gRPC/gRPC`, the obvious reason is you can't listen a port with and without TLS. - -The solution is, change the `remote/gRPC/port`. - -## How about other listening ports -Please use other security ways to make sure can't access other ports out of region (VPC), such as firewall, proxy. \ No newline at end of file +o make sure can't access other ports out of region (VPC), such as firewall, proxy. \ No newline at end of file diff --git a/docs/en/setup/service-agent/java-agent/Token-auth.md b/docs/en/setup/service-agent/java-agent/Token-auth.md index 27c754325e..843e362a54 100644 --- a/docs/en/setup/service-agent/java-agent/Token-auth.md +++ b/docs/en/setup/service-agent/java-agent/Token-auth.md @@ -1,31 +1,16 @@ # Token Authentication -## Supported version -5.0.0-beta + - -## How need token authentication after we have TLS? -TLS is about transport security, which makes sure the network can be trusted. -The token authentication is about monitoring application data **can be trusted**. ## Token In current version, Token is considered as a simple string. ### Set Token -1. Set token in agent.config file +Set token in agent.config file ```properties # Authentication active is based on backend setting, see application.yml for more details. agent.authentication = xxxx ``` -2. Set token in application.yml file -```yaml -agent_gRPC: - gRPC: - host: localhost - port: 11800 - - #Set your own token to active auth - authentication: xxxxxx -``` +Meanwhile, open the [backend token authentication](../../backend/backend-token-auth.md). ## Authentication fails The Collector verifies every request from agent, allowed only the token match. diff --git a/docs/en/setup/service-agent/java-agent/Use-ShardingJDBC-as-storage-implementor.md b/docs/en/setup/service-agent/java-agent/Use-ShardingJDBC-as-storage-implementor.md deleted file mode 100644 index 23b5a6e748..0000000000 --- a/docs/en/setup/service-agent/java-agent/Use-ShardingJDBC-as-storage-implementor.md +++ /dev/null @@ -1,21 +0,0 @@ -# Supported Database Sharding Storage -Beside the default Elasticsearch storage, the user can use shardingJDBC and MySQL as storage implementor. -Note: it only supported MYSQL database sharding, and due to the license restrictions, the users need to import MYSQL Driver manually. - -## Requirement -- Manually import MySQL Driver package mysql-connector-java-5.1.36.jar to collector libs directory. -- In config/application.yml, delete the ElasticSearch configuration and add the following shardingjdbc configuration. -``` - storage: - shardingjdbc: - driverClass: com.mysql.jdbc.Driver - # JDBC Datasource connections for ShardingJDBC, multiple should be separated by comma - url: jdbc:mysql://ip1:port1/skywalking,jdbc:mysql://ip2:port2/skywalking - # Usernames, which match the sequence of Datasource URLs - userName: admin,admin - # Passwords, which match the sequence of Datasource URLs - password: 123456,123456 -``` - -## See also -- ShardingJDBC now named as ShardingSphere since its 3.x, see [here](http://shardingsphere.io) -- GitLab