refactor(logs): API cleanups (#2909)

* CrossAccountDestination now extends `Resource`

BREAKING CHANGE: `newStream` renamed to `addStream` and doesn't need a scope
* **logs:** `newSubscriptionFilter` renamed to `addSubscriptionFilter` and doesn't need a scope
* **logs:** `newMetricFilter` renamed to `addMetricFilter` and doesn't need a scope
* **logs:** `NewSubscriptionFilterProps` renamed to `SubscriptionProps`
* **logs:** `NewLogStreamProps` renamed to `LogStreamOptions`
* **logs:** `NewMetricFilterProps` renamed to `MetricFilterOptions`
* **logs:** `JSONPattern` renamed to `JsonPattern`

Author: Elad Ben-Israel

packages/@aws-cdk/aws-logs/lib/cross-account-destination.ts

@@ -39,20 +39,24 @@ export interface CrossAccountDestinationProps {
  * subscribe a Kinesis stream using the integration class in the
  * `@aws-cdk/aws-logs-destinations` package; if necessary, a
  * `CrossAccountDestination` will be created automatically.
+ *
+ * @resource AWS::Logs::Destination
  */
-export class CrossAccountDestination extends cdk.Construct implements ILogSubscriptionDestination {
+export class CrossAccountDestination extends cdk.Resource implements ILogSubscriptionDestination {
   /**
    * Policy object of this CrossAccountDestination object
    */
   public readonly policyDocument: iam.PolicyDocument = new iam.PolicyDocument();
 
   /**
    * The name of this CrossAccountDestination object
+   * @attribute
    */
   public readonly destinationName: string;
 
   /**
    * The ARN of this CrossAccountDestination object
+   * @attribute
    */
   public readonly destinationArn: string;
 

packages/@aws-cdk/aws-logs/lib/log-group.ts

@@ -23,29 +23,26 @@ export interface ILogGroup extends IResource {
   /**
    * Create a new Log Stream for this Log Group
    *
-   * @param scope Parent construct
    * @param id Unique identifier for the construct in its parent
    * @param props Properties for creating the LogStream
    */
-  newStream(scope: Construct, id: string, props?: NewLogStreamProps): LogStream;
+  addStream(id: string, props?: StreamOptions): LogStream;
 
   /**
    * Create a new Subscription Filter on this Log Group
    *
-   * @param scope Parent construct
    * @param id Unique identifier for the construct in its parent
    * @param props Properties for creating the SubscriptionFilter
    */
-  newSubscriptionFilter(scope: Construct, id: string, props: NewSubscriptionFilterProps): SubscriptionFilter;
+  addSubscriptionFilter(id: string, props: SubscriptionFilterOptions): SubscriptionFilter;
 
   /**
    * Create a new Metric Filter on this Log Group
    *
-   * @param scope Parent construct
    * @param id Unique identifier for the construct in its parent
    * @param props Properties for creating the MetricFilter
    */
-  newMetricFilter(scope: Construct, id: string, props: NewMetricFilterProps): MetricFilter;
+  addMetricFilter(id: string, props: MetricFilterOptions): MetricFilter;
 
   /**
    * Extract a metric from structured log events in the LogGroup
@@ -91,12 +88,11 @@ abstract class LogGroupBase extends Resource implements ILogGroup {
   /**
    * Create a new Log Stream for this Log Group
    *
-   * @param scope Parent construct
    * @param id Unique identifier for the construct in its parent
    * @param props Properties for creating the LogStream
    */
-  public newStream(scope: Construct, id: string, props: NewLogStreamProps = {}): LogStream {
-    return new LogStream(scope, id, {
+  public addStream(id: string, props: StreamOptions = {}): LogStream {
+    return new LogStream(this, id, {
       logGroup: this,
       ...props
     });
@@ -105,12 +101,11 @@ abstract class LogGroupBase extends Resource implements ILogGroup {
   /**
    * Create a new Subscription Filter on this Log Group
    *
-   * @param scope Parent construct
    * @param id Unique identifier for the construct in its parent
    * @param props Properties for creating the SubscriptionFilter
    */
-  public newSubscriptionFilter(scope: Construct, id: string, props: NewSubscriptionFilterProps): SubscriptionFilter {
-    return new SubscriptionFilter(scope, id, {
+  public addSubscriptionFilter(id: string, props: SubscriptionFilterOptions): SubscriptionFilter {
+    return new SubscriptionFilter(this, id, {
       logGroup: this,
       ...props
     });
@@ -119,12 +114,11 @@ abstract class LogGroupBase extends Resource implements ILogGroup {
   /**
    * Create a new Metric Filter on this Log Group
    *
-   * @param scope Parent construct
    * @param id Unique identifier for the construct in its parent
    * @param props Properties for creating the MetricFilter
    */
-  public newMetricFilter(scope: Construct, id: string, props: NewMetricFilterProps): MetricFilter {
-    return new MetricFilter(scope, id, {
+  public addMetricFilter(id: string, props: MetricFilterOptions): MetricFilter {
+    return new MetricFilter(this, id, {
       logGroup: this,
       ...props
     });
@@ -353,7 +347,7 @@ export class LogGroup extends LogGroupBase {
 /**
  * Properties for a new LogStream created from a LogGroup
  */
-export interface NewLogStreamProps {
+export interface StreamOptions {
   /**
    * The name of the log stream to create.
    *
@@ -367,7 +361,7 @@ export interface NewLogStreamProps {
 /**
  * Properties for a new SubscriptionFilter created from a LogGroup
  */
-export interface NewSubscriptionFilterProps {
+export interface SubscriptionFilterOptions {
   /**
    * The destination to send the filtered events to.
    *
@@ -384,7 +378,7 @@ export interface NewSubscriptionFilterProps {
 /**
  * Properties for a MetricFilter created from a LogGroup
  */
-export interface NewMetricFilterProps {
+export interface MetricFilterOptions {
   /**
    * Pattern to search for log events.
    */

packages/@aws-cdk/aws-logs/lib/metric-filter.ts

@@ -1,55 +1,15 @@
 import { Construct, Resource } from '@aws-cdk/cdk';
-import { ILogGroup } from './log-group';
+import { ILogGroup, MetricFilterOptions } from './log-group';
 import { CfnMetricFilter } from './logs.generated';
-import { IFilterPattern } from './pattern';
 
 /**
  * Properties for a MetricFilter
  */
-export interface MetricFilterProps {
+export interface MetricFilterProps extends MetricFilterOptions {
   /**
    * The log group to create the filter on.
    */
   readonly logGroup: ILogGroup;
-
-  /**
-   * Pattern to search for log events.
-   */
-  readonly filterPattern: IFilterPattern;
-
-  /**
-   * The namespace of the metric to emit.
-   */
-  readonly metricNamespace: string;
-
-  /**
-   * The name of the metric to emit.
-   */
-  readonly metricName: string;
-
-  /**
-   * The value to emit for the metric.
-   *
-   * Can either be a literal number (typically "1"), or the name of a field in the structure
-   * to take the value from the matched event. If you are using a field value, the field
-   * value must have been matched using the pattern.
-   *
-   * If you want to specify a field from a matched JSON structure, use '$.fieldName',
-   * and make sure the field is in the pattern (if only as '$.fieldName = *').
-   *
-   * If you want to specify a field from a matched space-delimited structure,
-   * use '$fieldName'.
-   *
-   * @default "1"
-   */
-  readonly metricValue?: string;
-
-  /**
-   * The value to emit if the pattern does not match a particular event.
-   *
-   * @default No metric emitted.
-   */
-  readonly defaultValue?: number;
 }
 
 /**

packages/@aws-cdk/aws-logs/lib/pattern.ts

@@ -10,11 +10,10 @@ export interface IFilterPattern {
 /**
  * Base class for patterns that only match JSON log events.
  */
-export abstract class JSONPattern implements IFilterPattern {
+export abstract class JsonPattern implements IFilterPattern {
   // This is a separate class so we have some type safety where users can't
   // combine text patterns and JSON patterns with an 'and' operation.
-  constructor(public readonly jsonPatternString: string) {
-  }
+  constructor(public readonly jsonPatternString: string) { }
 
   public get logPatternString(): string {
     return '{ ' + this.jsonPatternString + ' }';
@@ -92,7 +91,7 @@ export class FilterPattern {
    * @param comparison Comparison to carry out. Either = or !=.
    * @param value The string value to compare to. May use '*' as wildcard at start or end of string.
    */
-  public static stringValue(jsonField: string, comparison: string, value: string): JSONPattern {
+  public static stringValue(jsonField: string, comparison: string, value: string): JsonPattern {
     return new JSONStringPattern(jsonField, comparison, value);
   }
 
@@ -114,7 +113,7 @@ export class FilterPattern {
    * @param comparison Comparison to carry out. One of =, !=, <, <=, >, >=.
    * @param value The numerical value to compare to
    */
-  public static numberValue(jsonField: string, comparison: string, value: number): JSONPattern {
+  public static numberValue(jsonField: string, comparison: string, value: number): JsonPattern {
     return new JSONNumberPattern(jsonField, comparison, value);
   }
 
@@ -123,7 +122,7 @@ export class FilterPattern {
    *
    * @param jsonField Field inside JSON. Example: "$.myField"
    */
-  public static isNull(jsonField: string): JSONPattern {
+  public static isNull(jsonField: string): JsonPattern {
     return new JSONPostfixPattern(jsonField, 'IS NULL');
   }
 
@@ -132,7 +131,7 @@ export class FilterPattern {
    *
    * @param jsonField Field inside JSON. Example: "$.myField"
    */
-  public static notExists(jsonField: string): JSONPattern {
+  public static notExists(jsonField: string): JsonPattern {
     return new JSONPostfixPattern(jsonField, 'NOT EXISTS');
   }
 
@@ -143,7 +142,7 @@ export class FilterPattern {
    *
    * @param jsonField Field inside JSON. Example: "$.myField"
    */
-  public static exists(jsonField: string): JSONPattern {
+  public static exists(jsonField: string): JsonPattern {
     return new JSONStringPattern(jsonField, '=', '*');
   }
 
@@ -153,14 +152,14 @@ export class FilterPattern {
    * @param jsonField Field inside JSON. Example: "$.myField"
    * @param value The value to match
    */
-  public static booleanValue(jsonField: string, value: boolean): JSONPattern {
+  public static booleanValue(jsonField: string, value: boolean): JsonPattern {
     return new JSONPostfixPattern(jsonField, value ? 'IS TRUE' : 'IS FALSE');
   }
 
   /**
    * A JSON log pattern that matches if all given JSON log patterns match
    */
-  public static all(...patterns: JSONPattern[]): JSONPattern {
+  public static all(...patterns: JsonPattern[]): JsonPattern {
     if (patterns.length === 0) { throw new Error('Must supply at least one pattern, or use allEvents() to match all events.'); }
     if (patterns.length === 1) { return patterns[0]; }
     return new JSONAggregatePattern('&&', patterns);
@@ -169,7 +168,7 @@ export class FilterPattern {
   /**
    * A JSON log pattern that matches if any of the given JSON log patterns match
    */
-  public static any(...patterns: JSONPattern[]): JSONPattern {
+  public static any(...patterns: JsonPattern[]): JsonPattern {
     if (patterns.length === 0) { throw new Error('Must supply at least one pattern'); }
     if (patterns.length === 1) { return patterns[0]; }
     return new JSONAggregatePattern('||', patterns);
@@ -220,7 +219,7 @@ class TextLogPattern implements IFilterPattern {
 /**
  * A string comparison for JSON values
  */
-class JSONStringPattern extends JSONPattern {
+class JSONStringPattern extends JsonPattern {
   public constructor(jsonField: string, comparison: string, value: string) {
     comparison = validateStringOperator(comparison);
     super(`${jsonField} ${comparison} ${quoteTerm(value)}`);
@@ -230,7 +229,7 @@ class JSONStringPattern extends JSONPattern {
 /**
  * A number comparison for JSON values
  */
-class JSONNumberPattern extends JSONPattern {
+class JSONNumberPattern extends JsonPattern {
   public constructor(jsonField: string, comparison: string, value: number) {
     comparison = validateNumericalOperator(comparison);
     super(`${jsonField} ${comparison} ${value}`);
@@ -240,7 +239,7 @@ class JSONNumberPattern extends JSONPattern {
 /**
  * A postfix operator for JSON patterns
  */
-class JSONPostfixPattern extends JSONPattern {
+class JSONPostfixPattern extends JsonPattern {
   public constructor(jsonField: string, postfix: string) {
     // No validation, we assume these are generated by trusted factory functions
     super(`${jsonField} ${postfix}`);
@@ -250,8 +249,8 @@ class JSONPostfixPattern extends JSONPattern {
 /**
  * Combines multiple other JSON patterns with an operator
  */
-class JSONAggregatePattern extends JSONPattern {
-  public constructor(operator: string, patterns: JSONPattern[]) {
+class JSONAggregatePattern extends JsonPattern {
+  public constructor(operator: string, patterns: JsonPattern[]) {
     if (operator !== '&&' && operator !== '||') {
       throw new Error('Operator must be one of && or ||');
     }

packages/@aws-cdk/aws-logs/lib/subscription-filter.ts

@@ -1,8 +1,7 @@
 import iam = require('@aws-cdk/aws-iam');
 import { Construct, Resource } from '@aws-cdk/cdk';
-import { ILogGroup } from './log-group';
+import { ILogGroup, SubscriptionFilterOptions } from './log-group';
 import { CfnSubscriptionFilter } from './logs.generated';
-import { IFilterPattern } from './pattern';
 
 /**
  * Interface for classes that can be the destination of a log Subscription
@@ -41,23 +40,11 @@ export interface LogSubscriptionDestinationConfig {
 /**
  * Properties for a SubscriptionFilter
  */
-export interface SubscriptionFilterProps {
+export interface SubscriptionFilterProps extends SubscriptionFilterOptions {
   /**
    * The log group to create the subscription on.
    */
   readonly logGroup: ILogGroup;
-
-  /**
-   * The destination to send the filtered events to.
-   *
-   * For example, a Kinesis stream or a Lambda function.
-   */
-  readonly destination: ILogSubscriptionDestination;
-
-  /**
-   * Log events matching this pattern will be sent to the destination.
-   */
-  readonly filterPattern: IFilterPattern;
 }
 
 /**

packages/@aws-cdk/aws-logs/test/test.loggroup.ts

@@ -88,7 +88,7 @@ export = {
 
     // WHEN
     const imported = LogGroup.fromLogGroupArn(stack2, 'lg', 'arn:aws:logs:us-east-1:123456789012:log-group:my-log-group');
-    imported.newStream(stack2, 'MakeMeAStream');
+    imported.addStream('MakeMeAStream');
 
     // THEN
     expect(stack2).to(haveResource('AWS::Logs::LogStream', {