Introduction

CloudWatch Logs metric filters can match JSON fields, including items inside arrays. The important detail is that the filter syntax distinguishes between a specific array index such as [0] and a wildcard selector such as [*], and the wildcard form is more limited than many people expect.

Matching a Specific Array Element

If you know the position of the value, address it directly.

Given a log event like this:

1{
2  "eventType": "UpdateTrail",
3  "arrayKey": ["value", "another value"]
4}

You can match the first entry with this metric filter pattern:

{ $.arrayKey[0] = "value" }

That is the most precise form and usually the easiest one to debug.

Matching Any Element in the Array

CloudWatch also supports a wildcard selector for array elements. This is useful when the value might appear in any position.

{ $.arrayKey[*] = %val.{2}% }

In CloudWatch filter syntax, wildcard array matching is commonly paired with regex-style matching. The official examples show this pattern for checking whether any array element matches a regular expression.

For arrays of objects, you can select a field under a specific element:

{ $.users[0].email = "[email protected]" }

You can also combine expressions:

{ ($.user.id = 1) && ($.users[0].email = "[email protected]") }

Testing the Pattern Before Creating the Metric Filter

Use the AWS CLI to test the filter against sample log events before you create alarms from it.

aws logs test-metric-filter \
  --filter-pattern '{ $.arrayKey[0] = "value" }' \
  --log-event-messages '{"arrayKey":["value","another value"]}'

That command is much faster than repeatedly editing filters in the console and waiting to see whether data appears.

Important Syntax Rules

A few rules matter a lot:

• array indexes are zero-based
• property selectors use JSON-style paths such as $.arrayKey[0]
• CloudWatch allows only one wildcard selector in a property selector
• keys containing a period can use bracket notation such as $.['cluster.name']

If the log event is not valid JSON, JSON field selectors do not apply. In that case you need a plain text or space-delimited filter instead.

When Metric Filters Are Not Enough

Metric filters are good for simple counters, thresholds, and alarms. If you need richer inspection, such as aggregating several matching elements or transforming nested arrays heavily, CloudWatch Logs Insights is often the better tool.

A useful rule of thumb is:

• metric filters for fast boolean-style matching that emits a metric
• Logs Insights for analysis and ad hoc querying

Arrays of Objects Need Exact Paths

When the array contains objects instead of strings, include both the array selector and the field name in the path. For example, a payload like users: [{\"role\":\"admin\"}] can be matched with a selector such as $.users[0].role = \"admin\". If the element position is unknown, you may need to redesign the log shape or move the analysis to Logs Insights, because metric filters do not provide full JSON querying semantics.

Common Pitfalls

The most common mistake is treating [*] as a fully general JSON query language. It is not. CloudWatch filter syntax is intentionally limited.

Another issue is testing multiline pretty-printed JSON. The examples need to be evaluated as single-line log events when you use the test API.

A third pitfall is assuming an array selector works on logs that were ingested as plain text instead of structured JSON.

Summary

• Use $.arrayKey[0] when you know the exact array position.
• Use $.arrayKey[*] when you need to match any element, typically with a regex-style pattern.
• Test filters with aws logs test-metric-filter before creating production alarms.
• Remember that array indexes are zero-based and wildcard support is limited.
• Switch to Logs Insights when the matching logic becomes more analytical than metric-oriented.