Advanced pattern matching system for filtering log events using text patterns, JSON field comparisons, and space-delimited parsing with support for complex boolean logic.
Base interface and factory class for creating log event filters that can match text patterns, JSON fields, and structured data.
/**
* Interface for log filter patterns
*/
interface IFilterPattern {
/** CloudWatch Logs filter pattern string */
readonly logPatternString: string;
}
/**
* Factory class for creating filter patterns
*/
class FilterPattern {
/**
* Use a literal string as the filter pattern
* @param pattern - Literal pattern string
* @returns Filter pattern for literal matching
*/
static literal(pattern: string): IFilterPattern;
/**
* Match all log events
* @returns Filter pattern that matches everything
*/
static allEvents(): IFilterPattern;
/**
* Match log events that contain all the specified terms
* @param terms - Terms that must all be present
* @returns Filter pattern for AND logic
*/
static allTerms(...terms: string[]): IFilterPattern;
/**
* Match log events that contain any of the specified terms
* @param terms - Terms where any one can match
* @returns Filter pattern for OR logic
*/
static anyTerm(...terms: string[]): IFilterPattern;
/**
* Match log events that contain any term from any of the term groups
* @param termGroups - Arrays of terms to match against
* @returns Filter pattern for complex OR logic
*/
static anyTermGroup(...termGroups: string[][]): IFilterPattern;
/**
* Match JSON log events where a string field equals a value
* @param jsonField - JSON field path (e.g., "$.level")
* @param comparison - Comparison operator ("=", "!=")
* @param value - String value to compare
* @returns JSON pattern for string comparison
*/
static stringValue(jsonField: string, comparison: string, value: string): JsonPattern;
/**
* Match JSON log events where a numeric field meets a condition
* @param jsonField - JSON field path (e.g., "$.responseTime")
* @param comparison - Comparison operator ("=", "!=", "<", "<=", ">", ">=")
* @param value - Numeric value to compare
* @returns JSON pattern for numeric comparison
*/
static numberValue(jsonField: string, comparison: string, value: number): JsonPattern;
/**
* Match JSON log events where a field is null
* @param jsonField - JSON field path
* @returns JSON pattern for null check
*/
static isNull(jsonField: string): JsonPattern;
/**
* Match JSON log events where a field doesn't exist
* @param jsonField - JSON field path
* @returns JSON pattern for existence check
*/
static notExists(jsonField: string): JsonPattern;
/**
* Match JSON log events where a field exists
* @param jsonField - JSON field path
* @returns JSON pattern for existence check
*/
static exists(jsonField: string): JsonPattern;
/**
* Match JSON log events where a boolean field equals a value
* @param jsonField - JSON field path
* @param value - Boolean value to match
* @returns JSON pattern for boolean comparison
*/
static booleanValue(jsonField: string, value: boolean): JsonPattern;
/**
* Match JSON log events where all the specified patterns match
* @param patterns - JSON patterns that must all match
* @returns Combined JSON pattern with AND logic
*/
static all(...patterns: JsonPattern[]): JsonPattern;
/**
* Match JSON log events where any of the specified patterns match
* @param patterns - JSON patterns where any can match
* @returns Combined JSON pattern with OR logic
*/
static any(...patterns: JsonPattern[]): JsonPattern;
/**
* Create a space-delimited text pattern for structured log parsing
* @param columns - Column names in order
* @returns Space-delimited pattern for further refinement
*/
static spaceDelimited(...columns: string[]): SpaceDelimitedTextPattern;
}Usage Examples:
import * as logs from '@aws-cdk/aws-logs';
// Simple text matching
const errorPattern = logs.FilterPattern.literal('ERROR');
const allEventsPattern = logs.FilterPattern.allEvents();
// Term-based patterns
const anyErrorPattern = logs.FilterPattern.anyTerm('ERROR', 'WARN', 'FATAL');
const allRequiredTerms = logs.FilterPattern.allTerms('user', 'login', 'success');
// JSON field patterns
const levelPattern = logs.FilterPattern.stringValue('$.level', '=', 'ERROR');
const responseTimePattern = logs.FilterPattern.numberValue('$.responseTime', '>', 1000);
const userExistsPattern = logs.FilterPattern.exists('$.userId');
// Complex JSON patterns
const errorWithUser = logs.FilterPattern.all(
logs.FilterPattern.stringValue('$.level', '=', 'ERROR'),
logs.FilterPattern.exists('$.userId')
);
const warnOrError = logs.FilterPattern.any(
logs.FilterPattern.stringValue('$.level', '=', 'ERROR'),
logs.FilterPattern.stringValue('$.level', '=', 'WARN')
);Specialized patterns for matching structured JSON log events with field-level filtering and complex boolean logic.
/**
* Base class for JSON filter patterns
*/
class JsonPattern implements IFilterPattern {
/** JSON-specific pattern string */
readonly jsonPatternString: string;
/** CloudWatch Logs filter pattern string */
readonly logPatternString: string;
}Parse and filter space-delimited structured text logs like Apache access logs or custom formatted logs.
/**
* Pattern for parsing space-delimited text logs
*/
class SpaceDelimitedTextPattern implements IFilterPattern {
/**
* Create a space-delimited text pattern
* @param columns - Column definitions and restrictions
* @returns Space-delimited pattern instance
*/
static construct(columns: RestrictionMap): SpaceDelimitedTextPattern;
/**
* Add a string value restriction to a column
* @param columnName - Name of the column to restrict
* @param comparison - Comparison operator ("=", "!=")
* @param value - String value to compare
* @returns Updated pattern with restriction
*/
whereString(columnName: string, comparison: string, value: string): SpaceDelimitedTextPattern;
/**
* Add a numeric value restriction to a column
* @param columnName - Name of the column to restrict
* @param comparison - Comparison operator ("=", "!=", "<", "<=", ">", ">=")
* @param value - Numeric value to compare
* @returns Updated pattern with restriction
*/
whereNumber(columnName: string, comparison: string, value: number): SpaceDelimitedTextPattern;
/** CloudWatch Logs filter pattern string */
readonly logPatternString: string;
}
/**
* Mapping of column names to their restrictions
*/
type RestrictionMap = { [columnName: string]: ColumnRestriction };
/**
* Value restrictions for a column in space-delimited text
*/
interface ColumnRestriction {
/** String value restriction */
readonly stringValue?: string;
/** Numeric value restriction */
readonly numberValue?: number;
}Usage Examples:
import * as logs from '@aws-cdk/aws-logs';
// Apache-style access log parsing
const accessLogPattern = logs.FilterPattern
.spaceDelimited('ip', 'user', 'time', 'method', 'path', 'status', 'size')
.whereString('method', '=', 'POST')
.whereNumber('status', '>=', 400);
// Custom application log format
const appLogPattern = logs.FilterPattern
.spaceDelimited('timestamp', 'level', 'component', 'message')
.whereString('level', '=', 'ERROR')
.whereString('component', '=', 'database');// Filter complex JSON application logs
const jsonPattern = logs.FilterPattern.all(
logs.FilterPattern.stringValue('$.level', '=', 'ERROR'),
logs.FilterPattern.exists('$.request.userId'),
logs.FilterPattern.numberValue('$.request.duration', '>', 5000)
);
// Match either authentication or authorization errors
const securityErrors = logs.FilterPattern.any(
logs.FilterPattern.all(
logs.FilterPattern.stringValue('$.level', '=', 'ERROR'),
logs.FilterPattern.stringValue('$.errorType', '=', 'AuthenticationError')
),
logs.FilterPattern.all(
logs.FilterPattern.stringValue('$.level', '=', 'ERROR'),
logs.FilterPattern.stringValue('$.errorType', '=', 'AuthorizationError')
)
);// Parse and filter web server access logs
const webServerPattern = logs.FilterPattern
.spaceDelimited('remoteIP', 'user', 'timestamp', 'method', 'path', 'protocol', 'status', 'bytes')
.whereString('method', '=', 'GET')
.whereNumber('status', '>=', 400)
.whereNumber('bytes', '>', 10000);
// Filter for specific error conditions
const errorLogPattern = logs.FilterPattern
.spaceDelimited('timestamp', 'level', 'process', 'message')
.whereString('level', '=', 'FATAL');// Filter slow database queries from JSON logs
const slowQueryPattern = logs.FilterPattern.all(
logs.FilterPattern.stringValue('$.component', '=', 'database'),
logs.FilterPattern.numberValue('$.queryTime', '>', 1000),
logs.FilterPattern.exists('$.query')
);
// Monitor failed database connections
const dbErrorPattern = logs.FilterPattern.all(
logs.FilterPattern.stringValue('$.level', '=', 'ERROR'),
logs.FilterPattern.anyTerm('connection', 'timeout', 'database')
);// Track high-latency API requests
const highLatencyPattern = logs.FilterPattern.all(
logs.FilterPattern.stringValue('$.type', '=', 'request'),
logs.FilterPattern.numberValue('$.responseTime', '>', 2000),
logs.FilterPattern.exists('$.endpoint')
);
// Monitor memory usage spikes
const memoryPattern = logs.FilterPattern.all(
logs.FilterPattern.stringValue('$.metric', '=', 'memory'),
logs.FilterPattern.numberValue('$.value', '>', 85),
logs.FilterPattern.stringValue('$.unit', '=', 'percent')
);