These instructions will describe the steps to deploy the Lambda function which forwards CloudWatch events to SignalFx as Custom Events. The deployed function uses SignalFx Lambda Wrapper and can be easily modified to send other types of Custom Events to SignalFx, or to transform CloudWatch events before sending (for example, to filter only selected fields or to use different field names).
There are two ways to install this Lambda function: using AWS Serverless Repository (recommended) or AWS Lambda Console.
After installation, this Lambda function will be triggered by a CloudWatch Event or a CloudWatch Event rule. You should use the rules to filter the CloudWatch Events you want to be forwarded.
To retrieve your access token:
This value will be later used as a SignalFx Access Token.
By default, this Function will send data to the us0 realm. As a result, if you are not in the us0 realm, then you must explicitly set your realm.
To locate your realm:
This value will be later used as a SignalFx Ingest Endpoint.
You will need to provide the Lambda Function with a SignalFx Access Token stored in an environment variable. As a best security practice, it is recommended that the token is encrypted using the Amazon Key Management Service. For the overview of this process see "Securing Environment Variables" section of AWS documentation.
In both installation methods, you have the option to use either encrypted or plain token variable.
In order to encrypt SignalFx Access Token, please make sure you have a managed Symmetric KMS key available for use.
Regardless of the key creation method, make sure you have access to the cipher text output as well as the key id of the encryption key you used.
You can install this function in two ways:
In this option, you will deploy an Application from Serverless Application Repository. A Lambda Layer, Lambda Function, CloudWatch Event Rule and all necessary configurations will be created for you. This is a recommended and less time-consuming option.
NOTE: If you choose a version with token encryption, it will be by default configured to omit the events from aws.kms.
The reason for this behavior is to avoid an infinite loop: when the lambda runs, it decrypts the token and thus generates a Cloudwatch Event.
Sign in to the AWS Management Console and open the Serverless Application Repository console.
Choose "Available Applications" and search for "SignalFx CloudWatch Event Forwarder" or "SignalFx CloudWatch Event Forwarder - encrypted" application.
Click on the right application entry, depending if you wish to encrypt the token environment variable in transit.
Set the Application Name to describe the application's purpose in your environment, for example SignalFx CloudWatch Event Forwarder App.
Set the EventSources parameter to include the services from which you want to forward events to SignalFx.
Enter a comma delimited list to specify multiple services as sources, for example: aws.ec2,aws.s3. Please be aware that including aws.lambda may lead to invocation loop (e.g. if you have two lambdas which react on aws.lambda they will cause invocation loop). If you use encrypted version please avoid aws.kms as it leads to invocation loop.
Note: You will be later able to modify the Event Pattern in CloudWatch Events console.
If you chose version without encryption, set SignalFxAccessToken to the SignalFx Access Token value you identified in Prerequisites.
If you chose version with encryption, set EncryptedSignalFxAccessToken to the value of SignalFx Access Token identified in Prerequisites encrypted with a prepared KMS key.
Set the KeyId parameter to the Key Id of this key; it is the last section of the key's ARN.
Set SignalFxIngestEndpoint parameter to the SignalFx Ingest Endpoint value you identified in Prerequisites.
You may leave SignalFxSendTimeout parameter with a default value of 1000 ms.
Acknowledge that the Application contains nested application. The nested application is a SignalFx Lambda Wrapper for Node.js deployed as a Lambda Layer.
In this option, you will create a Lambda function and manually configure its dependencies, environment variables and a trigger. While more time consuming, it will give you better understanding of the inner workings of the process.
Sign in to the AWS Management Console and open the AWS Lambda console and switch to the target region. Review the note below on choosing a region.
To benefit from the most convenient installation procedure, use one of the regions for which we provide a SignalFx Lambda Wrapper as Layer. To confirm that the region is supported, locate its Layer ARN here. If you wish to install in the region which is not supported, you can still do so, but you will need to deploy the copy of the Layer to your account, using Serverless Application Repository. The steps to accomplish this can be found here.
Click "Create function" and choose the first option "Author from scratch".
Enter a function name, for example cloudwatch-event-forwarder.
Choose Node 12.x as a runtime.
Let AWS create a new role with basic Lambda permissions or choose the existing role depending on how you manage permissions in your account.
Click "Create function."
cloudwatch-event-forwarder.js file to the Console Editor.index.handler.NOTE: Alternative scripts:
Instead of the default cloudwatch-event-forwarder.js file, you can copy any of the following files if they better suit your needs:
examples/cloudwatch-event-forwarder-no-encryption.js. The default forwarder will work, but the one without encryption has much simpler code.examples/cloudwatch-event-forwarder-custom.js as a base and change accordingly.SIGNALFX_AUTH_TOKEN to the SignalFx Access Token value you identified when preparing Prerequisites.SIGNALFX_INGEST_ENDPOINT to the SignalFx Ingest Endpoint value you identified when preparing Prerequisites.SIGNALFX_SEND_TIMEOUT to a value in milliseconds. Default: 1000.ENCRYPTED_SIGNALFX_AUTH_TOKEN variable, set its value to the SignalFx Access Token identified when following the Prerequisites. Click "Encrypt" next to the variable and choose a key to perform the encryption.SIGNALFX_INGEST_ENDPOINT to the SignalFx Access Token value you identified when preparing Prerequisites.SIGNALFX_SEND_TIMEOUT to a value in milliseconds. Default: 1000.NOTE: the list of services available in the Lambda Designer is a short list of most common choices. If you need a richer editor and all the sources available, you can create the rule through CloudWatch Events console and select the target there.
You're ready! The integration is now configured. See here how to view and use events in SignalFx.
SignalFx Custom Event needs to be sent as a key-value map. This Lambda function will transform any CloudWatch event to conform to naming and format restrictions of a SignalFx, and then forward it to SignalFx.
If the default behavior does not suit your needs, please see the examples on how to build and send SignalFx Custom Events.
By default, based on a Cloudwatch Event, this lambda will create a SignalFx Custom Event in a following way:
USER_DEFINEDCloudWatchsource, account, detail-type, region keys which are common for all CloudWatch events and have a limited set of possible values will be sent as dimensions (detail-type will be sent as detailType)time property will be converted to Unix epoch time and sent as a timestamp of the SignalFx Custom Event.Other keys will be transformed in the ways listed below and sent as properties:
" " (space), ":" or "/" will be replaced with a "_" character. The allowed characters are [a-zA-Z0-9\-_].resources array will be stringified.id will be copied as is.detail section will be stringified and copied to the SignalFx Custom Event with a "detail_" prefix.
See exemplary transformation below.For example, a sample CloudWatch event:
{
"id":"7bf73129-1428-4cd3-a780-95db273d1602",
"detail-type":"EC2 Instance State-change Notification",
"source":"aws.ec2",
"account":"123456789012",
"time":"2015-11-11T21:29:54Z",
"region":"us-east-1",
"resources":[
"arn:aws:ec2:us-east-1:123456789012:instance/i-abcd1111"
],
"detail":{
"instance-id":"i-abcd1111",
"state":"pending",
"obj": {"key": "val"}
}
}will be transformed to a Custom SignalFx Event:
{
"category":"USER_DEFINED",
"eventType":"CloudWatch",
"dimensions":{
"detailType":"EC2 Instance State-change Notification",
"source":"aws.ec2",
"account":"123456789012",
"region":"us-east-1"
},
"properties":{
"id":"7bf73129-1428-4cd3-a780-95db273d1602",
"resources":"[\"arn:aws:ec2:us-east-1:123456789012:instance/i-abcd1111\"]",
"detail_instance-id":"i-abcd1111",
"detail_state":"pending",
"detail_obj":"{\"key\":\"val\"}"
},
"timestamp":1447277394000
}