AWSAWS Certified Generative AI Developer - Professional2026-102.4 Implement FM API integrations
Join inference failures across service boundaries
Completed by the knowledge check
Learning objective
Correlate FM requests and tool integration failures across services with AWS X-Ray traces and request identifiers.
Core idea
A failed answer is a symptom of a distributed request, not necessarily a failed foundation model (FM). The gateway can reject admission, inference can fail, a tool can time out, or post-processing can reject an otherwise successful response. Correlation connects these events to one logical operation while preserving the distinct service calls and attempts that caused them.
Use traces to reconstruct timing and parent-child relationships, and request identifiers to find the corresponding service records. Neither replaces the other. Traces are sampled, and each service can assign its own request identifier. A durable application correlation identifier keeps investigation possible when no complete trace exists.
How it works
Distinguish the identifiers
An X-Ray trace groups related segments and subsegments. Its trace context travels in the X-Amzn-Trace-Id header, which can include Root, Parent, and Sampled. The root identifies the trace; parent context connects the next segment to its caller; the sampling decision governs trace recording. These fields are not a customer’s authentication credentials or a deduplication key.
API Gateway provides two useful REST API request identifiers. $context.requestId corresponds to the x-amzn-RequestId value. A caller can override it with a valid UUID. $context.extendedRequestId is generated by API Gateway and cannot be supplied or overridden by the caller; it is returned in x-amz-apigw-id.
Include both in access logs, as AWS recommends. Also include $context.xrayTraceId to join the gateway record to an available X-Ray trace. For an AWS service integration, include $context.integration.requestId, equivalent to $context.awsEndpointRequestId, to record the AWS endpoint’s request ID in the same access-log line. This joins the gateway request to the integrated service’s own request record; it does not identify every subsequent call inside an application backend. A client-controlled request ID alone is weak evidence that two records belong to the same request, especially when callers accidentally reuse identifiers.
Create an application correlation ID at your trusted ingress and carry it through model and tool operations. Give each invocation attempt its own attempt ID. These are application-defined fields. The logical correlation ID remains stable across recovery, while the attempt ID distinguishes a failed first call from a successful retry. See 2.4.2 for durable job correlation and completion tracking.
Enable recording at the participating services
API Gateway X-Ray tracing supports REST APIs, including Regional, edge-optimized, and private endpoint types. It does not provide the same managed tracing support for HTTP APIs. Enable active tracing on the REST API stage so API Gateway samples incoming requests and sends trace segments.
API Gateway adds an X-Ray tracing header to incoming requests that lack one. With active tracing disabled, it can still record a segment when an upstream service supplies a sampled trace. Therefore, seeing a trace for one request does not prove that stage-level active tracing is enabled or that every request has coverage.
For Lambda, configure TracingConfig.Mode as Active when the function must automatically send traces for sampled invocations. AWS documents that PassThrough propagates context but does not automatically send traces, even when an upstream header says to sample. AWS explicitly notes that this differs from its previous passive-tracing behavior. Do not rely on a sampled API Gateway header alone to make a PassThrough function emit its own trace.
Managed service segments also do not explain every operation inside your handler. Instrument model SDK calls, tool HTTP calls, and meaningful application processing so they produce downstream spans or subsegments. Otherwise, one broad Lambda duration can conceal whether time was spent in inference, a tool, or validation.
Keep X-Ray while choosing supported instrumentation
The objective names X-Ray, but X-Ray’s tracing backend and its language SDKs have different lifecycles. AWS’s SDK and daemon support timeline places those instrumentation components in maintenance mode from February 25, 2026, with releases limited to security issues. That statement does not declare the X-Ray service retired.
AWS recommends OpenTelemetry instrumentation. AWS Distro for OpenTelemetry can export OpenTelemetry traces as X-Ray segments. Choose the instrumentation appropriate to your runtime, configure propagation across participating boundaries, and verify that the exported spans form the intended trace. A language SDK installed in one service does not automatically instrument every downstream application.
X-Ray calls its indexed key-value fields annotations and its unindexed detail fields metadata. X-Ray indexes up to 50 annotations per trace. Use a small set of useful annotation fields, such as route class or failure stage, when you need trace filtering. Keep detailed diagnostic context in metadata or structured logs according to your data policy. For OpenTelemetry exporters, verify the attribute mapping rather than assuming every arbitrary span attribute becomes an indexed X-Ray annotation.
Record attempts and classify the failing boundary
Emit structured application records around each model and tool call. Include the application correlation ID, attempt ID, trace ID when available, selected route, operation name, elapsed time, outcome, and downstream request identifier when the service returns one. Use separate fields for separate identifiers; do not overwrite the logical correlation ID with whichever service responded last.
X-Ray distinguishes client Error events, server Fault events, and Throttle events for 429 responses. These transport categories help investigation but do not express every application failure. A tool might return HTTP success with an unusable business result. Record that validation failure in the application span and logs rather than concluding that the integration succeeded because no transport error appeared.
Tracing is sampled, so absence of a span is not proof that a call never happened. Preserve structured records for the outcomes you must audit independently of trace sampling. Avoid putting prompts, tool credentials, or retrieved documents into trace attributes merely to make the trace look complete. Identifiers and bounded diagnostic fields usually support the join without duplicating sensitive payloads.
Key distinctions and trade-offs
The following evidence serves different purposes:
| Evidence | What it establishes | What it cannot establish alone |
|---|---|---|
| X-Ray trace | Recorded call relationships, timing, and errors | Complete coverage of every request |
| Gateway request IDs | A particular gateway request record | Identity of every downstream attempt |
| Application correlation ID | One logical operation across boundaries | Which individual retry failed |
| Attempt ID and downstream request ID | A specific call and its service evidence | The whole user-visible operation |
More trace detail improves diagnosis but increases telemetry volume and data exposure. Choose fields from actual investigation questions, and test whether they join across the gateway, inference adapter, and tool boundary.
Architecture / decision scenario
A support assistant runs behind a REST API and invokes a model before calling an order-status tool. Customers report intermittent failed answers. The gateway returns an extended request ID, and its access log joins that ID to an X-Ray trace and the application’s correlation ID.
The team enables active tracing on the API stage and Lambda function, and exports instrumented downstream spans to X-Ray. A sampled trace shows that inference succeeded, the first order-tool attempt returned a server failure, and the retry exceeded the application’s remaining deadline. The parent request’s failure was therefore a tool-recovery failure, not a model-quality regression.
Each tool attempt has a distinct application attempt ID and records the tool’s request identifier when available. Operations uses those records to inspect the tool’s own logs. It does not group the first failure and retry into one overwritten record.
For an unsampled customer request, the team follows the gateway IDs and structured application records instead. During instrumentation migration, it verifies that OpenTelemetry exports preserve the same causal path. It also tests Lambda Active explicitly, because the prior assumption that PassThrough would automatically emit sampled function traces no longer matches AWS’s documented behavior.
Common exam traps
- Treating a trace ID, request ID, and idempotency key as interchangeable.
- Assuming clients cannot override API Gateway’s basic request ID.
- Expecting managed API Gateway X-Ray tracing for HTTP APIs.
- Relying on Lambda
PassThroughto emit traces automatically. - Treating missing sampled spans as proof that no downstream call occurred.
- Assuming X-Ray SDK maintenance means the X-Ray service is retired.
What to remember
Join the logical operation, each attempt, and each service request without collapsing their identifiers. Enable recording and instrument downstream calls, not only ingress. Preserve logs for unsampled failures. Use supported OpenTelemetry instrumentation with X-Ray when appropriate, and distinguish model, tool, transport, and validation failures before choosing a remedy.
Knowledge check
One customer request makes two model attempts and then calls an order-status tool. The second model attempt succeeds and the tool times out. Which identifiers should the application records carry so that operators can find both the whole operation and the call that failed?
An investigator must tie a REST API gateway record to one specific request, but some clients set their own x-amzn-RequestId, and a few reuse the same value. Which access-log field identifies the request reliably?
$context.requestId , which matches the x-amzn-RequestId value$context.extendedRequestId , which API Gateway generates for the request$context.xrayTraceId , which every request carries in its trace header$context.integration.requestId , which the backend returns for the call$context.requestId , so reused values make it weak evidence. API Gateway generates $context.extendedRequestId and callers cannot set it. Trace IDs depend on sampling, and the integration request ID identifies the integrated AWS service’s request, not the gateway’s.A REST API stage has active tracing, and sampled traces show the gateway segment, but no segment ever appears for the Lambda function behind it. The function’s TracingConfig.Mode is PassThrough. What explains this?
PassThrough propagates trace context but does not send traces itselfPassThrough mode, Lambda forwards the tracing header but does not send traces automatically, even when the header says to sample. Set the mode to Active , and instrument the model and tool calls inside the handler so their time appears as separate spans.A customer reports one failed answer, and X-Ray holds no trace for that request. What should the team conclude, and where should it look?
An order-status tool returns HTTP 200 with a body that fails the application’s business validation. The X-Ray trace shows no Error, Fault or Throttle for the call, and the customer receives a failed answer. How should the failure be recorded?
Error , by returning HTTP 400 from the tool adapterError , Fault and Throttle events classify transport outcomes; an unusable business result inside a 200 is not one of them. The application records the validation failure at the tool boundary so the cause is attributed correctly, rather than blaming the model or rewriting the transport status.