Introduction

An X-Ray trace without subsegments is only partially useful. It tells you a request existed, but not which downstream database call, HTTP request, Lambda invocation, or other operation consumed the time. When subsegments are missing, the issue is usually not “X-Ray is broken” in the abstract. It is that the application did not instrument the path, lost context across async boundaries, or never delivered the downstream trace data correctly.

Symptoms

  • The X-Ray console shows only the top-level segment
  • Expected downstream service calls do not appear in the trace timeline
  • Async or threaded code seems especially under-instrumented
  • The trace exists, but latency analysis is too shallow to identify the slow component

Common Causes

  • The X-Ray SDK is not patching or wrapping the libraries that perform downstream work
  • Trace context is lost in async, threaded, or background execution
  • The X-Ray daemon or agent path is unavailable or misconfigured
  • The application only creates the root segment and never starts subsegments for downstream operations

Step-by-Step Fix

  1. 1.Verify the X-Ray daemon or delivery path is healthy
  2. 2.If the app cannot send trace data out, subsegments may never appear even if the code creates them.
  3. 3.Check whether the SDK is actually instrumenting the libraries you use
  4. 4.A root segment alone often means the downstream client code was never patched or wrapped.
  5. 5.Review async and background execution boundaries
  6. 6.Context propagation breaks easily when work moves outside the request thread or process that created the root segment.
  7. 7.Add explicit subsegment instrumentation where needed
  8. 8.If automatic patching does not cover the code path, create and close the subsegment yourself around the downstream operation.

Prevention

  • Verify instrumentation coverage for the actual libraries and async model in use
  • Test X-Ray visibility on real downstream calls, not only on root request traces
  • Monitor X-Ray agent or daemon health alongside application tracing
  • Treat missing subsegments as an observability regression worth alerting on