[hbase] 16/18: HBASE-26139 Backport HBASE-23762 "Add documentation on how to enable and view tracing with OpenTelemetry" to branch-2 (#3629)
This is an automated email from the ASF dual-hosted git repository. taklwu pushed a commit to branch branch-2 in repository https://gitbox.apache.org/repos/asf/hbase.git commit 65b5b9b2a867957232719005740bf30ac988accb Author: Tak Lon (Stephen) Wu 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 Signed-off-by: Duo Zhang --- 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 000..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
[hbase] 16/18: HBASE-26139 Backport HBASE-23762 "Add documentation on how to enable and view tracing with OpenTelemetry" to branch-2 (#3629)
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 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 Signed-off-by: Duo Zhang --- 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 000..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
