Hi Phoenix Community,
Following up on the earlier discussion around HTrace removal (
https://lists.apache.org/thread/6y61s9j8yk1gpznwj0g4ptgv6l1h8jyz), HTrace
has been abandoned for years and HBase has already completed its own
migration to OpenTelemetry (HBASE-22120). Phoenix still carries HTrace as a
dependency, and its tracing infrastructure is effectively non-functional.
I would like to volunteer to work on PHOENIX-5215 : migrating Phoenix's
distributed tracing from the deprecated HTrace library to OpenTelemetry. (
https://issues.apache.org/jira/browse/PHOENIX-5215)
*High-level architecture:*
Phoenix will depend only on opentelemetry-api at compile time (no SDK
bundled). A single new facade class *PhoenixTracing.java* modeled after
HBase's TraceUtil, will centralize all tracing calls (createSpan, trace,
wrap, withTracing, etc. At runtime, the OpenTelemetry Java Agent shipped by
HBase provides the SDK implementation. When the agent is not attached, all
OTel API calls are no-ops with zero overhead. Since Phoenix runs inside
HBase's JVM as coprocessors, Phoenix spans automatically join HBase's trace
pipeline, giving operators unified end-to-end traces (Phoenix query → HBase
RPC → region scan) in any OTLP-compatible backend (Jaeger, Grafana Tempo,
Zipkin, etc.) with no Phoenix-specific configuration required.
*Proposed approach:*
1. Remove HTrace Maven dependency : Drop HTrace from all POMs and ban it
via maven-enforcer-plugin.
2. Add stub classes : Introduce lightweight no-op stub implementations
for the removed HTrace types so existing code continues to compile without
build failures during the transition.
3. Add OpenTelemetry API dependency : Add
opentelemetry-api compile-time only, no SDK to the root and module POMs.
4. Create PhoenixTracing.java facade : A thin wrapper over the OTel API
following HBase's TraceUtil pattern, providing createSpan(), trace(),
wrap(), withTracing(), isRecording(), etc.
5. Migrate client & server code : Replace all HTrace stub usage across ~
files (PhoenixConnection, MutationState, BaseQueryPlan, TracingIterator,
IndexRegionObserver, Indexer, etc.) with PhoenixTracing calls using proper
span lifecycle (create → makeCurrent → end).
6. Delete old trace infrastructure : Remove the stub classes, old
Tracing.java/NullSpan.java/TracingUtils.java utilities, TraceWriter,
TraceSpanReceiver, TraceReader, PhoenixMetricsSink, and related test
classes.
7. Update tests & docs : Rewrite tracing tests for OTel's
InMemorySpanExporter and update operator documentation.
I would like to volunteer on this migration and would greatly appreciate
any feedback or suggestions you may have.
Thanks,
Xavier Fernandis
