Update README

open-telemetry · Feb 7, 2024 · 3edb27f · 3edb27f
1 parent 2b3dea0
commit 3edb27f
Showing 1 changed file with 13 additions and 44 deletions.
diff --git 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=<base64 value>*/ 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