From 3edb27fd92098951a60a61b9fab542e07bfad53c Mon Sep 17 00:00:00 2001 From: Francis Bogsanyi Date: Wed, 7 Feb 2024 14:16:57 -0500 Subject: [PATCH] Update README --- propagator/vitess/README.md | 57 +++++++++---------------------------- 1 file changed, 13 insertions(+), 44 deletions(-) diff --git a/propagator/vitess/README.md b/propagator/vitess/README.md index 859ce8dd8..d95561637 100644 --- a/propagator/vitess/README.md +++ b/propagator/vitess/README.md @@ -3,48 +3,19 @@ The `opentelemetry-propagator-vitess` gem contains injectors and extractors for the [Vitess context propagation format][vitess-spec]. -## OT Trace Format +## Vitess trace context Format -| Header Name | Description | Required | -| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | -| `ot-tracer-traceid` | 64-bit; 16 hex digits (extract and inject) or 128-bit; 32 hex digits (extract) | yes | -| `ot-tracer-spanid` | 64-bit; 16 hex digits | yes | -| `ot-tracer-sampled` | boolean or bit encoded as a string with the values `'true'`,`'false'`, `'1'`, or `'0'` | no | -| `ot-baggage-*` | repeated string to string key-value baggage items; keys are prefixed with `ot-baggage-` and the corresponding value is the raw string. | if baggage is present | +Vitess encodes trace context in a special SQL comment style. The format is a base64 string encoding of a JSON object that, at it simplest, looks something like this: -### Sampled Flag vs Bit - -The `ot-tracer-sampled` header is a `boolean` encoded string however the Golang SDK incorrectly sets the `ot-tracer-sampled` header to a `bit` flag. -This and other language SDKs compensate for this by supporting both a `bit` and `boolean` encoded strings upon extraction: - -- [Java](https://github.com/open-telemetry/opentelemetry-java/blob/9cea4ef1f92d3186b1bd8296e9daac4281c0f759/extensions/trace-propagators/src/main/java/io/opentelemetry/extension/trace/propagation/Common.java#L41) -- [Golang](https://github.com/open-telemetry/opentelemetry-go-contrib/blob/b72c2cd63b9a9917554cbcd709e61f5d8541eea5/propagators/ot/ot_propagator.go#L118) - -This issue was [fixed](https://github.com/open-telemetry/opentelemetry-go-contrib/pull/1358) however this SDK supports both for backward compatibility with older versions of the Golang propagator. - -### Interop and trace ids - -Vitess was changed to be interoperable with other format so it is supposed to 8 or 16 byte array values for the trace-id. - -In order to do that Lightstep released a version of the Vitess propagators in OpenTracing SDKs that left padded 64-bit headers to 128-bits using an additional 64-bit of 0s. - -The reality of the world is not every application upgraded to support 16 byte array propagation format, but this propagator must still convert legacy 64-bit trace ids to match the W3C Trace Context Trace ID 16 byte array. - -In addition to that it must be interoperable with legacy Vitessrs, which expect 64-bit headers so this propagator truncates the value from a 128-bit to a 64-bit value before inject it into the carrier. - -This propagator is compatible with 64-bit or 128-bit trace ids when extracting the parent context, however it truncates the trace ids down to 64-bit trace ids when injecting the context. - -### Baggage Notes +```json +{"uber-trace-id":"{trace-id}:{span-id}:{parent-span-id}:{flags}"} +``` -Baggage keys and values are validated according to [rfc7230][rfc7230-url]. Any -keys or values that would result in invalid HTTP headers will be silently -dropped during inject. +To inform Vitess of the trace context, the context is prepended to a SQL query, e.g.: -OT Baggage is represented as multiple headers where the -names are carrier dependent. For this reason, they are omitted from the `fields` -method. This behavior should be taken into account if your application relies -on the `fields` functionality. See the [specification][fields-spec-url] for -more details. +```sql +/*VT_SPAN_CONTEXT=*/ SELECT * from product; +``` ## What is OpenTelemetry? @@ -54,7 +25,7 @@ OpenTelemetry provides a single set of APIs, libraries, agents, and collector se ## How does this gem fit in? -This gem can be used with any OpenTelemetry SDK implementation. This can be the official `opentelemetry-sdk` gem or any other concrete implementation. +This gem can be used with any OpenTelemetry SDK implementation. This can be the official `opentelemetry-sdk` gem or any other concrete implementation. It is intended to be used with SQL client instrumentation, such as the `opentelemetry-instrumentation-trilogy` gem. ## How do I get started? @@ -66,10 +37,10 @@ gem install opentelemetry-propagator-vitess Or, if you use [bundler][bundler-home], include `opentelemetry-propagator-vitess` in your `Gemfile`. -Configure your application to use this propagator by setting the following [environment variable][envars]: +Configure your application to use this propagator with the Trilogy client instrumentation by setting the following [environment variable][envars]: ``` -OTEL_PROPAGATORS=vitess +OTEL_RUBY_INSTRUMENTATION_TRILOGY_PROPAGATOR=vitess ``` ## How can I get involved? @@ -89,7 +60,5 @@ The `opentelemetry-propagator-vitess` gem is distributed under the Apache 2.0 li [ruby-sig]: https://github.com/open-telemetry/community#ruby-sig [community-meetings]: https://github.com/open-telemetry/community#community-meetings [discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions -[vitess-spec]: https://github.com/opentracing/specification/blob/master/rfc/trace_identifiers.md -[rfc7230-url]: https://tools.ietf.org/html/rfc7230#section-3.2 -[fields-spec-url]: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/context/api-propagators.md#fields +[vitess-spec]: https://vitess.io/docs/16.0/user-guides/configuration-advanced/tracing/#instrumenting-queries [envars]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md#general-sdk-configuration