Core Log Management

/**
 * Define a CloudWatch Log Group
 */
class LogGroup extends Construct implements ILogGroup {
  /**
   * Create a new LogGroup
   * @param scope - Construct scope
   * @param id - Construct ID
   * @param props - LogGroup configuration properties
   */
  constructor(scope: Construct, id: string, props?: LogGroupProps);

  /**
   * Import an existing LogGroup by ARN
   * @param scope - Construct scope  
   * @param id - Construct ID
   * @param logGroupArn - ARN of existing log group
   * @returns ILogGroup interface
   */
  static fromLogGroupArn(scope: Construct, id: string, logGroupArn: string): ILogGroup;

  /**
   * Import an existing LogGroup by name
   * @param scope - Construct scope
   * @param id - Construct ID  
   * @param logGroupName - Name of existing log group
   * @returns ILogGroup interface
   */
  static fromLogGroupName(scope: Construct, id: string, logGroupName: string): ILogGroup;

  /** ARN of the log group with ':*' appended */
  readonly logGroupArn: string;
  
  /** Name of the log group */
  readonly logGroupName: string;

  /**
   * Create a new log stream in this log group
   * @param id - Construct ID for the stream
   * @param props - Stream configuration options
   * @returns Created LogStream instance
   */
  addStream(id: string, props?: StreamOptions): LogStream;

  /**
   * Create a subscription filter for this log group
   * @param id - Construct ID for the filter
   * @param props - Subscription filter configuration
   * @returns Created SubscriptionFilter instance
   */
  addSubscriptionFilter(id: string, props: SubscriptionFilterOptions): SubscriptionFilter;

  /**
   * Create a metric filter for this log group
   * @param id - Construct ID for the filter
   * @param props - Metric filter configuration
   * @returns Created MetricFilter instance
   */
  addMetricFilter(id: string, props: MetricFilterOptions): MetricFilter;

  /**
   * Extract a metric from structured log events in the LogGroup
   * 
   * Creates a MetricFilter on this LogGroup that will extract the value
   * of the indicated JSON field in all records where it occurs.
   * The metric will be available in CloudWatch Metrics under the
   * indicated namespace and name.
   * 
   * @param jsonField - JSON field to extract (example: '$.myfield')
   * @param metricNamespace - Namespace to emit the metric under
   * @param metricName - Name to emit the metric under
   * @returns A Metric object representing the extracted metric
   */
  extractMetric(jsonField: string, metricNamespace: string, metricName: string): cloudwatch.Metric;

  /**
   * Grant write permissions to this log group
   * @param grantee - Principal to grant permissions to
   * @returns Grant object
   */
  grantWrite(grantee: iam.IGrantable): iam.Grant;

  /**
   * Grant specific permissions to this log group
   * @param grantee - Principal to grant permissions to
   * @param actions - Specific actions to grant
   * @returns Grant object
   */
  grant(grantee: iam.IGrantable, ...actions: string[]): iam.Grant;

  /**
   * Add a policy statement to the log group's resource policy
   * @param statement - IAM policy statement to add
   */
  addToResourcePolicy(statement: iam.PolicyStatement): iam.AddToResourcePolicyResult;

  /**
   * Get the physical name of the log group
   * @returns Physical name string
   */
  logGroupPhysicalName(): string;
}

/**
 * Properties for defining a LogGroup
 */
interface LogGroupProps {
  /** KMS key for encrypting log data */
  readonly encryptionKey?: kms.IKey;
  
  /** Name of the log group */
  readonly logGroupName?: string;
  
  /** How long to retain logs */
  readonly retention?: RetentionDays;
  
  /** Policy for removing this log group when stack is deleted */
  readonly removalPolicy?: RemovalPolicy;
}

/**
 * Interface representing a log group
 */
interface ILogGroup extends iam.IResourceWithPolicy {
  /** ARN of the log group with ':*' appended */
  readonly logGroupArn: string;
  
  /** Name of the log group */
  readonly logGroupName: string;

  /** Create a new log stream in this log group */
  addStream(id: string, props?: StreamOptions): LogStream;
  
  /** Create a subscription filter for this log group */
  addSubscriptionFilter(id: string, props: SubscriptionFilterOptions): SubscriptionFilter;
  
  /** Create a metric filter for this log group */
  addMetricFilter(id: string, props: MetricFilterOptions): MetricFilter;
  
  /** Grant write permissions to this log group */
  grantWrite(grantee: iam.IGrantable): iam.Grant;
  
  /** Grant specific permissions to this log group */
  grant(grantee: iam.IGrantable, ...actions: string[]): iam.Grant;
  
  /** Add a policy statement to the log group's resource policy */
  addToResourcePolicy(statement: iam.PolicyStatement): iam.AddToResourcePolicyResult;
  
  /** Get the physical name of the log group */
  logGroupPhysicalName(): string;
}

import * as logs from '@aws-cdk/aws-logs';
import * as kms from '@aws-cdk/aws-kms';

// Basic log group
const logGroup = new logs.LogGroup(this, 'MyLogGroup', {
  logGroupName: '/aws/lambda/my-function',
  retention: logs.RetentionDays.ONE_WEEK,
});

// Encrypted log group
const encryptionKey = new kms.Key(this, 'LogKey');
const secureLogGroup = new logs.LogGroup(this, 'SecureLogGroup', {
  encryptionKey: encryptionKey,
  retention: logs.RetentionDays.ONE_MONTH,
});

