# DatabaseInstanceMetrics

CloudWatch metrics for a database instance.

Works with any reference to a database instance: a `DatabaseInstance`, an
imported instance or a `CfnDBInstance`.

Obtainable from: DatabaseInstanceMetrics.fromDatabaseInstance

- Source: [`aws-rds/lib/instance-metrics.ts`](https://github.com/aws/aws-cdk/blob/v2.278.0/packages/aws-cdk-lib/aws-rds/lib/instance-metrics.ts#L10)

## Example

TypeScript:

```ts
declare const instance: rds.IDatabaseInstance;

const metrics = rds.DatabaseInstanceMetrics.fromDatabaseInstance(instance);

// How far a read replica lags behind its source (average over 5 minutes)
const replicaLag = metrics.replicaLag();

// The average amount of time taken per disk I/O read operation (average over 1 minute)
const readLatency = metrics.readLatency({ period: Duration.seconds(60) });

// Any other metric, such as an engine-specific one
const binLogDiskUsage = metrics.metric('BinLogDiskUsage', { statistic: 'Maximum' });
```

Python:

```python
# instance: rds.IDatabaseInstance

metrics = rds.DatabaseInstanceMetrics.from_database_instance(instance)

# How far a read replica lags behind its source (average over 5 minutes)
replica_lag = metrics.replica_lag()

# The average amount of time taken per disk I/O read operation (average over 1 minute)
read_latency = metrics.read_latency(period=Duration.seconds(60))

# Any other metric, such as an engine-specific one
bin_log_disk_usage = metrics.metric("BinLogDiskUsage", statistic="Maximum")
```

Java:

```java
IDatabaseInstance instance;

DatabaseInstanceMetrics metrics = DatabaseInstanceMetrics.fromDatabaseInstance(instance);

// How far a read replica lags behind its source (average over 5 minutes)
Metric replicaLag = metrics.replicaLag();

// The average amount of time taken per disk I/O read operation (average over 1 minute)
Metric readLatency = metrics.readLatency(MetricOptions.builder().period(Duration.seconds(60)).build());

// Any other metric, such as an engine-specific one
Metric binLogDiskUsage = metrics.metric("BinLogDiskUsage", MetricOptions.builder().statistic("Maximum").build());
```

C# / .NET:

```csharp
// Install: dotnet add package Amazon.CDK.Lib
IDatabaseInstance instance;

var metrics = DatabaseInstanceMetrics.FromDatabaseInstance(instance);

// How far a read replica lags behind its source (average over 5 minutes)
var replicaLag = metrics.ReplicaLag();

// The average amount of time taken per disk I/O read operation (average over 1 minute)
var readLatency = metrics.ReadLatency(new MetricOptions { Period = Duration.Seconds(60) });

// Any other metric, such as an engine-specific one
var binLogDiskUsage = metrics.Metric("BinLogDiskUsage", new MetricOptions { Statistic = "Maximum" });
```

Golang:

```go
// Install: go get github.com/aws/aws-cdk-go/awscdk/v2
var instance IDatabaseInstance

metrics := rds.DatabaseInstanceMetrics_FromDatabaseInstance(instance)

// How far a read replica lags behind its source (average over 5 minutes)
replicaLag := metrics.ReplicaLag()

// The average amount of time taken per disk I/O read operation (average over 1 minute)
readLatency := metrics.ReadLatency(&MetricOptions{
	Period: awscdk.Duration_Seconds(jsii.Number(60)),
})

// Any other metric, such as an engine-specific one
binLogDiskUsage := metrics.Metric(jsii.String("BinLogDiskUsage"), &MetricOptions{
	Statistic: jsii.String("Maximum"),
})
```

## Methods

- `burstBalance(props?: MetricOptions): Metric` — The percent of burst-bucket I/O credits available.

  This metric is available for DB instances that use General Purpose SSD (gp2) storage.

- `cpuUtilization(props?: MetricOptions): Metric` — The percentage of CPU utilization.

- `databaseConnections(props?: MetricOptions): Metric` — The number of client network connections to the database instance.

- `diskQueueDepth(props?: MetricOptions): Metric` — The number of outstanding I/Os (read/write requests) waiting to access the disk.

- `freeableMemory(props?: MetricOptions): Metric` — The amount of available random access memory.

- `freeStorageSpace(props?: MetricOptions): Metric` — The amount of available storage space.

- `fromDatabaseInstance(instance: IDBInstanceRef): DatabaseInstanceMetrics // chainable` (static) — Creates the metrics for the given database instance.

  **Parameters**

  - `instance` — The database instance to create the metrics for.

- `metric(metricName: string, props?: MetricOptions): Metric` — Return the given named metric for this database instance.

  If `dimensionsMap` is set, it replaces the default `DBInstanceIdentifier`
  dimension, so the metric no longer refers to this instance unless the new
  dimensions include it.

  **Parameters**

  - `metricName` — The name of the metric in the `AWS/RDS` namespace.
  - `props` — Properties to override on the metric.

- `networkReceiveThroughput(props?: MetricOptions): Metric` — The incoming (receive) network traffic on the DB instance, including both customer database traffic and Amazon RDS traffic used for monitoring and replication.

- `networkTransmitThroughput(props?: MetricOptions): Metric` — The outgoing (transmit) network traffic on the DB instance, including both customer database traffic and Amazon RDS traffic used for monitoring and replication.

- `readIOPS(props?: MetricOptions): Metric` — The average number of disk read I/O operations per second.

- `readLatency(props?: MetricOptions): Metric` — The average amount of time taken per disk I/O read operation.

- `readThroughput(props?: MetricOptions): Metric` — The average number of bytes read from disk per second.

- `replicaLag(props?: MetricOptions): Metric` — For read replica configurations, the amount of time a read replica DB instance lags behind the source DB instance.

  This metric is available for MariaDB, Microsoft SQL Server, MySQL, Oracle, and PostgreSQL read replicas.

- `swapUsage(props?: MetricOptions): Metric` — The amount of swap space used on the DB instance.

  This metric is available for MariaDB, MySQL, Oracle, and PostgreSQL DB instances.

- `writeIOPS(props?: MetricOptions): Metric` — The average number of disk write I/O operations per second.

- `writeLatency(props?: MetricOptions): Metric` — The average amount of time taken per disk I/O write operation.

- `writeThroughput(props?: MetricOptions): Metric` — The average number of bytes written to disk per second.
