This is an automated email from the ASF dual-hosted git repository.
taklwu pushed a commit to branch HBASE-25853
in repository https://gitbox.apache.org/repos/asf/hbase.git
commit 2c0664e379866ddfdec30a170e23c90e2d85954f
Author: Tak Lon (Stephen) Wu <tak...@apache.org>
AuthorDate: Thu Aug 26 09:36:05 2021 -0700
HBASE-26139 Backport HBASE-23762 "Add documentation on how to enable and
view tracing with OpenTelemetry" to branch-2 (#3629)
16/17 commits of HBASE-22120, original commit
be4503d9f82f044fbfce21c8a42d0b1684607238
Co-authored-by: Duo Zhang <zhang...@apache.org>
Signed-off-by: Duo Zhang <zhang...@apache.org>
---
src/main/asciidoc/_chapters/tracing.adoc | 57 ++++++++++++++++++++++++++++++
src/main/asciidoc/_chapters/upgrading.adoc | 4 +--
src/main/asciidoc/book.adoc | 1 +
3 files changed, 60 insertions(+), 2 deletions(-)
diff --git a/src/main/asciidoc/_chapters/tracing.adoc
b/src/main/asciidoc/_chapters/tracing.adoc
new file mode 100644
index 0000000..cc9f093
--- /dev/null
+++ b/src/main/asciidoc/_chapters/tracing.adoc
@@ -0,0 +1,57 @@
+////
+/**
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+////
+
+[[tracing]]
+= Tracing
+:doctype: book
+:numbered:
+:toc: left
+:icons: font
+:experimental:
+
+== Overview
+
+HBase used to depend on the HTrace project for tracing. After the Apache
HTrace project moved to the Attic/retired, we decided to move to
https://opentelemetry.io[OpenTelemetry] in
https://issues.apache.org/jira/browse/HBASE-22120[HBASE-22120].
+
+The basic support for tracing has been done, where we added tracing for async
client, rpc, region read/write/scan operation, and WAL. We use
opentelemetry-api to implement the tracing support manually by code, as our
code base is way too complicated to be instrumented through a java agent. But
notice that you still need to attach the opentelemetry java agent to enable
tracing. Please see the official site for
https://opentelemetry.io/[OpenTelemetry] and the documentation for https://gith
[...]
+
+== Usage
+
+=== Enable Tracing
+
+See this section in hbase-env.sh
+
+[source,shell]
+----
+# Uncomment to enable trace, you can change the options to use other exporters
such as jaeger or
+# zipkin. See
https://github.com/open-telemetry/opentelemetry-java-instrumentation on how to
+# configure exporters and other components through system properties.
+# export HBASE_TRACE_OPTS="-Dotel.resource.attributes=service.name=HBase
-Dotel.traces.exporter=logging otel.metrics.exporter=none"
+----
+
+Uncomment this line to enable tracing. The default config is to output the
tracing data to log. Please see the documentation for
https://github.com/open-telemetry/opentelemetry-java-instrumentation[opentelemetry-java-instrumentation]
for more details on how to export tracing data to other tracing system such as
OTel collector, jaeger or zipkin, what does the _service.name_ mean, and how to
change the sampling rate, etc.
+
+NOTE: The
https://github.com/open-telemetry/opentelemetry-java/blob/v1.0.1/exporters/logging/src/main/java/io/opentelemetry/exporter/logging/LoggingSpanExporter.java[LoggingSpanExporter]
uses java.util.logging(jul) for logging tracing data, and the logger is
initialized in opentelemetry java agent, which seems to be ahead of our jul to
slf4j bridge initialization, so it will always log the tracing data to console.
We highly suggest that you use other tracing systems to collect and view t [...]
+
+=== Performance Impact
+
+According to the result in
https://issues.apache.org/jira/browse/HBASE-25658[HBASE-25658], the performance
impact is minimal. Of course the test cluster is not under heavy load, so if
you find out that enabling tracing would impact the performance, try to lower
the sampling rate. See documentation for configuring
https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md#sampler[sampler]
for more details.
+
diff --git a/src/main/asciidoc/_chapters/upgrading.adoc
b/src/main/asciidoc/_chapters/upgrading.adoc
index cf1568e..d4f9e37 100644
--- a/src/main/asciidoc/_chapters/upgrading.adoc
+++ b/src/main/asciidoc/_chapters/upgrading.adoc
@@ -634,11 +634,11 @@ The Java client API for HBase has a number of changes
that break both source and
.Tracing implementation changes
The backing implementation of HBase's tracing features was updated from Apache
HTrace 3 to HTrace 4, which includes several breaking changes. While HTrace 3
and 4 can coexist in the same runtime, they will not integrate with each other,
leading to disjoint trace information.
-The internal changes to HBase during this upgrade were sufficient for
compilation, but it has not been confirmed that there are no regressions in
tracing functionality. Please consider this feature expiremental for the
immediate future.
+The internal changes to HBase during this upgrade were sufficient for
compilation, but it has not been confirmed that there are no regressions in
tracing functionality. Please consider this feature experimental for the
immediate future.
If you previously relied on client side tracing integrated with HBase
operations, it is recommended that you upgrade your usage to HTrace 4 as well.
-After the Apache HTrace project moved to the Attic/retired, the traces in
HBase are left broken and unmaintained since HBase 2.0. A new project
link:https://issues.apache.org/jira/browse/HBASE-22120[HBASE-22120] will
replace HTrace with OpenTracing.
+After the Apache HTrace project moved to the Attic/retired, the traces in
HBase are left broken and unmaintained since HBase 2.0. A new project
link:https://issues.apache.org/jira/browse/HBASE-22120[HBASE-22120] will
replace HTrace with OpenTelemetry. It will be shipped in 3.0.0 release. Please
see the reference guide section <<tracing>> for more details.
[[upgrade2.0.hfile.compatability]]
.HFile lose forward compatability
diff --git a/src/main/asciidoc/book.adoc b/src/main/asciidoc/book.adoc
index e0df010..c264b06 100644
--- a/src/main/asciidoc/book.adoc
+++ b/src/main/asciidoc/book.adoc
@@ -86,6 +86,7 @@ include::_chapters/amv2.adoc[]
include::_chapters/zookeeper.adoc[]
include::_chapters/community.adoc[]
include::_chapters/hbtop.adoc[]
+include::_chapters/tracing.adoc[]
= Appendix
