Type Definitions

/**
 * Options for the tracer class to be used during initialization
 */
interface TracerOptions {
  /** Enable or disable tracing (default: true in Lambda, false otherwise) */
  enabled?: boolean;

  /** Service name for traces (can also be set via POWERTOOLS_SERVICE_NAME env var) */
  serviceName?: string;

  /** Whether to trace outgoing HTTP requests made with http, https, or fetch (default: true) */
  captureHTTPsRequests?: boolean;

  /** Custom configuration service for advanced use cases */
  customConfigService?: ConfigServiceInterface;
}

/**
 * Options for handler decorators and middleware
 */
interface CaptureLambdaHandlerOptions {
  /** Whether to capture the Lambda handler response as subsegment metadata (default: true) */
  captureResponse?: boolean;
}

/**
 * Options for method decorators
 */
interface CaptureMethodOptions {
  /** Set a custom name for the subsegment (default: ### methodName) */
  subSegmentName?: string;

  /** Disable response serialization as subsegment metadata (default: true) */
  captureResponse?: boolean;
}

/**
 * Complete interface for the Tracer class
 */
interface TracerInterface {
  /** Add error to segment as metadata */
  addErrorAsMetadata(error: Error, remote?: boolean): void;

  /** Add response data to segment as metadata */
  addResponseAsMetadata(data?: unknown, methodName?: string): void;

  /** Add service name annotation to segment */
  addServiceNameAnnotation(): void;

  /** Add cold start annotation to segment */
  annotateColdStart(): void;

  /** @deprecated Capture AWS SDK v2 */
  captureAWS<T>(aws: T): undefined | T;

  /** Capture AWS SDK v3 client */
  captureAWSv3Client<T>(service: T): undefined | T;

  /** @deprecated Capture AWS SDK v2 client */
  captureAWSClient<T>(service: T): undefined | T;

  /** Decorator for Lambda handler */
  captureLambdaHandler(options?: CaptureLambdaHandlerOptions): HandlerMethodDecorator;

  /** Decorator for class methods */
  captureMethod<T extends AnyClass>(options?: CaptureMethodOptions): MethodDecorator<T>;

  /** Get current segment or subsegment */
  getSegment(): Segment | Subsegment | undefined;

  /** Get root X-Ray trace ID */
  getRootXrayTraceId(): string | undefined;

  /** Check if current trace is sampled */
  isTraceSampled(): boolean;

  /** Check if tracing is enabled */
  isTracingEnabled(): boolean;

  /** Add annotation to segment */
  putAnnotation: (key: string, value: string | number | boolean) => void;

  /** Add metadata to segment */
  putMetadata: (
    key: string,
    value: unknown,
    namespace?: string | undefined
  ) => void;

  /** Set active segment or subsegment */
  setSegment(segment: Segment | Subsegment): void;
}

/**
 * Type representing any class constructor
 */
type AnyClass = new (...args: any[]) => any;

/**
 * Type representing any class method
 */
type AnyClassMethod = (...args: any[]) => any;

/**
 * Type for method decorators
 */
type MethodDecorator<T extends AnyClass> = (
  target: InstanceType<T>,
  propertyKey: string | symbol,
  descriptor: TypedPropertyDescriptor<AnyClassMethod>
) => void;

/**
 * Type for Lambda handler method decorators
 */
type HandlerMethodDecorator = (
  target: unknown,
  propertyKey: string | symbol,
  descriptor: PropertyDescriptor
) => void;

/**
 * Interface for the provider service
 */
interface ProviderServiceInterface {
  /** Get the X-Ray namespace */
  getNamespace(): Namespace;

  /** Get the current segment or subsegment */
  getSegment(): Segment | Subsegment | undefined;

  /** Set the current segment or subsegment */
  setSegment(segment: Segment | Subsegment): void;

  /** Set the X-Ray logger */
  setLogger(logObj: unknown): void;

  /** Set the X-Ray daemon address */
  setDaemonAddress(address: string): void;

  /** Set the context missing strategy */
  setContextMissingStrategy(strategy: ContextMissingStrategy): void;

  /** @deprecated Capture AWS SDK v2 */
  captureAWS<T>(awsservice: T): T;

  /** @deprecated Capture AWS SDK v2 client */
  captureAWSClient<T>(awsservice: T): T;

  /** Capture AWS SDK v3 client */
  captureAWSv3Client<T>(awsservice: T): T;

  /** Capture async function with subsegment */
  captureAsyncFunc(
    name: string,
    fcn: (subsegment?: Subsegment) => unknown,
    parent?: Segment | Subsegment
  ): unknown;

  /** Capture sync function with subsegment */
  captureFunc(
    name: string,
    fcn: (subsegment?: Subsegment) => unknown,
    parent?: Segment | Subsegment
  ): unknown;

  /** Capture all HTTP(s) requests globally */
  captureHTTPsGlobal(): void;

  /** Instrument fetch requests with AWS X-Ray */
  instrumentFetch(): void;

  /** Put annotation on current segment */
  putAnnotation(key: string, value: string | number | boolean): void;

  /** Put metadata on current segment */
  putMetadata(key: string, value: unknown, namespace?: string): void;
}

/**
 * Strategy for handling missing X-Ray context
 */
type ContextMissingStrategy =
  | 'LOG_ERROR'
  | 'RUNTIME_ERROR'
  | 'IGNORE_ERROR'
  | ((msg: string) => void);

/**
 * Subsegment that contains information for a request made to a remote service
 */
interface HttpSubsegment extends Subsegment {
  /** Namespace is always 'remote' for HTTP subsegments */
  namespace: 'remote';

