OpenTelemetry Tracing for Jetty Edge

Status: Implemented

Overview

Distributed tracing for the Jetty edge server and tunnel agent using OpenTelemetry. Traces follow the W3C Trace Context (traceparent) standard and flow from the public HTTP request through the WebSocket tunnel to the PHP agent and back.

Architecture

Browser/Client
  |  traceparent header (optional)
  v
jetty-edge (Go)
  |  Start span "edge.http_request"
  |  Extract or generate traceparent
  |  Pass trace_parent in WS http_request frame
  v
WebSocket tunnel
  v
PHP EdgeAgent
  |  Read trace_parent from frame
  |  Set traceparent header on upstream curl request
  |  Include trace_parent in http_response frame
  v
Local upstream (Laravel, etc.)

Configuration

When OTEL_EXPORTER_OTLP_ENDPOINT is not set, the tracer is a no-op with zero overhead.

Components

1. Tracing package (cli/internal/tracing/tracing.go)

• Init() / InitFromConfig() -- create a Tracer from env or explicit config
• StartSpan(ctx, tracer, name, traceparent) -- begin a span, parse incoming traceparent
• EndSpan(span) -- finish span, record duration
• Span.Traceparent() -- format W3C traceparent for propagation
• No-op when OTLP endpoint is not configured

2. Edge server integration (cli/internal/edge/edge.go)

• Config.OTLPEndpoint and Config.TraceSampleRate fields
• ListenAndServe: initialize tracer, defer shutdown
• handlePublicHTTP: start span, add attributes, propagate via frame

3. Wire protocol (cli/internal/wsproto/proto.go)

• HTTPRequest.TraceParent field (json: trace_parent,omitempty)
• HTTPResponse.TraceParent field (json: trace_parent,omitempty)

4. PHP EdgeAgent (jetty-client/src/EdgeAgent.php)

• Read trace_parent from http_request frame
• Set traceparent header on upstream curl request
• Return trace_parent in http_response frame

Span attributes

The edge.http_request span includes:

• http.method -- request method
• http.target -- request path
• http.status_code -- response status
• jetty.subdomain -- tunnel subdomain
• jetty.request_id -- internal request ID

Future work

• Add OTEL SDK dependencies to go.mod (currently stubbed with TODO comments)
• Span export batching and retry configuration
• Baggage propagation for custom metadata
• PHP-side span creation (requires PHP OTEL extension)