TestMetricFilter - Amazon CloudWatch Logs

Request Syntax Request Parameters Response Syntax Response Elements Errors Examples See Also

TestMetricFilter

Tests the filter pattern of a metric filter against a sample of log event messages. You can use this operation to validate the correctness of a metric filter pattern.

Request Syntax


{
   "filterPattern": "string",
   "logEventMessages": [ "string" ]
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

filterPattern

A symbolic description of how CloudWatch Logs should interpret the data in each log event. For example, a log event can contain timestamps, IP addresses, strings, and so on. You use the filter pattern to specify what to look for in the log event message.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1024.

Required: Yes

logEventMessages

The log event messages to test.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 50 items.

Length Constraints: Minimum length of 1.

Required: Yes

Response Syntax


{
   "matches": [ 
      { 
         "eventMessage": "string",
         "eventNumber": number,
         "extractedValues": { 
            "string" : "string" 
         }
      }
   ]
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

The matched events.

Type: Array of MetricFilterMatchRecord objects

Errors

For information about the errors that are common to all actions, see Common Errors.

InvalidParameterException

A parameter is specified incorrectly.

HTTP Status Code: 400

ServiceUnavailableException

The service cannot complete the request.

HTTP Status Code: 500

Examples

To test a metric filter pattern on Apache access.log events

The following example tests the specified metric filter pattern.

Sample Request


POST / HTTP/1.1
Host: logs.<region>.<domain>
X-Amz-Date: <DATE>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=content-type;date;host;user-agent;x-amz-date;x-amz-target;x-amzn-requestid, Signature=<Signature>
User-Agent: <UserAgentString>
Accept: application/json
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Connection: Keep-Alive
X-Amz-Target: Logs_20140328.TestMetricFilter
{
  "filterPattern": "[ip, identity, user_id, timestamp, request, status_code, size]",
  "logEventMessages": [
    "127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 1534",
    "127.0.0.1 - frank [10/Oct/2000:13:35:22 -0700] \"GET /apache_pb.gif HTTP/1.0\" 500 5324",
    "127.0.0.1 - frank [10/Oct/2000:13:50:35 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 4355"
  ]
}

Sample Response


HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>
{
  "matches": [
    {
      "eventNumber": 0, 
      "eventMessage": "127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 1534", 
      "extractedValues": {
        "$status_code": "200", 
        "$identity": "-", 
        "$request": "GET /apache_pb.gif HTTP/1.0", 
        "$size": "1534,", 
        "$user_id": "frank", 
        "$ip": "127.0.0.1", 
        "$timestamp": "10/Oct/2000:13:25:15 -0700"
      }
    }, 
    {
      "eventNumber": 1, 
      "eventMessage": "127.0.0.1 - frank [10/Oct/2000:13:35:22 -0700] \"GET /apache_pb.gif HTTP/1.0\" 500 5324", 
      "extractedValues": {
        "$status_code": "500", 
        "$identity": "-", 
        "$request": "GET /apache_pb.gif HTTP/1.0", 
        "$size": "5324,", 
        "$user_id": "frank", 
        "$ip": "127.0.0.1", 
        "$timestamp": "10/Oct/2000:13:35:22 -0700"
      }
    }, 
    {
      "eventNumber": 2, 
      "eventMessage": "127.0.0.1 - frank [10/Oct/2000:13:50:35 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 4355", 
      "extractedValues": {
        "$status_code": "200", 
        "$identity": "-", 
        "$request": "GET /apache_pb.gif HTTP/1.0", 
        "$size": "4355", 
        "$user_id": "frank", 
        "$ip": "127.0.0.1", 
        "$timestamp": "10/Oct/2000:13:50:35 -0700"
      }
    }
  ]
}

To test a metric filter pattern on Apache access.log events without specifying all the fields

The following example tests the specified metric filter pattern.

Sample Request


POST / HTTP/1.1
Host: logs.<region>.<domain>
X-Amz-Date: <DATE>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=content-type;date;host;user-agent;x-amz-date;x-amz-target;x-amzn-requestid, Signature=<Signature>
User-Agent: <UserAgentString>
Accept: application/json
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Connection: Keep-Alive
X-Amz-Target: Logs_20140328.TestMetricFilter
{
  "filterPattern": "[..., size]",
  "logEventMessages": [
    "127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 1534",
    "127.0.0.1 - frank [10/Oct/2000:13:35:22 -0700] \"GET /apache_pb.gif HTTP/1.0\" 500 5324",
    "127.0.0.1 - frank [10/Oct/2000:13:50:35 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 4355"
  ]
}

Sample Response


HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>
{
  "matches": [
    {
      "eventNumber": 0, 
      "eventMessage": "127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 1534", 
      "extractedValues": {
        "$size": "1534", 
        "$6": "200", 
        "$4": "10/Oct/2000:13:25:15 -0700", 
        "$5": "GET /apache_pb.gif HTTP/1.0", 
        "$2": "-", 
        "$3": "frank", 
        "$1": "127.0.0.1"
      }
    }, 
    {
      "eventNumber": 1, 
      "eventMessage": "127.0.0.1 - frank [10/Oct/2000:13:35:22 -0700] \"GET /apache_pb.gif HTTP/1.0\" 500 5324", 
      "extractedValues": {
        "$size": "5324", 
        "$6": "500", 
        "$4": "10/Oct/2000:13:35:22 -0700", 
        "$5": "GET /apache_pb.gif HTTP/1.0", 
        "$2": "-", 
        "$3": "frank", 
        "$1": "127.0.0.1"
      }
    }, 
    {
      "eventNumber": 2, 
      "eventMessage": "127.0.0.1 - frank [10/Oct/2000:13:50:35 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 4355", 
      "extractedValues": {
        "$size": "4355", 
        "$6": "200", 
        "$4": "10/Oct/2000:13:50:35 -0700", 
        "$5": "GET /apache_pb.gif HTTP/1.0", 
        "$2": "-", 
        "$3": "frank", 
        "$1": "127.0.0.1"
      }
    }
  ]
}

To test a metric filter pattern on Apache access.log events without specifying any fields

The following example tests the specified metric filter pattern.

Sample Request


POST / HTTP/1.1
Host: logs.<region>.<domain>
X-Amz-Date: <DATE>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=content-type;date;host;user-agent;x-amz-date;x-amz-target;x-amzn-requestid, Signature=<Signature>
User-Agent: <UserAgentString>
Accept: application/json
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Connection: Keep-Alive
X-Amz-Target: Logs_20140328.TestMetricFilter
{
  "filterPattern": "[]",
  "logEventMessages": [
    "127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 1534",
    "127.0.0.1 - frank [10/Oct/2000:13:35:22 -0700] \"GET /apache_pb.gif HTTP/1.0\" 500 5324",
    "127.0.0.1 - frank [10/Oct/2000:13:50:35 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 4355"
  ]
}

Sample Response


HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>
{
  "matches": [
    {
      "eventNumber": 0, 
      "eventMessage": "127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 1534", 
      "extractedValues": {
        "$7": "1534", 
        "$6": "200", 
        "$4": "10/Oct/2000:13:25:15 -0700", 
        "$5": "GET /apache_pb.gif HTTP/1.0", 
        "$2": "-", 
        "$3": "frank", 
        "$1": "127.0.0.1"
      }
    }, 
    {
      "eventNumber": 1, 
      "eventMessage": "127.0.0.1 - frank [10/Oct/2000:13:35:22 -0700] \"GET /apache_pb.gif HTTP/1.0\" 500 5324", 
      "extractedValues": {
        "$7": "5324", 
        "$6": "500", 
        "$4": "10/Oct/2000:13:35:22 -0700", 
        "$5": "GET /apache_pb.gif HTTP/1.0", 
        "$2": "-", 
        "$3": "frank", 
        "$1": "127.0.0.1"
      }
    }, 
    {
      "eventNumber": 2, 
      "eventMessage": "127.0.0.1 - frank [10/Oct/2000:13:50:35 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 4355", 
      "extractedValues": {
        "$7": "4355", 
        "$6": "200", 
        "$4": "10/Oct/2000:13:50:35 -0700", 
        "$5": "GET /apache_pb.gif HTTP/1.0", 
        "$2": "-", 
        "$3": "frank", 
        "$1": "127.0.0.1"
      }
    }
  ]
}

To test a metric filter pattern that matches successful requests in Apache access.log events

The following example tests the specified metric filter pattern.

Sample Request


POST / HTTP/1.1
Host: logs.<region>.<domain>
X-Amz-Date: <DATE>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=content-type;date;host;user-agent;x-amz-date;x-amz-target;x-amzn-requestid, Signature=<Signature>
User-Agent: <UserAgentString>
Accept: application/json
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Connection: Keep-Alive
X-Amz-Target: Logs_20140328.TestMetricFilter
{
  "filterPattern": "[..., status_code=200, size]",
  "logEventMessages": [
    "127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 1534",
    "127.0.0.1 - frank [10/Oct/2000:13:35:22 -0700] \"GET /apache_pb.gif HTTP/1.0\" 500 5324",
    "127.0.0.1 - frank [10/Oct/2000:13:50:35 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 4355"
  ]
}

Sample Response


HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>
{
  "matches": [
    {
      "eventNumber": 0, 
      "eventMessage": "127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 1534", 
      "extractedValues": {
        "$status_code": "200", 
        "$size": "1534", 
        "$4": "10/Oct/2000:13:25:15 -0700", 
        "$5": "GET /apache_pb.gif HTTP/1.0", 
        "$2": "-", 
        "$3": "frank", 
        "$1": "127.0.0.1"
      }
    }, 
    {
      "eventNumber": 2, 
      "eventMessage": "127.0.0.1 - frank [10/Oct/2000:13:50:35 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 4355", 
      "extractedValues": {
        "$status_code": "200", 
        "$size": "4355", 
        "$4": "10/Oct/2000:13:50:35 -0700", 
        "$5": "GET /apache_pb.gif HTTP/1.0", 
        "$2": "-", 
        "$3": "frank", 
        "$1": "127.0.0.1"
      }
    }
  ]
}

To test a metric filter pattern that matches 4XX response codes for HTML pages in Apache access.log events

The following example tests the specified metric filter pattern.

Sample Request


POST / HTTP/1.1
Host: logs.<region>.<domain>
X-Amz-Date: <DATE>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=content-type;date;host;user-agent;x-amz-date;x-amz-target;x-amzn-requestid, Signature=<Signature>
User-Agent: <UserAgentString>
Accept: application/json
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Connection: Keep-Alive
X-Amz-Target: Logs_20140328.TestMetricFilter
{
  "filterPattern": "[..., request=*.html*, status_code=4*,]",
  "logEventMessages": [
    "127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] \"GET /index.html HTTP/1.0\" 404 1534",
    "127.0.0.1 - frank [10/Oct/2000:13:35:22 -0700] \"GET /about-us/index.html HTTP/1.0\" 200 5324",
    "127.0.0.1 - frank [10/Oct/2000:13:50:35 -0700] \"GET /apache_pb.gif HTTP/1.0\" 404 4355",
    "127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] \"GET /products/index.html HTTP/1.0\" 400 1534",
  ]
}

Sample Response


HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>
{
  "matches": [
    {
      "eventNumber": 0, 
      "eventMessage": "127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] \"GET /index.html HTTP/1.0\" 404 1534", 
      "extractedValues": {
        "$status_code": "404", 
        "$request": "GET /index.html HTTP/1.0", 
        "$7": "1534", 
        "$4": "10/Oct/2000:13:25:15 -0700", 
        "$2": "-", 
        "$3": "frank", 
        "$1": "127.0.0.1"
      }
    }, 
    {
      "eventNumber": 3, 
      "eventMessage": "127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] \"GET /products/index.html HTTP/1.0\" 400 1534", 
      "extractedValues": {
        "$status_code": "400", 
        "$request": "GET /products/index.html HTTP/1.0", 
        "$7": "1534", 
        "$4": "10/Oct/2000:13:25:15 -0700", 
        "$2": "-", 
        "$3": "frank", 
        "$1": "127.0.0.1"
      }
    }
  ]
}

To test a metric filter pattern that matches occurrences of "[ERROR]" in log events

The following example tests the specified metric filter pattern.

Sample Request


POST / HTTP/1.1
Host: logs.<region>.<domain>
X-Amz-Date: <DATE>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=content-type;date;host;user-agent;x-amz-date;x-amz-target;x-amzn-requestid, Signature=<Signature>
User-Agent: <UserAgentString>
Accept: application/json
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Connection: Keep-Alive
X-Amz-Target: Logs_20140328.TestMetricFilter
{
  "filterPattern": "\"[ERROR]\"",
  "logEventMessages": [
    "02 May 2014 00:34:12,525 [INFO] Starting the application",
    "02 May 2014 00:35:14,245 [DEBUG] Database connection established",
    "02 May 2014 00:34:14,663 [INFO] Executing SQL Query",
    "02 May 2014 00:34:16,142 [ERROR] Unhanded exception: InvalidQueryException",
    "02 May 2014 00:34:16,224 [ERROR] Terminating the application"
  ]
}

Sample Response


HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>
{
  "matches": [
    {
      "eventNumber": 3, 
      "eventMessage": "02 May 2014 00:34:16,142 [ERROR] Unhanded exception: InvalidQueryException", 
      "extractedValues": {}
    }, 
    {
      "eventNumber": 4, 
      "eventMessage": "02 May 2014 00:34:16,224 [ERROR] Terminating the application", 
      "extractedValues": {}
    }
  ]
}

To test a metric filter pattern that matches occurrences of "[ERROR]" and "Exception" in log events

The following example tests the specified metric filter pattern.

Sample Request


POST / HTTP/1.1
Host: logs.<region>.<domain>
X-Amz-Date: <DATE>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=content-type;date;host;user-agent;x-amz-date;x-amz-target;x-amzn-requestid, Signature=<Signature>
User-Agent: <UserAgentString>
Accept: application/json
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Connection: Keep-Alive
X-Amz-Target: Logs_20140328.TestMetricFilter
{
  "filterPattern": "\"[ERROR]\" Exception",
  "logEventMessages": [
    "02 May 2014 00:34:12,525 [INFO] Starting the application",
    "02 May 2014 00:35:14,245 [DEBUG] Database connection established",
    "02 May 2014 00:34:14,663 [INFO] Executing SQL Query",
    "02 May 2014 00:34:16,142 [ERROR] Unhanded exception: InvalidQueryException",
    "02 May 2014 00:34:16,224 [ERROR] Terminating the application"
  ]
}

Sample Response


HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>
{
  "matches": [
    {
      "eventNumber": 3, 
      "eventMessage": "02 May 2014 00:34:16,142 [ERROR] Unhanded exception: InvalidQueryException", 
      "extractedValues": {}
    }
  ]
}

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following:

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

TagResource

UntagLogGroup