You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by ct...@apache.org on 2020/12/16 20:25:19 UTC
[lucene-solr] branch branch_8x updated: Ref Guide: copy editing
solr-tracing.adoc; fix for table template so format options to work;
code in tables is highlighted
This is an automated email from the ASF dual-hosted git repository.
ctargett pushed a commit to branch branch_8x
in repository https://gitbox.apache.org/repos/asf/lucene-solr.git
The following commit(s) were added to refs/heads/branch_8x by this push:
new abaf683 Ref Guide: copy editing solr-tracing.adoc; fix for table template so format options to work; code in tables is highlighted
abaf683 is described below
commit abaf68348c2296bdd49804104c5b809d47bced0f
Author: Cassandra Targett <ct...@apache.org>
AuthorDate: Wed Dec 16 14:20:13 2020 -0600
Ref Guide: copy editing solr-tracing.adoc; fix for table template so format options to work; code in tables is highlighted
---
solr/solr-ref-guide/src/_templates/table.html.slim | 4 +-
.../src/cluster-node-management.adoc | 7 +-
solr/solr-ref-guide/src/css/ref-guide.css | 1 -
.../images/solr-tracing/query-request-tracing.png | Bin 286374 -> 157465 bytes
solr/solr-ref-guide/src/solr-tracing.adoc | 102 +++++++++++++++------
5 files changed, 80 insertions(+), 34 deletions(-)
diff --git a/solr/solr-ref-guide/src/_templates/table.html.slim b/solr/solr-ref-guide/src/_templates/table.html.slim
index 0d06657..b66bf5b 100644
--- a/solr/solr-ref-guide/src/_templates/table.html.slim
+++ b/solr/solr-ref-guide/src/_templates/table.html.slim
@@ -1,6 +1,6 @@
= block_with_caption :top, :class=>'tableblock'
table [
- class=["frame-#{attr :frame, 'all'}", "grid-#{attr :grid, 'all'}", spread?]
+ class=["tableblock", "frame-#{attr :frame, 'all'}", "grid-#{attr :grid, 'all'}", spread?]
style=style_value(width: ("#{attr :tablepcwidth}%" if !autowidth? && !spread? || (local_attr :width)),
float: (attr :float)) ]
- unless (attr :rowcount).zero?
@@ -17,7 +17,7 @@
tr
- row.each do |cell|
= html_tag(tblsec == :head || cell.style == :header ? 'th' : 'td',
- :class=>["halign-#{cell.attr :halign}", "valign-#{cell.attr :valign}"],
+ :class=>["tableblock", "halign-#{cell.attr :halign}", "valign-#{cell.attr :valign}"],
:colspan=>cell.colspan,
:rowspan=>cell.rowspan,
:style=>style_value(background_color: (document.attr :cellbgcolor)))
diff --git a/solr/solr-ref-guide/src/cluster-node-management.adoc b/solr/solr-ref-guide/src/cluster-node-management.adoc
index a605d84..d302e1a 100644
--- a/solr/solr-ref-guide/src/cluster-node-management.adoc
+++ b/solr/solr-ref-guide/src/cluster-node-management.adoc
@@ -131,8 +131,11 @@ Add, edit or delete a cluster-wide property.
=== CLUSTERPROP Parameters
`name`::
-The name of the property. Supported properties names are `autoAddReplicas`, `legacyCloud`, `location`, `maxCoresPerNode`, `urlScheme` and `defaultShardPreferences`. Other properties can be set
-(for example, if you need them for custom plugins) but they must begin with the prefix `ext.`. Unknown properties that don't begin with `ext.` will be rejected.
+The name of the property. Supported properties names are `autoAddReplicas`, `legacyCloud`, `location`, `maxCoresPerNode`, `urlScheme`, and `defaultShardPreferences`.
+If the <<solr-tracing.adoc#solr-tracing,Jaeger tracing contrib>> has been enabled, the property `samplePercentage` is also available.
++
+Other properties can be set (for example, if you need them for custom plugins) but they must begin with the prefix `ext.`.
+Unknown properties that don't begin with `ext.` will be rejected.
`val`::
The value of the property. If the value is empty or null, the property is unset.
diff --git a/solr/solr-ref-guide/src/css/ref-guide.css b/solr/solr-ref-guide/src/css/ref-guide.css
index efac8a0..9037823 100644
--- a/solr/solr-ref-guide/src/css/ref-guide.css
+++ b/solr/solr-ref-guide/src/css/ref-guide.css
@@ -1184,7 +1184,6 @@ tfoot tr th p
p.tableblock > code:only-child
{
padding: 0;
- background: none;
}
td > div.verse
diff --git a/solr/solr-ref-guide/src/images/solr-tracing/query-request-tracing.png b/solr/solr-ref-guide/src/images/solr-tracing/query-request-tracing.png
index 827d0f5..8098e35 100644
Binary files a/solr/solr-ref-guide/src/images/solr-tracing/query-request-tracing.png and b/solr/solr-ref-guide/src/images/solr-tracing/query-request-tracing.png differ
diff --git a/solr/solr-ref-guide/src/solr-tracing.adoc b/solr/solr-ref-guide/src/solr-tracing.adoc
index 2d90516..47477ed 100644
--- a/solr/solr-ref-guide/src/solr-tracing.adoc
+++ b/solr/solr-ref-guide/src/solr-tracing.adoc
@@ -17,22 +17,24 @@
// under the License.
Solr includes a general tracing framework based on OpenTracing that can be used to trace lifecycle of a request for performance monitoring.
-Tracing data can be configured and send to arbitrary backend like Jaeger, Zipkin, Datadog, etc. For now only Jaeger is
-supported out of the box.
+
+Tracing data can be configured to send to arbitrary backend like Jaeger, Zipkin, Datadog, etc.
+At the moment, only Jaeger is supported out of the box.
A sampled distributed tracing query request on Jaeger looks like this:
.Tracing of a Solr query
-image::images/solr-tracing/query-request-tracing.png[image,width=600]
+image::images/solr-tracing/query-request-tracing.png[]
-== Setup Tracer
+== Configuring Tracer
-`TracerConfigurator` is a class used for provide an instance of `io.opentracing.Tracer` based on configuration in `solr.xml`.
-Like `JaegerTracerConfigurator` provide JaegerTracer instance to Solr node.
+`TracerConfigurator` is a class used to provide an instance of `io.opentracing.Tracer` based on configuration in `solr.xml`.
+The `JaegerTracerConfigurator` provides a JaegerTracer instance to a Solr node.
-A setup of a `TracerConfigurator` looks like this
+A setup of a `TracerConfigurator` in `solr.xml` looks like this:
-```xml
+[source,xml]
+----
<solr>
<tracerConfig name="tracerConfig" class="org.apache.solr.jaeger.JaegerTracerConfigurator">
<str name="agentHost">localhost</str>
@@ -42,29 +44,33 @@ A setup of a `TracerConfigurator` looks like this
<int name="maxQueueSize">10000</int>
</tracerConfig>
</solr>
-```
+----
-If `<tracerConfig>` part is absent, `TracerConfigurator` will try to pick up the `Tracer` instance was registered in
-in `io.opentracing.util.GlobalTracer`. By doing this some backend like DataDog is supported out of the box since
-https://docs.datadoghq.com/tracing/setup/java/[datadog-java-agent] use Javaagent to register a `Tracer` in
+If `<tracerConfig>` is absent, `TracerConfigurator` will try to pick up the `Tracer` instance that was registered in `io.opentracing.util.GlobalTracer`.
+By doing this some backends like DataDog are supported out of the box since
+https://docs.datadoghq.com/tracing/setup/java/[datadog-java-agent] uses Javaagent to register a `Tracer` in
`io.opentracing.util.GlobalTracer`.
=== Configuring Sample Rate
-By default only 0.1% of requests are sampled, this ensure that tracing activities does not affect performance of a node.
+By default only 0.1% of requests are sampled, this ensures that tracing activities do not affect performance of a node.
+
+The rate can be changed without needing to restart Solr nodes by setting the new sample rate as a cluster property using the Collections API's <<cluster-node-management.adoc#clusterprop,CLUSTERPROP>> command.
+
+For example, the following sets the `samplePercentage` property to 100%:
-The rate can be changed on the fly (without restarting Solr nodes) by setting new sample rate in cluster property. For example,
-below call set sample rate to 100%
-```
+[source,text]
/admin/collections?action=CLUSTERPROP&name=samplePercentage&val=100
-```
== Jaeger Tracer Configurator
-Module `contrib/jagertracer-configurator` provides a default implementation for setting up Jaeger Tracer.
-Note that all library of jaegertracer-configurator must be included in the classpath of all nodes then Jaeger tracer can be setup in `solr.xml` like this:
+The `contrib/jagertracer-configurator` provides a default implementation for setting up Jaeger Tracer.
-```
+Note that all libraries of `jaegertracer-configurator` must be included in the classpath of all nodes.
+Then Jaeger tracer can be set up in `solr.xml` like this:
+
+[source,xml]
+----
<tracerConfig name="tracerConfig" class="org.apache.solr.jaeger.JaegerTracerConfigurator">
<str name="agentHost">localhost</str>
<int name="agentPort">5775</int>
@@ -72,16 +78,54 @@ Note that all library of jaegertracer-configurator must be included in the class
<int name="flushInterval">1000</int>
<int name="maxQueueSize">10000</int>
</tracerConfig>
-```
+----
+
+The parameters for `JaegerTracerConfigurator` include:
+
+`agentHost`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+The Jaeger backend host.
+
+`agentPort`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+The Jaeger port.
+
+`logSpans`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `true`
+|===
++
+Whether the tracer should also log the spans.
+
+`flushInterval`::
++
+[%autowidth,frame=none]
+|===
+|Optional | Default: `5000` (ms)
+|===
++
+The tracer's flush interval.
-List of parameters for JaegerTracerConfigurator include:
+`maxQueueSize`::
++
+[%autowidth,frame=none]
|===
-|Parameter|Type|Required|Default|Description
-|agentHost|string|Yes||The host of Jaeger backend
-|agentPort|int|Yes||The port of Jaeger port
-|logsSpans|bool|No|true|Whether the tracer should also log the spans
-|flushInterval|int|No|5000|The tracer's flush interval (ms)
-|maxQueueSize|int|No|10000|The tracer's maximum queue size
+|Optional | Default: `10000`
|===
++
+The tracer's maximum queue size.
-Other parameters which are not listed above can be configured using System Properties or Environment Variables. The full list are listed at https://github.com/jaegertracing/jaeger-client-java/blob/master/jaeger-core/README.md[Jaeger-README].
+Other parameters which are not listed above can be configured using system properties or environment variables.
+The full list of parameters can be found in the https://github.com/jaegertracing/jaeger-client-java/blob/master/jaeger-core/README.md[Jaeger-README].