// Import existing log group
const existingLogGroup = logs.LogGroup.fromLogGroupName(
  this, 
  'ExistingGroup', 
  '/aws/apigateway/my-api'
);

// Grant write access to a service
logGroup.grantWrite(new iam.ServicePrincipal('lambda.amazonaws.com'));

/**
 * Define a Log Stream in a Log Group
 */
class LogStream extends Construct implements ILogStream {
  /**
   * Create a new LogStream
   * @param scope - Construct scope
   * @param id - Construct ID
   * @param props - LogStream configuration properties
   */
  constructor(scope: Construct, id: string, props: LogStreamProps);

  /**
   * Import an existing LogStream by name
   * @param scope - Construct scope
   * @param id - Construct ID
   * @param logStreamName - Name of existing log stream
   * @returns ILogStream interface
   */
  static fromLogStreamName(scope: Construct, id: string, logStreamName: string): ILogStream;

  /** Name of the log stream */
  readonly logStreamName: string;
}

/**
 * Properties for defining a LogStream
 */
interface LogStreamProps {
  /** Parent log group for this stream */
  readonly logGroup: ILogGroup;
  
  /** Name of the log stream */
  readonly logStreamName?: string;
  
  /** Policy for removing this stream when stack is deleted */
  readonly removalPolicy?: RemovalPolicy;
}

/**
 * Interface representing a log stream
 */
interface ILogStream {
  /** Name of the log stream */
  readonly logStreamName: string;
}

import * as logs from '@aws-cdk/aws-logs';

const logGroup = new logs.LogGroup(this, 'MyLogGroup');

// Create a log stream
const logStream = new logs.LogStream(this, 'MyLogStream', {
  logGroup: logGroup,
  logStreamName: 'application-logs',
});

// Or add stream via log group method
const anotherStream = logGroup.addStream('AnotherStream', {
  logStreamName: 'error-logs',
});

/**
 * Log retention periods supported by CloudWatch Logs
 */
enum RetentionDays {
  ONE_DAY = 1,
  THREE_DAYS = 3,
  FIVE_DAYS = 5,
  ONE_WEEK = 7,
  TWO_WEEKS = 14,
  ONE_MONTH = 30,
  TWO_MONTHS = 60,
  THREE_MONTHS = 90,
  FOUR_MONTHS = 120,
  FIVE_MONTHS = 150,
  SIX_MONTHS = 180,
  ONE_YEAR = 365,
  THIRTEEN_MONTHS = 400,
  EIGHTEEN_MONTHS = 545,
  TWO_YEARS = 731,
  FIVE_YEARS = 1827,
  SIX_YEARS = 2192,
  SEVEN_YEARS = 2557,
  EIGHT_YEARS = 2922,
  NINE_YEARS = 3288,
  TEN_YEARS = 3653,
  INFINITE = 9999
}

/**
 * Control retention of external log groups using a custom resource
 */
class LogRetention extends Construct {
  /**
   * Create a LogRetention custom resource
   * @param scope - Construct scope
   * @param id - Construct ID
   * @param props - LogRetention configuration properties
   */
  constructor(scope: Construct, id: string, props: LogRetentionProps);

  /** ARN of the managed log group */
  readonly logGroupArn: string;
}

/**
 * Properties for LogRetention
 */
interface LogRetentionProps {
  /** Name of the log group to manage */
  readonly logGroupName: string;
  
  /** AWS region where the log group exists */
  readonly logGroupRegion?: string;
  
  /** Retention period to set */
  readonly retention: RetentionDays;
  
  /** IAM role for the Lambda function that manages retention */
  readonly role?: iam.IRole;
  
  /** Retry configuration for API calls */
  readonly logRetentionRetryOptions?: LogRetentionRetryOptions;
}

/**
 * Retry configuration for LogRetention operations
 */
interface LogRetentionRetryOptions {
  /** Maximum number of retry attempts */
  readonly maxRetries?: number;
  
  /** Base duration between retries */
  readonly base?: cdk.Duration;
}

import * as logs from '@aws-cdk/aws-logs';

// Control retention for Lambda function log group
const logRetention = new logs.LogRetention(this, 'MyFunctionLogRetention', {
  logGroupName: '/aws/lambda/my-function',
  retention: logs.RetentionDays.ONE_WEEK,
});

// Control retention in different region
const crossRegionRetention = new logs.LogRetention(this, 'CrossRegionRetention', {
  logGroupName: '/aws/chatbot/my-bot',
  logGroupRegion: 'us-east-1',
  retention: logs.RetentionDays.ONE_MONTH,
});

/**
 * Options for creating log streams
 */
interface StreamOptions {
  /** Name of the log stream */
  readonly logStreamName?: string;
}

/**
 * Options for creating subscription filters
 */
interface SubscriptionFilterOptions {
  /** Destination for log events */
  readonly destination: ILogSubscriptionDestination;
  
  /** Pattern to match log events */
  readonly filterPattern: IFilterPattern;
}

/**
 * Options for creating metric filters  
 */
interface MetricFilterOptions {
  /** Pattern to match log events */
  readonly filterPattern: IFilterPattern;
  
  /** CloudWatch metric namespace */
  readonly metricNamespace: string;
  
  /** CloudWatch metric name */
  readonly metricName: string;
  
  /** Expression for metric value */
  readonly metricValue?: string;
  
  /** Default value when no match found */
  readonly defaultValue?: number;
}