fix(tracing): install W3C TraceContext propagator in OTLP path (#532)

## Summary

The OTLP init path never installed a text-map propagator, so katana
silently dropped inbound `traceparent` headers under that backend —
every request became a fresh root trace even when the caller had a live
trace context. The `gcloud` path installs a
`GoogleTraceContextPropagator`; OTLP was missing the equivalent W3C one.

One-line fix: add
`opentelemetry::global::set_text_map_propagator(TraceContextPropagator::new())`
in `otlp::init_tracer`.

## Why this matters

`crates/rpc/rpc-server/src/middleware/...` wraps incoming HTTP in a
`tower_http::TraceLayer` configured with `GoogleStackDriverMakeSpan`,
which calls `opentelemetry::global::get_text_map_propagator(|p|
p.extract(&HeaderExtractor(req.headers())))`. With no propagator
installed, `get_text_map_propagator` returns a `NoopTextMapPropagator`
and the extract call silently produces an empty context. Result:
`span.set_parent(cx)` is effectively a no-op, and the exported span
starts a new trace instead of chaining to the caller's.

## Repro (before this PR)

```bash
# Start jaeger v2 as an OTLP collector:
jaeger --config file:/tmp/jaeger-config.yaml  # OTLP gRPC on :4317, UI on :16686

# Start katana with OTLP:
katana --tracer.otlp --tracer.otlp-endpoint http://localhost:4317 --http.port 5055

# Send a request with a synthetic traceparent:
curl http://localhost:5055 \
  -H 'traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01' \
  -d '{"jsonrpc":"2.0","method":"starknet_chainId","id":1}'

# Check jaeger — the exported trace has a random trace_id, NOT 0af7651916cd43dd8448eb211c80319c
curl "http://localhost:16686/api/traces?service=katana&limit=1"
```

After this PR, the exported `http_request` span has
`trace_id=0af7651916cd43dd8448eb211c80319c` — the caller's context is
preserved, and any spans katana fans out downstream chain under the same
trace.

## Discovered during

Wiring distributed tracing into the cartridge sidecar services
([cartridge-gg/vrf#46](cartridge-gg/vrf#46),
[cartridge-gg/paymaster#15](cartridge-gg/paymaster#15)).
Those PRs correctly install the W3C propagator; this PR closes the gap
on the katana side so the three-service chain stitches under one
trace_id in the collector.

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kariy

crates/tracing/src/otlp.rs

@@ -1,6 +1,7 @@
 use anyhow::Result;
 use opentelemetry::trace::TracerProvider;
 use opentelemetry_otlp::SpanExporterBuilder;
+use opentelemetry_sdk::propagation::TraceContextPropagator;
 use opentelemetry_sdk::trace::{RandomIdGenerator, SdkTracerProvider};
 use opentelemetry_sdk::Resource;
 
@@ -31,6 +32,15 @@ pub fn init_tracer(otlp_config: &OtlpConfig) -> Result<opentelemetry_sdk::trace:
         .with_resource(resource)
         .build();
 
+    // Install a W3C TraceContext propagator so the `MakeSpan` used by the
+    // RPC server's `tower_http::TraceLayer` can extract inbound `traceparent`
+    // headers and chain exported spans under the caller's trace_id. Without
+    // this, every inbound request starts a fresh root trace even when the
+    // caller sent a trace context — breaking distributed tracing across
+    // services. The `gcloud` path installs its own propagator; the OTLP
+    // path was missing one.
+    opentelemetry::global::set_text_map_propagator(TraceContextPropagator::new());
+
     opentelemetry::global::set_tracer_provider(provider.clone());
 
     Ok(provider.tracer("katana"))

docs/cartridge.md

@@ -428,6 +428,77 @@ Sidecar versions are pinned in `sidecar-versions.toml` at the repository root an
 
 > Source: `crates/cli/src/sidecar/mod.rs`
 
+## Distributed tracing
+
+Katana and both sidecars (`paymaster-service`, `vrf-server`) emit OpenTelemetry spans via OTLP, so a single request that fans out from Katana through the sidecars produces one end-to-end trace in the collector.
+
+### Wire protocol
+
+| Service | Transport | Default endpoint |
+|---------|-----------|------------------|
+| `katana` | OTLP **gRPC** | `http://localhost:4317` |
+| `vrf-server` | OTLP **gRPC** | `http://localhost:4317` |
+| `paymaster-service` | OTLP **HTTP** | `http://localhost:4318/v1/traces` |
+
+Context is propagated using the W3C **TraceContext** format (`traceparent` header). Any OTLP-compatible collector that accepts both gRPC and HTTP on the standard ports (Jaeger v2, `otel-collector`, Tempo, etc.) will stitch the three services under one `trace_id`.
+
+### Enabling it
+
+**Katana:**
+```bash
+katana --tracer.otlp --tracer.otlp-endpoint http://localhost:4317 ...
+```
+
+See [`--tracer.gcloud`](../README.md) for the Google Cloud Trace alternative, which uses the `X-Cloud-Trace-Context` propagator instead of W3C.
+
+**vrf-server** (when running standalone or via `--vrf.bin`):
+```bash
+vrf-server --tracer.otlp --tracer.otlp-endpoint http://localhost:4317 ...
+```
+
+**paymaster-service** (configured via the profile JSON that katana writes in sidecar mode):
+```json
+{
+  "prometheus": {
+    "endpoint": "http://localhost:4318",
+    "token": null
+  }
+}
+```
+
+> The profile field is named `prometheus` for historical reasons but actually configures OTLP trace and metric export. Setting it to `null` disables telemetry.
+
+### What gets traced
+
+| Service | Root span | Child spans |
+|---------|-----------|-------------|
+| `katana` | `http_request` (tower-http) | `rpc_call`, `db_get`, `db_put`, `db_txn_ro_create`, stage/pipeline spans |
+| `paymaster-service` | `http_request` (tower-http) | `paymaster_health`, `paymaster_buildTransaction`, `paymaster_executeTransaction`, `paymaster_executeRawTransaction`, ... (from `#[instrument]` on each RPC method) |
+| `vrf-server` | `http_request` (tower-http) | handler-level spans when `#[instrument]` is applied (not wired by default) |
+
+Inbound `traceparent` headers are extracted by a `tower_http::TraceLayer` with a custom `MakeSpan` that calls the globally installed text-map propagator. Outbound HTTP calls between services (Katana -> paymaster, CartridgeApi -> vrf-server) do not yet inject `traceparent` automatically — callers that want full chain visibility must set the header themselves, or the service will start a fresh root span.
+
+### End-to-end example
+
+```bash
+# Start an OTLP collector (Jaeger v2 shown here — UI on :16686):
+jaeger --config file:/path/to/jaeger-config.yaml
+
+# Start katana with OTLP tracing:
+katana --chain-id SN_SEPOLIA \
+       --paymaster --cartridge.paymaster --vrf \
+       --tracer.otlp --tracer.otlp-endpoint http://localhost:4317
+
+# Send a request with a synthesized W3C trace context:
+curl http://localhost:5050 \
+  -H 'traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01' \
+  -d '{"jsonrpc":"2.0","method":"cartridge_addExecuteOutsideTransaction","params":[...],"id":1}'
+
+# All three services emit spans under trace_id 0af7651916cd43dd8448eb211c80319c.
+```
+
+> Source: `crates/tracing/src/otlp.rs`, `crates/tracing/src/gcloud.rs`; [cartridge-gg/vrf#46](https://github.com/cartridge-gg/vrf/pull/46), [cartridge-gg/paymaster#15](https://github.com/cartridge-gg/paymaster/pull/15)
+
 ## Error codes
 
 | Code | Variant | Message |

sidecar-versions.toml

@@ -1,9 +1,9 @@
 [paymaster-service]
 repo = "https://github.com/cartridge-gg/paymaster"
-rev = "4748365"
+rev = "8fc62f26f88cbe150b28104faa158af9188606ab"
 package = "paymaster-service"
 
 [vrf-server]
 repo = "https://github.com/cartridge-gg/vrf.git"
-rev = "6d1c0f60a53558f19618b2bff81c3da0849db270"
+rev = "d7a1f9a81e19ed565d3c6a7c2dae586b6413c615"
 package = "vrf-server"