feat(neptune): introduce metric method to cluster and instance (aws#21995)

closes aws#20248


----

### All Submissions:

* [x] Have you followed the guidelines in our [Contributing guide?](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md)

### Adding new Unconventional Dependencies:

* [ ] This PR adds new unconventional dependencies following the process described [here](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md/#adding-new-unconventional-dependencies)

### New Features

* [ ] Have you added the new feature to an [integration test](https://github.com/aws/aws-cdk/blob/main/INTEGRATION_TESTS.md)?
	* [ ] Did you use `yarn integ` to deploy the infrastructure and generate the snapshot (i.e. `yarn integ` without `--dry-run`)?

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: humanzz

packages/@aws-cdk/aws-neptune/README.md

@@ -121,7 +121,7 @@ const cluster = new neptune.DatabaseCluster(this, 'Database', {
 });
 ```
 
-Additionally it is also possible to add replicas using `DatabaseInstance` for an existing cluster.
+Additionally, it is also possible to add replicas using `DatabaseInstance` for an existing cluster.
 
 ```ts fixture=with-cluster
 const replica1 = new neptune.DatabaseInstance(this, 'Instance', {
@@ -143,3 +143,17 @@ new neptune.DatabaseCluster(this, 'Cluster', {
   autoMinorVersionUpgrade: true,
 });
 ```
+
+## Metrics
+
+Both `DatabaseCluster` and `DatabaseInstance` provide a `metric()` method to help with cluster-level and instance-level monitoring.
+
+```ts
+declare const cluster: neptune.DatabaseCluster;
+declare const instance: neptune.DatabaseInstance;
+
+cluster.metric('SparqlRequestsPerSec'); // cluster-level SparqlErrors metric
+instance.metric('SparqlRequestsPerSec') // instance-level SparqlErrors metric
+```
+
+For more details on the available metrics, refer to https://docs.aws.amazon.com/neptune/latest/userguide/cw-metrics.html

packages/@aws-cdk/aws-neptune/lib/cluster.ts

@@ -1,3 +1,4 @@
+import * as cloudwatch from '@aws-cdk/aws-cloudwatch';
 import * as ec2 from '@aws-cdk/aws-ec2';
 import * as iam from '@aws-cdk/aws-iam';
 import * as kms from '@aws-cdk/aws-kms';
@@ -284,6 +285,14 @@ export interface IDatabaseCluster extends IResource, ec2.IConnectable {
    * Grant the given identity connection access to the database.
    */
   grantConnect(grantee: iam.IGrantable): iam.Grant;
+
+  /**
+   * Return the given named metric associated with this DatabaseCluster instance
+   *
+   * @see https://docs.aws.amazon.com/neptune/latest/userguide/cw-metrics.html
+   * @see https://docs.aws.amazon.com/neptune/latest/userguide/cw-dimensions.html
+   */
+  metric(metricName: string, props?: cloudwatch.MetricOptions): cloudwatch.Metric;
 }
 
 /**
@@ -398,6 +407,17 @@ export abstract class DatabaseClusterBase extends Resource implements IDatabaseC
   public grantConnect(grantee: iam.IGrantable): iam.Grant {
     return this.grant(grantee, 'neptune-db:*');
   }
+
+  public metric(metricName: string, props?: cloudwatch.MetricOptions): cloudwatch.Metric {
+    return new cloudwatch.Metric({
+      namespace: 'AWS/Neptune',
+      dimensionsMap: {
+        DBClusterIdentifier: this.clusterIdentifier,
+      },
+      metricName,
+      ...props,
+    });
+  }
 }
 
 /**

packages/@aws-cdk/aws-neptune/lib/instance.ts

@@ -1,3 +1,4 @@
+import * as cloudwatch from '@aws-cdk/aws-cloudwatch';
 import * as ec2 from '@aws-cdk/aws-ec2';
 import * as cdk from '@aws-cdk/core';
 import { Construct } from 'constructs';
@@ -165,6 +166,14 @@ export interface IDatabaseInstance extends cdk.IResource {
    * @attribute Port
    */
   readonly dbInstanceEndpointPort: string;
+
+  /**
+   * Return the given named metric associated with this database instance
+   *
+   * @see https://docs.aws.amazon.com/neptune/latest/userguide/cw-metrics.html
+   * @see https://docs.aws.amazon.com/neptune/latest/userguide/cw-dimensions.html
+   */
+  metric(metricName: string, props?: cloudwatch.MetricOptions): cloudwatch.Metric;
 }
 
 /**
@@ -233,27 +242,64 @@ export interface DatabaseInstanceProps {
 }
 
 /**
- * A database instance
- *
- * @resource AWS::Neptune::DBInstance
+ * A new or imported database instance.
  */
-export class DatabaseInstance extends cdk.Resource implements IDatabaseInstance {
-
+export abstract class DatabaseInstanceBase extends cdk.Resource implements IDatabaseInstance {
   /**
    * Import an existing database instance.
    */
   public static fromDatabaseInstanceAttributes(scope: Construct, id: string, attrs: DatabaseInstanceAttributes): IDatabaseInstance {
-    class Import extends cdk.Resource implements IDatabaseInstance {
+    class Import extends DatabaseInstanceBase implements IDatabaseInstance {
       public readonly defaultPort = ec2.Port.tcp(attrs.port);
       public readonly instanceIdentifier = attrs.instanceIdentifier;
       public readonly dbInstanceEndpointAddress = attrs.instanceEndpointAddress;
       public readonly dbInstanceEndpointPort = attrs.port.toString();
       public readonly instanceEndpoint = new Endpoint(attrs.instanceEndpointAddress, attrs.port);
     }
-
     return new Import(scope, id);
   }
 
+  /**
+   * @inheritdoc
+   */
+  public abstract readonly dbInstanceEndpointAddress: string;
+
+  /**
+   * @inheritdoc
+   */
+  public abstract readonly dbInstanceEndpointPort: string;
+
+  /**
+   * @inheritdoc
+   */
+  public abstract readonly instanceEndpoint: Endpoint;
+
+  /**
+   * @inheritdoc
+   */
+  public abstract readonly instanceIdentifier: string;
+
+  /**
+   * @inheritdoc
+   */
+  public metric(metricName: string, props?: cloudwatch.MetricOptions): cloudwatch.Metric {
+    return new cloudwatch.Metric({
+      namespace: 'AWS/Neptune',
+      dimensionsMap: {
+        DBInstanceIdentifier: this.instanceIdentifier,
+      },
+      metricName,
+      ...props,
+    });
+  }
+}
+
+/**
+ * A database instance
+ *
+ * @resource AWS::Neptune::DBInstance
+ */
+export class DatabaseInstance extends DatabaseInstanceBase implements IDatabaseInstance {
 
   /**
    * The instance's database cluster

packages/@aws-cdk/aws-neptune/package.json

@@ -90,13 +90,15 @@
     "@types/jest": "^27.5.2"
   },
   "dependencies": {
+    "@aws-cdk/aws-cloudwatch": "0.0.0",
     "@aws-cdk/aws-ec2": "0.0.0",
     "@aws-cdk/aws-iam": "0.0.0",
     "@aws-cdk/aws-kms": "0.0.0",
     "@aws-cdk/core": "0.0.0",
     "constructs": "^10.0.0"
   },
   "peerDependencies": {
+    "@aws-cdk/aws-cloudwatch": "0.0.0",
     "@aws-cdk/aws-ec2": "0.0.0",
     "@aws-cdk/aws-iam": "0.0.0",
     "@aws-cdk/aws-kms": "0.0.0",

packages/@aws-cdk/aws-neptune/test/cluster.integ.snapshot/ClusterTestDefaultTestDeployAssert6A1BBA9D.assets.json

@@ -0,0 +1,19 @@
+{
+  "version": "21.0.0",
+  "files": {
+    "21fbb51d7b23f6a6c262b46a9caee79d744a3ac019fd45422d988b96d44b2a22": {
+      "source": {
+        "path": "ClusterTestDefaultTestDeployAssert6A1BBA9D.template.json",
+        "packaging": "file"
+      },
+      "destinations": {
+        "current_account-current_region": {
+          "bucketName": "cdk-hnb659fds-assets-${AWS::AccountId}-${AWS::Region}",
+          "objectKey": "21fbb51d7b23f6a6c262b46a9caee79d744a3ac019fd45422d988b96d44b2a22.json",
+          "assumeRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-file-publishing-role-${AWS::AccountId}-${AWS::Region}"
+        }
+      }
+    }
+  },
+  "dockerImages": {}
+}

packages/@aws-cdk/aws-neptune/test/cluster.integ.snapshot/ClusterTestDefaultTestDeployAssert6A1BBA9D.template.json

@@ -0,0 +1,36 @@
+{
+ "Parameters": {
+  "BootstrapVersion": {
+   "Type": "AWS::SSM::Parameter::Value<String>",
+   "Default": "/cdk-bootstrap/hnb659fds/version",
+   "Description": "Version of the CDK Bootstrap resources in this environment, automatically retrieved from SSM Parameter Store. [cdk:skip]"
+  }
+ },
+ "Rules": {
+  "CheckBootstrapVersion": {
+   "Assertions": [
+    {
+     "Assert": {
+      "Fn::Not": [
+       {
+        "Fn::Contains": [
+         [
+          "1",
+          "2",
+          "3",
+          "4",
+          "5"
+         ],
+         {
+          "Ref": "BootstrapVersion"
+         }
+        ]
+       }
+      ]
+     },
+     "AssertDescription": "CDK bootstrap stack version 6 required. Please run 'cdk bootstrap' with a recent version of the CDK CLI."
+    }
+   ]
+  }
+ }
+}

packages/@aws-cdk/aws-neptune/test/cluster.integ.snapshot/aws-cdk-neptune-integ.assets.json

@@ -1,15 +1,15 @@
 {
   "version": "21.0.0",
   "files": {
-    "315715ffe6004c7bd7c9874629785c10fd8f65a20d6995ea8eb20188dfb82b7d": {
+    "c3aa283b33e47bc3d0cb943f014017d1742247b6577982270570cb6cbf5a778c": {
       "source": {
         "path": "aws-cdk-neptune-integ.template.json",
         "packaging": "file"
       },
       "destinations": {
         "current_account-current_region": {
           "bucketName": "cdk-hnb659fds-assets-${AWS::AccountId}-${AWS::Region}",
-          "objectKey": "315715ffe6004c7bd7c9874629785c10fd8f65a20d6995ea8eb20188dfb82b7d.json",
+          "objectKey": "c3aa283b33e47bc3d0cb943f014017d1742247b6577982270570cb6cbf5a778c.json",
           "assumeRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-file-publishing-role-${AWS::AccountId}-${AWS::Region}"
         }
       }

packages/@aws-cdk/aws-neptune/test/cluster.integ.snapshot/aws-cdk-neptune-integ.template.json

@@ -538,6 +538,26 @@
    ],
    "UpdateReplacePolicy": "Delete",
    "DeletionPolicy": "Delete"
+  },
+  "Alarm7103F465": {
+   "Type": "AWS::CloudWatch::Alarm",
+   "Properties": {
+    "ComparisonOperator": "LessThanThreshold",
+    "EvaluationPeriods": 1,
+    "Dimensions": [
+     {
+      "Name": "DBClusterIdentifier",
+      "Value": {
+       "Ref": "DatabaseB269D8BB"
+      }
+     }
+    ],
+    "MetricName": "SparqlRequestsPerSec",
+    "Namespace": "AWS/Neptune",
+    "Period": 300,
+    "Statistic": "Average",
+    "Threshold": 1
+   }
   }
  },
  "Parameters": {

packages/@aws-cdk/aws-neptune/test/cluster.integ.snapshot/integ.json

@@ -1,14 +1,12 @@
 {
   "version": "21.0.0",
   "testCases": {
-    "integ.cluster": {
+    "ClusterTest/DefaultTest": {
       "stacks": [
         "aws-cdk-neptune-integ"
       ],
-      "diffAssets": false,
-      "stackUpdateWorkflow": true
+      "assertionStack": "ClusterTest/DefaultTest/DeployAssert",
+      "assertionStackName": "ClusterTestDefaultTestDeployAssert6A1BBA9D"
     }
-  },
-  "synthContext": {},
-  "enableLookups": false
+  }
 }