  /** HTTP request and response information */
  http: {
    request?: {
      /** Full URL of the request */
      url: string;
      /** HTTP method (GET, POST, etc.) */
      method?: string;
    };
    response?: {
      /** HTTP status code */
      status: number;
      /** Response content length in bytes */
      content_length?: number;
    };
  };
}

/**
 * Interface for custom configuration service
 *
 * Extends the base ConfigServiceInterface from @aws-lambda-powertools/commons
 */
interface ConfigServiceInterface extends ConfigServiceBaseInterface {
  /** Get the AWS_EXECUTION_ENV environment variable */
  getAwsExecutionEnv(): string;

  /** Get the POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS environment variable */
  getCaptureHTTPsRequests(): string;

  /** Get the AWS_SAM_LOCAL environment variable */
  getSamLocal(): string;

  /** Get the POWERTOOLS_TRACE_ENABLED environment variable */
  getTracingEnabled(): string;

  /** Get the POWERTOOLS_TRACER_CAPTURE_RESPONSE environment variable */
  getTracingCaptureResponse(): string;

  /** Get the POWERTOOLS_TRACER_CAPTURE_ERROR environment variable */
  getTracingCaptureError(): string;
}

/**
 * X-Ray Segment represents the root trace
 *
 * In Lambda, the facade segment is created automatically by AWS
 */
interface Segment {
  /** Add a new subsegment to this segment */
  addNewSubsegment(name: string): Subsegment;

  /** Close the segment */
  close(): void;

  /** Other X-Ray SDK methods available but not commonly used */
  [key: string]: any;
}

/**
 * X-Ray Subsegment represents a child trace
 *
 * Created manually or by decorators/middleware
 */
interface Subsegment {
  /** Subsegment ID */
  id: string;

  /** Subsegment name */
  name: string;

  /** Parent segment or subsegment */
  parent?: Segment | Subsegment;

  /** Whether this subsegment is not traced */
  notTraced?: boolean;

  /** Add a new subsegment to this subsegment */
  addNewSubsegment(name: string): Subsegment;

  /** Close the subsegment */
  close(): void;

  /** Add an attribute to the subsegment */
  addAttribute(key: string, value: any): void;

  /** Add an error to the subsegment */
  addError(error: Error, remote: boolean): void;

  /** Add error flag without error details */
  addErrorFlag(): void;

  /** Other X-Ray SDK methods available but not commonly used */
  [key: string]: any;
}

/**
 * Continuation Local Storage namespace for X-Ray context
 *
 * Used internally by the provider service
 */
interface Namespace {
  /** Internal CLS methods - not typically used directly */
  [key: string]: any;
}

/**
 * Middy-like middleware object
 */
interface MiddlewareLikeObj {
  /** Hook called before handler execution */
  before?: (request: MiddyLikeRequest) => void | Promise<void>;

  /** Hook called after handler execution */
  after?: (request: MiddyLikeRequest) => void | Promise<void>;

  /** Hook called on handler error */
  onError?: (request: MiddyLikeRequest) => void | Promise<void>;
}

/**
 * Middy-like request object
 */
interface MiddyLikeRequest {
  /** Lambda event */
  event: any;

  /** Lambda context */
  context: any;

  /** Handler response */
  response: any;

  /** Handler error */
  error?: Error;

  /** Internal middleware state */
  internal?: Record<string, any>;
}

import { Tracer } from '@aws-lambda-powertools/tracer';
import type {
  TracerOptions,
  TracerInterface,
  CaptureLambdaHandlerOptions,
  CaptureMethodOptions
} from '@aws-lambda-powertools/tracer/types';
import type { Segment, Subsegment } from 'aws-xray-sdk-core';

// Typed tracer options
const options: TracerOptions = {
  serviceName: 'myService',
  enabled: true,
  captureHTTPsRequests: true
};

const tracer: TracerInterface = new Tracer(options);

// Typed handler options
const handlerOptions: CaptureLambdaHandlerOptions = {
  captureResponse: false
};

// Typed method options
const methodOptions: CaptureMethodOptions = {
  subSegmentName: 'customName',
  captureResponse: true
};

// Working with segments
function processWithSegment(): void {
  const segment: Segment | Subsegment | undefined = tracer.getSegment();

  if (segment) {
    const subsegment: Subsegment = segment.addNewSubsegment('myOperation');
    tracer.setSegment(subsegment);

    try {
      // Process logic
    } finally {
      subsegment.close();
      tracer.setSegment(segment);
    }
  }
}

import type { ConfigServiceInterface } from '@aws-lambda-powertools/tracer/types';

class CustomConfigService implements ConfigServiceInterface {
  getAwsExecutionEnv(): string {
    return process.env.AWS_EXECUTION_ENV || '';
  }

  getCaptureHTTPsRequests(): string {
    return process.env.CAPTURE_HTTPS || 'true';
  }

  getSamLocal(): string {
    return process.env.AWS_SAM_LOCAL || '';
  }

  getTracingEnabled(): string {
    return process.env.TRACING_ENABLED || 'true';
  }

  getTracingCaptureResponse(): string {
    return process.env.CAPTURE_RESPONSE || 'true';
  }

  getTracingCaptureError(): string {
    return process.env.CAPTURE_ERROR || 'true';
  }

  getServiceName(): string {
    return process.env.SERVICE_NAME || 'default';
  }

  // Other required methods from ConfigServiceBaseInterface
  // ...
}

const tracer = new Tracer({
  customConfigService: new CustomConfigService()
});