logging-tracing-capture

Lambda X-Ray Capture & CDK

Tracing AWS SDK Clients

// src/shared/clients/dynamodb.ts

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
import { tracer } from "@/shared/tracer";

let docClient: DynamoDBDocumentClient | undefined;

export function getDynamoDBClient(): DynamoDBDocumentClient {
  if (!docClient) {
    const client = new DynamoDBClient({});
    
    // Capture AWS SDK calls in X-Ray
    tracer.captureAWSv3Client(client);
    
    docClient = DynamoDBDocumentClient.from(client);
  }

  return docClient;
}

Tracing HTTP Clients (External APIs)

// src/shared/clients/http-client.ts

import { tracer } from "@/shared/tracer";
import { getRequestContext } from "@/shared/observability/request-context";
import { logger } from "@/shared/logger";

interface HttpRequestOptions {
  method: "GET" | "POST" | "PUT" | "DELETE";
  url: string;
  headers?: Record<string, string>;
  body?: unknown;
  timeout?: number;
}

export async function tracedFetch<T>(options: HttpRequestOptions): Promise<T> {
  const context = getRequestContext();
  const segment = tracer.getSegment();
  const subsegment = segment?.addNewSubsegment(`HTTP ${options.method} ${new URL(options.url).hostname}`);

  const startTime = Date.now();

  try {
    // Add trace context to outgoing request
    const headers: Record<string, string> = {
      ...options.headers,
      "X-Correlation-Id": context?.correlationId ?? "",
    };

    // Propagate X-Ray trace header for downstream tracing
    if (process.env._X_AMZN_TRACE_ID) {
      headers["X-Amzn-Trace-Id"] = process.env._X_AMZN_TRACE_ID;
    }

    subsegment?.addAnnotation("correlationId", context?.correlationId ?? "unknown");
    subsegment?.addAnnotation("url", options.url);
    subsegment?.addAnnotation("method", options.method);
    subsegment?.addMetadata("requestHeaders", headers);

    const response = await fetch(options.url, {
      method: options.method,
      headers,
      body: options.body ? JSON.stringify(options.body) : undefined,
      signal: options.timeout ? AbortSignal.timeout(options.timeout) : undefined,
    });

    const duration = Date.now() - startTime;

    subsegment?.addAnnotation("statusCode", response.status);
    subsegment?.addMetadata("responseHeaders", Object.fromEntries(response.headers));

    logger.info({
      correlationId: context?.correlationId,
      url: options.url,
      method: options.method,
      statusCode: response.status,
      durationMs: duration,
    }, "External HTTP request completed");

    if (!response.ok) {
      const error = new Error(`HTTP ${response.status}: ${response.statusText}`);
      subsegment?.addError(error);
      throw error;
    }

    return response.json() as Promise<T>;
  } catch (error) {
    subsegment?.addError(error as Error);
    logger.error({
      correlationId: context?.correlationId,
      url: options.url,
      err: error,
    }, "External HTTP request failed");
    throw error;
  } finally {
    subsegment?.close();
  }
}