You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ignite.apache.org by ab...@apache.org on 2020/08/19 10:19:20 UTC
[ignite] 03/03: update tracing page
This is an automated email from the ASF dual-hosted git repository.
abudnikov pushed a commit to branch IGNITE-7595
in repository https://gitbox.apache.org/repos/asf/ignite.git
commit 6b9c7f42781a1fd1b6b8a5b753e268027389a441
Author: abudnikov <ab...@gridgain.com>
AuthorDate: Wed Aug 19 13:18:15 2020 +0300
update tracing page
---
.../java/org/apache/ignite/snippets/Tracing.java | 20 ++++++-
docs/_docs/monitoring-metrics/tracing.adoc | 65 ++++++++++++++++++----
2 files changed, 71 insertions(+), 14 deletions(-)
diff --git a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/Tracing.java b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/Tracing.java
index 7181ef8..61ec931 100644
--- a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/Tracing.java
+++ b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/Tracing.java
@@ -1,9 +1,11 @@
package org.apache.ignite.snippets;
import org.apache.ignite.Ignite;
-import org.apache.ignite.IgniteSystemProperties;
import org.apache.ignite.Ignition;
import org.apache.ignite.configuration.IgniteConfiguration;
+import org.apache.ignite.spi.tracing.Scope;
+import org.apache.ignite.spi.tracing.TracingConfigurationCoordinates;
+import org.apache.ignite.spi.tracing.TracingConfigurationParameters;
import org.junit.jupiter.api.Test;
import io.opencensus.exporter.trace.zipkin.ZipkinExporterConfiguration;
@@ -24,11 +26,23 @@ public class Tracing {
ignite.close();
}
+ void enableSampling() {
+ //tag::enable-sampling[]
+ Ignite ignite = Ignition.start();
+
+ ignite.tracingConfiguration().set(
+ new TracingConfigurationCoordinates.Builder(Scope.TX).build(),
+ new TracingConfigurationParameters.Builder().withSamplingRate(0.5).build());
+
+ //end::enable-sampling[]
+ }
+
@Test
void exportToZipkin() {
//tag::export-to-zipkin[]
- ZipkinTraceExporter.createAndRegister(ZipkinExporterConfiguration.builder()
- .setV2Url("http://localhost:9411/api/v2/spans").setServiceName("ignite-cluster").build());
+ ZipkinTraceExporter.createAndRegister(
+ ZipkinExporterConfiguration.builder().setV2Url("http://localhost:9411/api/v2/spans")
+ .setServiceName("ignite-cluster").build());
IgniteConfiguration cfg = new IgniteConfiguration();
diff --git a/docs/_docs/monitoring-metrics/tracing.adoc b/docs/_docs/monitoring-metrics/tracing.adoc
index 1200afb..5536387 100644
--- a/docs/_docs/monitoring-metrics/tracing.adoc
+++ b/docs/_docs/monitoring-metrics/tracing.adoc
@@ -2,12 +2,14 @@
:javaFile: {javaCodeDir}/Tracing.java
+WARNING: Experimental
+
A number of APIs in Ignite are instrumented with OpenCensus for tracing.
You can collect distributed traces of various tasks execuded in your cluster and use this information to diagnose latency problems.
-We suggest you get familiar with OpenCensus tracing documentation: https://opencensus.io/tracing/.
+We suggest you get familiar with OpenCensus tracing documentation: https://opencensus.io/tracing/[^].
-The following APIs are instrumented for tracing:
+The following Ignite APIs are instrumented for tracing:
* Discovery
* Communication
@@ -16,8 +18,8 @@ The following APIs are instrumented for tracing:
== Configuring Tracing
-. Configure OpenCensus tracing in the node configuration:
-+
+Enable OpenCensus tracing in the node configuration. All nodes in the cluster must use the same tracing configuration.
+
[tabs]
--
tab:XML[]
@@ -36,14 +38,54 @@ tab:C#/.NET[]
tab:C++[unsupported]
--
-. Enable sampling of traces for a specific scope:
-+
---
+
+
+== Enabling Sampling of Traces
+
+When you start your cluster with the above configuration, Ignite will not collect traces.
+You have to enable collection of traces for a specific API at runtime.
+You can turn trace sampling on and off at will, for example, only for the period when you are troubleshooting a problem.
+
+You can do this in two ways:
+
+* via the control script from the command line
+* programmatically
+
+Traces are collected with a given probabilistic sampling rate.
+The rate is specified as a value between 0 and 1 inclusive: `0` means no sampling, `1` means always sampling.
+
+When the sampling rate is set to a value greater than 0, Ignite will collect traces.
+To disable trace collection, set the sampling rate to 0.
+
+The following sections describe the two ways of enabling trace sampling.
+
+=== Using Control Script
+
+Go to the `{IGNITE_HOME}/bin` directory of your Ignite installation.
+Enable experimental commands in the control script:
+
+[source, shell]
+----
+export IGNITE_ENABLE_EXPERIMENTAL_COMMAND=true
+----
+
+Enable tracing for a specific API:
+
[source, shell]
----
./control.sh --tracing-configuration set --scope DISCOVERY --sampling-rate 1
----
+=== Programmatically
+
+Once you start the node, you can enable sampling as follows:
+
+[source, java]
+----
+include::{javaFile}[tags=enable-sampling, indent=0]
+----
+
+
The `--scope` parameter specifies the API you want to trace.
The following APIs are instrumented for tracing:
@@ -52,9 +94,10 @@ The following APIs are instrumented for tracing:
* `COMMUNICATION` — communication events
* `TX` — transactions
-The `--sampling-rate` is the probabilistic sampling rate, a number between `0` and `1`.
-`0` means no sampling, `1` means always sampling.
---
+The `--sampling-rate` is the probabilistic sampling rate, a number between `0` and `1`:
+
+* `0` means no sampling,
+* `1` means always sampling.
== Viewing Traces
@@ -64,7 +107,7 @@ OpenCensus supports a number of exporter out-of-the-box, and you can write a cus
Refer to the link:https://opencensus.io/exporters/[OpenCensus Exporters^] for details.
In this section, we will show how to export traces to link:https://zipkin.io[Zipkin^].
-Follow link:https://zipkin.io/pages/quickstart.html[this guide^] to launch Zipkin in your local machine.
+Follow link:https://zipkin.io/pages/quickstart.html[this guide^] to launch Zipkin on your machine.
[source, java]
----