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 d94ad878ce565c600bb9a504b29ea618eea3e212 Author: abudnikov <[email protected]> AuthorDate: Fri Aug 14 18:44:39 2020 +0300 add initial documentation on tracing --- .../java/org/apache/ignite/snippets/Tracing.java | 42 ++++++++++ docs/_docs/code-snippets/xml/tracing.xml | 29 +++++++ docs/_docs/images/trace_in_zipkin.png | Bin 0 -> 120344 bytes docs/_docs/monitoring-metrics/tracing.adoc | 86 +++++++++++++++++++++ 4 files changed, 157 insertions(+) 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 new file mode 100644 index 0000000..fd404e2 --- /dev/null +++ b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/Tracing.java @@ -0,0 +1,42 @@ +package org.apache.ignite.snippets; + +import org.apache.ignite.Ignite; +import org.apache.ignite.Ignition; +import org.apache.ignite.configuration.IgniteConfiguration; +import org.junit.jupiter.api.Test; + +import io.opencensus.exporter.trace.zipkin.ZipkinExporterConfiguration; +import io.opencensus.exporter.trace.zipkin.ZipkinTraceExporter; + +public class Tracing { + + @Test + void config() { + //tag::config[] + IgniteConfiguration cfg = new IgniteConfiguration(); + + cfg.setTracingSpi(new org.apache.ignite.spi.tracing.opencensus.OpenCensusTracingSpi()); + + Ignite ignite = Ignition.start(cfg); + //end::config[] + + ignite.close(); + } + + @Test + void exportToZipkin() { + //tag::export-to-zipkin[] + ZipkinTraceExporter.createAndRegister(ZipkinExporterConfiguration.builder() + .setV2Url("http://localhost:9411/api/v2/spans";).setServiceName("ignite-cluster").build()); + + IgniteConfiguration cfg = new IgniteConfiguration(); + + cfg.setTracingSpi(new org.apache.ignite.spi.tracing.opencensus.OpenCensusTracingSpi()); + + Ignite ignite = Ignition.start(cfg); + //end::config[] + //end::export-to-zipkin[] + ignite.close(); + + } +} diff --git a/docs/_docs/code-snippets/xml/tracing.xml b/docs/_docs/code-snippets/xml/tracing.xml new file mode 100644 index 0000000..7902987 --- /dev/null +++ b/docs/_docs/code-snippets/xml/tracing.xml @@ -0,0 +1,29 @@ +<?xml version="1.0" encoding="UTF-8"?> +<beans xmlns="http://www.springframework.org/schema/beans"; xmlns:util="http://www.springframework.org/schema/util"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd";> + <!-- tag::ignite-config[] --> + <bean class="org.apache.ignite.configuration.IgniteConfiguration"> + + <property name="tracingSpi"> + <bean class="org.apache.ignite.spi.tracing.opencensus.OpenCensusTracingSpi"/> + </property> + + <!-- tag::discovery[] --> + <property name="discoverySpi"> + <bean class="org.apache.ignite.spi.discovery.tcp.TcpDiscoverySpi"> + <!-- prevent this client from reconnecting on connection loss --> + <property name="clientReconnectDisabled" value="true"/> + <property name="ipFinder"> + <bean class="org.apache.ignite.spi.discovery.tcp.ipfinder.vm.TcpDiscoveryVmIpFinder"> + <property name="addresses"> + <list> + <value>127.0.0.1:47500..47509</value> + </list> + </property> + </bean> + </property> + </bean> + </property> + <!-- end::discovery[] --> + </bean> + <!-- end::ignite-config[] --> +</beans> \ No newline at end of file diff --git a/docs/_docs/images/trace_in_zipkin.png b/docs/_docs/images/trace_in_zipkin.png new file mode 100644 index 0000000..fdf1e18 Binary files /dev/null and b/docs/_docs/images/trace_in_zipkin.png differ diff --git a/docs/_docs/monitoring-metrics/tracing.adoc b/docs/_docs/monitoring-metrics/tracing.adoc new file mode 100644 index 0000000..1200afb --- /dev/null +++ b/docs/_docs/monitoring-metrics/tracing.adoc @@ -0,0 +1,86 @@ += Tracing + +:javaFile: {javaCodeDir}/Tracing.java + +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/. + +The following APIs are instrumented for tracing: + +* Discovery +* Communication +* Exchange +* Transactions + +== Configuring Tracing + +. Configure OpenCensus tracing in the node configuration: ++ +[tabs] +-- +tab:XML[] +[source, xml] +---- +include::code-snippets/xml/tracing.xml[tags=ignite-config;!discovery, indent=0] +---- + +tab:Java[] +[source, java] +---- +include::{javaFile}[tags=config, indent=0] +---- +tab:C#/.NET[] + +tab:C++[unsupported] +-- + +. Enable sampling of traces for a specific scope: ++ +-- +[source, shell] +---- +./control.sh --tracing-configuration set --scope DISCOVERY --sampling-rate 1 +---- + +The `--scope` parameter specifies the API you want to trace. +The following APIs are instrumented for tracing: + +* `DISCOVERY` — discovery events +* `EXCHANGE` — exchange events +* `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. +-- + + +== Viewing Traces + +To view traces, you need to export them to an external backend using one of the available exporters. +OpenCensus supports a number of exporter out-of-the-box, and you can write a custom exporter. +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. + +[source, java] +---- +include::{javaFile}[tags=export-to-zipkin, indent=0] +---- + +Start one server node and then start another node. + +TODO + +open http://localhost:9411[^] in your browser + +This is what a trace of a node join event looks like: + +image::images/trace_in_zipkin.png[] + + + +
