or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-log-management.mdindex.mdlog-forwarding.mdmetric-extraction.mdpattern-matching.mdquery-definitions.mdresource-policies.md
tile.json

tessl/npm-aws-cdk--aws-logs

The CDK Construct Library for AWS::Logs

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@aws-cdk/aws-logs@1.204.x

To install, run

npx @tessl/cli install tessl/npm-aws-cdk--aws-logs@1.204.0

index.mddocs/

AWS CDK Logs

The CDK Construct Library for AWS::Logs provides comprehensive constructs for working with Amazon CloudWatch Logs, enabling developers to programmatically create and manage log groups, log streams, subscription filters, metric filters, and retention policies. The library supports advanced CloudWatch Logs features including cross-account destinations for log forwarding, encryption using AWS KMS customer master keys, resource-based policies for service access control, and sophisticated filtering patterns for both text-based and JSON-structured log events.

⚠️ DEPRECATED: AWS CDK v1 has reached End-of-Support on 2023-06-01. This package is no longer being updated, and users should migrate to AWS CDK v2. For more information on how to migrate, see the AWS CDK v2 migration guide.

Package Information

  • Package Name: @aws-cdk/aws-logs
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @aws-cdk/aws-logs
  • Version: 1.204.0

Core Imports

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

Individual imports:

import { 
  LogGroup, 
  LogStream, 
  FilterPattern, 
  MetricFilter, 
  SubscriptionFilter,
  RetentionDays 
} from '@aws-cdk/aws-logs';

Basic Usage

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

class MyStack extends cdk.Stack {
  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

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

    // Add a log stream
    logGroup.addStream('MyStream', {
      logStreamName: 'my-stream',
    });

    // Add metric filter to extract metrics from logs
    logGroup.addMetricFilter('ErrorMetric', {
      filterPattern: logs.FilterPattern.literal('ERROR'),
      metricNamespace: 'MyApp',
      metricName: 'ErrorCount',
    });

    // Extract metric from JSON structured logs
    const responseTimeMetric = logGroup.extractMetric(
      '$.responseTime',
      'MyApp',
      'ResponseTime'
    );
  }
}

Architecture

The AWS CDK Logs library is built around several key components:

  • Core Log Management: LogGroup and LogStream constructs for basic log organization
  • Pattern Matching System: Sophisticated filtering capabilities through FilterPattern for text and JSON patterns
  • Metric Extraction: MetricFilter for creating CloudWatch metrics from log events
  • Log Forwarding: SubscriptionFilter and CrossAccountDestination for streaming logs to other services
  • Access Control: Resource policies and IAM integration for fine-grained permissions
  • Retention Management: Automated log lifecycle management with configurable retention periods
  • Query Tools: CloudWatch Logs Insights integration via QueryDefinition

Capabilities

Core Log Management

Essential constructs for creating and managing CloudWatch log groups and streams, with support for encryption, retention policies, and IAM permissions.

class LogGroup extends Construct implements ILogGroup {
  constructor(scope: Construct, id: string, props?: LogGroupProps);
  static fromLogGroupArn(scope: Construct, id: string, logGroupArn: string): ILogGroup;
  static fromLogGroupName(scope: Construct, id: string, logGroupName: string): ILogGroup;
  
  readonly logGroupArn: string;
  readonly logGroupName: string;
  
  addStream(id: string, props?: StreamOptions): LogStream;
  addSubscriptionFilter(id: string, props: SubscriptionFilterOptions): SubscriptionFilter;
  addMetricFilter(id: string, props: MetricFilterOptions): MetricFilter;
  extractMetric(jsonField: string, metricNamespace: string, metricName: string): cloudwatch.Metric;
  grantWrite(grantee: iam.IGrantable): iam.Grant;
  grant(grantee: iam.IGrantable, ...actions: string[]): iam.Grant;
  addToResourcePolicy(statement: iam.PolicyStatement): iam.AddToResourcePolicyResult;
  logGroupPhysicalName(): string;
}

interface LogGroupProps {
  readonly encryptionKey?: kms.IKey;
  readonly logGroupName?: string;
  readonly retention?: RetentionDays;
  readonly removalPolicy?: RemovalPolicy;
}

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
}

Core Log Management

Pattern Matching and Filtering

Advanced pattern matching system for filtering log events using text patterns, JSON field comparisons, and space-delimited parsing with support for complex boolean logic.

