[incubator-skywalking] branch backend-sampling updated: Add a trace sampling document

[wu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

wusheng pushed a commit to branch backend-sampling
in repository https://gitbox.apache.org/repos/asf/incubator-skywalking.git


The following commit(s) were added to refs/heads/backend-sampling by this push:
     new 4ea0ab0  Add a trace sampling document
4ea0ab0 is described below

commit 4ea0ab0e536ac54a3b1f06b189847f844c31a21b
Author: Wu Sheng <wu...@foxmail.com>
AuthorDate: Thu Nov 29 16:26:11 2018 +0800

    Add a trace sampling document
---
 docs/en/setup/backend/backend-receivers.md |  1 +
 docs/en/setup/backend/backend-setup.md     |  2 ++
 docs/en/setup/backend/trace-sampling.md    | 36 ++++++++++++++++++++++++++++++
 3 files changed, 39 insertions(+)

diff --git a/docs/en/setup/backend/backend-receivers.md b/docs/en/setup/backend/backend-receivers.md
index b808acb..361d409 100644
--- a/docs/en/setup/backend/backend-receivers.md
+++ b/docs/en/setup/backend/backend-receivers.md
@@ -23,6 +23,7 @@ receiver-trace:
     bufferOffsetMaxFileSize: 100 # Unit is MB
     bufferDataMaxFileSize: 500 # Unit is MB
     bufferFileCleanWhenRestart: false
+    sampleRate: {$SW_TRACE_SAMPLE_RATE:1000} # The sample rate precision is 1/10000. 10000 means 100% sample in default.
 receiver-jvm:
   default:
 service-mesh:
diff --git a/docs/en/setup/backend/backend-setup.md b/docs/en/setup/backend/backend-setup.md
index bb4f612..e2e4376 100644
--- a/docs/en/setup/backend/backend-setup.md
+++ b/docs/en/setup/backend/backend-setup.md
@@ -63,6 +63,8 @@ DB. But clearly, it doesn't fit the product env. In here, you could find what ot
 Choose the one you like, we are also welcome anyone to contribute new storage implementor,
 1. [Set receivers](backend-receivers.md). You could choose receivers by your requirements, most receivers
 are harmless, at least our default receivers are. You would set and active all receivers provided.
+1. Do [trace sampling](trace-sampling.md) at backend. This sample keep the metric accurate, only don't save some of traces
+in storage based on rate.
 1. Official [OAL scripts](../../guides/backend-oal-scripts.md). As you known from our [OAL introduction](../../concepts-and-designs/oal.md),
 most of backend analysis capabilities based on the scripts. Here is the description of official scripts,
 which helps you to understand which metric data are in process, also could be used in alarm.
diff --git a/docs/en/setup/backend/trace-sampling.md b/docs/en/setup/backend/trace-sampling.md
new file mode 100644
index 0000000..617a40d
--- /dev/null
+++ b/docs/en/setup/backend/trace-sampling.md
@@ -0,0 +1,36 @@
+# Trace Sampling at server side
+When we run a distributed tracing system, the trace bring us detailed info, but cost a lot at storage.
+Open server side trace sampling mechanism, the metric of service, service instance, endpoint and topology are all accurate
+as before, but only don't save all the traces into storage.
+
+Of course, even you open sampling, the traces will be kept as consistent as possible. **Consistent** means, once the trace
+segments have been collected and reported by agents, the backend would do their best to don't break the trace. See [Recommendation](#recommendation)
+to understand why we called it `as consistent as possible` and `do their best to don't break the trace`.
+
+## Set the sample rate
+In **receiver-trace** receiver, you will find `sampleRate` setting.
+
+```yaml
+receiver-trace:
+  default:
+    bufferPath: ../trace-buffer/  # Path to trace buffer files, suggest to use absolute path
+    bufferOffsetMaxFileSize: 100 # Unit is MB
+    bufferDataMaxFileSize: 500 # Unit is MB
+    bufferFileCleanWhenRestart: false
+    sampleRate: {$SW_TRACE_SAMPLE_RATE:1000} # The sample rate precision is 1/10000. 10000 means 100% sample in default.
+```
+
+`sampleRate` is for you to set sample rate to this backend. 
+The sample rate precision is 1/10000. 10000 means 100% sample in default. 
+
+# Recommendation
+You could set different backend instances with different `sampleRate` values, but we recommend you to set the same.
+
+When you set the rate different, let's say
+* Backend-Instance**A**.sampleRate = 35
+* Backend-Instance**B**.sampleRate = 55
+
+And we assume the agents reported all trace segments to backend,
+Then the 35% traces in the global will be collected and saved in storage consistent/complete, with all spans.
+20% trace segments, which reported to Backend-Instance**B**, will saved in storage, maybe miss some trace segments,
+because they are reported to Backend-Instance**A** and ignored.
\ No newline at end of file