# AWS CloudTrail Client Package #

**aws.cloudtrail** is a simple client package for the Amazon Web Services (AWS) [CloudTrail](http://aws.amazon.com/awscloudtrail/) REST API, which can be used to monitor use of AWS web services API calls by logging API requests in an S3 bucket.

## Installation ##

[![Build Status](https://travis-ci.org/cloudyr/aws.cloudtrail.png?branch=master)](https://travis-ci.org/cloudyr/aws.cloudtrail)

To install the latest development version from GitHub, run the following:

```R
if(!require("devtools")){
    install.packages("devtools")
    library("devtools")
}
install_github("cloudyr/aws.cloudtrail")
```

To install the latest version from CRAN, simply use `install.packages("aws.cloudtrail")`.


## Code Examples ##

A CloudTrail is a log of API calls made to AWS. The service is incredibly easy to use. It simply requires creating a trail that defines where (i.e., in what AWS S3 bucket) the CloudTrail log should be stored.

To use CloudTrail, start by creating an S3 bucket. This can be done using the **aws.s3** package:

```{r}
library("aws.cloudtrail")
library("aws.s3")
putbucket("MyExampleBucket")
```

```{r}
trail <- create_trail(name = "NewTrail", bucket = "MyExampleBucket")
get_trails() # see trail in list of trails
```

Note: The s3 bucket should exist (perhaps created using **aws.s3**) and have write permissions granted to CloudTrail. An example permission document is provided by `cloudtrail_s3policy()`.

Once a trail is created, it can be updated (e.g., to move it to a different bucket, to activate event notifications using SNS, etc.) using `update_trail()`.

```{r}
# move trail to another bucket
putbucket("MyOtherExampleBucket")
update_trail(name = "NewTrail", bucket = "MyOtherExampleBucket")

# send SNS notifications when log updated
update_trail(name = "NewTrail", sns_topic = "arn:aws:sns:us-east-1:123456789012:My-Topic")

# log global calls (e.g., IAM)
update_trail(name = "NewTrail", global = TRUE)
```

Once created and configured, it is easy to start logging requests using `start_logging()` and stop logging using `stop_logging()`:

```{r}
start_logging(trail$Name)
trail_status(trail$Name)$IsLogging # check logging status
stop_logging(trail$Name)
```

If you're done with a trail, you can delete it and it will no longer show up in your trail list:

```{r}
delete_trail(trail$Name)
get_trails()
```

---
[![cloudyr project logo](http://i.imgur.com/JHS98Y7.png)](https://github.com/cloudyr)