PaperWatch

A tool for automatically forwarding CloudWatch logs from other AWS services or other AWS Lambda functions to Papertrail.

Setup

Follow these steps to set up and deploy PaperWatch to AWS:

Configure

The Lambda functions read the following configuration information from config/paperwatch.json:

Key	Required	Type	Description
host	Yes	String	The paper trail endpoint's address.
port	Yes	Number	The paper trail endpoint's port.
consumer	Yes	String	The name of the consumer function. Used by the Subscribe function to avoid subscribing the consumer to itself. Do not change unless you are modifying the deploy.cfn.json template.
retentionPeriod	No	Number	If included, updates the CloudWatch log group's retention period (in days).
sources	Yes	Array of Objects	List of log sources. A log source is identified by the prefix property. Logs generated by a source are passed to its consumer function. Default configuration includes log sources for Lambda functions and CloudTrail.
exclude	No	Array of Strings	List of lambda function names that the Subscribe function should ignore.

Example config

{
  "host": "logsN.papertrailapp.com",
  "port": XXXXX,
  "sources": [
    {
      "prefix": "/aws/lambda/",
      "consumer": "LambdaLogConsumer"
    },
    {
      "prefix": "CloudTrail/",
      "consumer": "CloudTrailConsumer"
    }
  ]
  "exclude": [
    "TestFunction",
    "LoudFunction"
  ]
}

Build

Running the build script will install dependencies and create the .zip deployment package, as lambda.zip.

paperwatch $ npm run build

Deploy

First, upload the deployment package to an S3 bucket. Take note of the bucket name; you will need this later. This can be done with the aws-cli as follows:

paperwatch $ aws s3 cp ./lambda.zip s3://<BUCKET_NAME>

Next, create a new CloudFormation stack using from the template at cfn/deploy.cfn.json. Enter a stack name. You will also be prompted to enter the following parameters:

• SourceBucket - the name of the s3 bucket you uploaded the deployment package to
• SourceKey - name of the deployment package in the s3 bucket (lambda.zip), including any prefixes if applicable

Once deployed, logs will be forwarded to papertrail for all new lambda functions.
Existing functions and other services must be subscribed manually.

Manual Subscription

To manually subscribe a function or log group, navigate to the CloudWatch console and follow these steps:

1. Locate the log group for the function or service you wish to subscribe, and select it by checking the box on the left.
2. Open the Actions dropdown and choose Stream to AWS Lambda.
3. From the Lambda Function dropdown, select the consumer function (LambdaLogConsumer or CloudTrailConsumer by default), and click Next.
4. From the Log Format dropdown, select Other and click next
5. Click Start Streaming.

PaperWatch will begin forwarding the function or service's logs to Papertrail.