interface IFilterPattern {
  readonly logPatternString: string;
}

class FilterPattern {
  static literal(pattern: string): IFilterPattern;
  static allEvents(): IFilterPattern;
  static allTerms(...terms: string[]): IFilterPattern;
  static anyTerm(...terms: string[]): IFilterPattern;
  static stringValue(jsonField: string, comparison: string, value: string): JsonPattern;
  static numberValue(jsonField: string, comparison: string, value: number): JsonPattern;
  static exists(jsonField: string): JsonPattern;
  static isNull(jsonField: string): JsonPattern;
  static booleanValue(jsonField: string, value: boolean): JsonPattern;
  static all(...patterns: JsonPattern[]): JsonPattern;
  static any(...patterns: JsonPattern[]): JsonPattern;
  static spaceDelimited(...columns: string[]): SpaceDelimitedTextPattern;
}

Pattern Matching and Filtering

Metric Extraction and Monitoring

Extract CloudWatch metrics from log events using configurable patterns and metric definitions, enabling automated monitoring and alerting based on log content.

class MetricFilter extends Construct {
  constructor(scope: Construct, id: string, props: MetricFilterProps);
  metric(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
}

interface MetricFilterProps {
  readonly logGroup: ILogGroup;
  readonly filterPattern: IFilterPattern;
  readonly metricNamespace: string;
  readonly metricName: string;
  readonly metricValue?: string;
  readonly defaultValue?: number;
}

Metric Extraction and Monitoring

Log Forwarding and Destinations

Stream log events to external destinations including Lambda functions, Kinesis streams, and cross-account destinations with automatic IAM role management.

class SubscriptionFilter extends Construct {
  constructor(scope: Construct, id: string, props: SubscriptionFilterProps);
}

interface SubscriptionFilterProps {
  readonly logGroup: ILogGroup;
  readonly destination: ILogSubscriptionDestination;
  readonly filterPattern: IFilterPattern;
}

class CrossAccountDestination extends Construct implements ILogSubscriptionDestination {
  constructor(scope: Construct, id: string, props: CrossAccountDestinationProps);
  readonly destinationArn: string;
  readonly destinationName: string;
  addToPolicy(statement: iam.PolicyStatement): void;
}

Log Forwarding and Destinations

Resource Policies and Access Control

Manage CloudWatch Logs resource policies for fine-grained access control, enabling other AWS services and external accounts to interact with log groups.

class ResourcePolicy extends Construct {
  constructor(scope: Construct, id: string, props?: ResourcePolicyProps);
  readonly document: iam.PolicyDocument;
}

interface ResourcePolicyProps {
  readonly resourcePolicyName?: string;
  readonly policyStatements?: iam.PolicyStatement[];
}

Resource Policies and Access Control

Query Definitions and Insights

Create and manage CloudWatch Logs Insights query definitions for structured log analysis and reporting with predefined query templates.

class QueryDefinition extends Construct {
  constructor(scope: Construct, id: string, props: QueryDefinitionProps);
  readonly queryDefinitionId: string;
}

interface QueryDefinitionProps {
  readonly queryDefinitionName: string;
  readonly queryString: QueryString;
  readonly logGroups?: ILogGroup[];
}

class QueryString {
  constructor(props?: QueryStringProps);
  toString(): string;
}

Query Definitions and Insights

Types

Core Interfaces

interface ILogGroup extends iam.IResourceWithPolicy {
  readonly logGroupArn: string;
  readonly logGroupName: string;
  addStream(id: string, props?: StreamOptions): LogStream;
  addSubscriptionFilter(id: string, props: SubscriptionFilterOptions): SubscriptionFilter;
  addMetricFilter(id: string, props: MetricFilterOptions): MetricFilter;
  extractMetric(jsonField: string, metricNamespace: string, metricName: string): cloudwatch.Metric;
  grantWrite(grantee: iam.IGrantable): iam.Grant;
  grant(grantee: iam.IGrantable, ...actions: string[]): iam.Grant;
  logGroupPhysicalName(): string;
}

interface ILogStream extends IResource {
  readonly logStreamName: string;
}

interface ILogSubscriptionDestination {
  bind(scope: Construct, sourceLogGroup: ILogGroup): LogSubscriptionDestinationConfig;
}

interface LogSubscriptionDestinationConfig {
  readonly arn: string;
  readonly role?: iam.IRole;
}