feat: Allow group identifiers to be used in wr.cloudwatch queries (#2430)

Author: LeonLuttenberger

awswrangler/cloudwatch.py

@@ -40,17 +40,17 @@ def start_query(
 
     Parameters
     ----------
-    query : str
+    query: str
         The query string.
-    log_group_names : str
-        The list of log groups to be queried. You can include up to 20 log groups.
-    start_time : datetime.datetime
+    log_group_names: List[str]
+        The list of log group names or ARNs to be queried. You can include up to 50 log groups.
+    start_time: datetime.datetime
         The beginning of the time range to query.
-    end_time : datetime.datetime
+    end_time: datetime.datetime
         The end of the time range to query.
-    limit : Optional[int]
+    limit: Optional[int]
         The maximum number of log events to return in the query.
-    boto3_session : boto3.Session(), optional
+    boto3_session: boto3.Session(), optional
         Boto3 Session. The default boto3 session will be used if boto3_session receive None.
 
     Returns
@@ -79,15 +79,19 @@ def start_query(
     _logger.debug("start_timestamp: %s", start_timestamp)
     _logger.debug("end_timestamp: %s", end_timestamp)
 
-    _validate_args(start_timestamp=start_timestamp, end_timestamp=end_timestamp)
+    _validate_args(
+        start_timestamp=start_timestamp,
+        end_timestamp=end_timestamp,
+    )
     args: Dict[str, Any] = {
-        "logGroupNames": log_group_names,
+        "logGroupIdentifiers": log_group_names,
         "startTime": start_timestamp,
         "endTime": end_timestamp,
         "queryString": query,
     }
     if limit is not None:
         args["limit"] = limit
+
     client_logs = _utils.client(service_name="logs", session=boto3_session)
     response = client_logs.start_query(**args)
     return response["queryId"]
@@ -159,8 +163,8 @@ def run_query(
     ----------
     query : str
         The query string.
-    log_group_names : str
-        The list of log groups to be queried. You can include up to 20 log groups.
+    log_group_names: List[str]
+        The list of log group names or ARNs to be queried. You can include up to 50 log groups.
     start_time : datetime.datetime
         The beginning of the time range to query.
     end_time : datetime.datetime
@@ -210,17 +214,17 @@ def read_logs(
 
     Parameters
     ----------
-    query : str
+    query: str
         The query string.
-    log_group_names : str
-        The list of log groups to be queried. You can include up to 20 log groups.
-    start_time : datetime.datetime
+    log_group_names: List[str]
+        The list of log group names or ARNs to be queried. You can include up to 50 log groups.
+    start_time: datetime.datetime
         The beginning of the time range to query.
-    end_time : datetime.datetime
+    end_time: datetime.datetime
         The end of the time range to query.
-    limit : Optional[int]
+    limit: Optional[int]
         The maximum number of log events to return in the query.
-    boto3_session : boto3.Session(), optional
+    boto3_session: boto3.Session(), optional
         Boto3 Session. The default boto3 session will be used if boto3_session receive None.
 
     Returns
@@ -384,15 +388,15 @@ def filter_log_events(
 
     Note
     ----
-    Cannot call filter_log_events with both log_stream_names and log_stream_name_prefix.
+    Cannot call ``filter_log_events`` with both ``log_stream_names`` and ``log_stream_name_prefix``.
 
     Parameters
     ----------
-    log_group_name : str
+    log_group_name: str
         The name of the log group.
-    log_stream_name_prefix : str
+    log_stream_name_prefix: str, optional
         Filters the results to include only events from log streams that have names starting with this prefix.
-    log_stream_names: List[str]
+    log_stream_names: List[str], optional
         Filters the results to only logs from the log streams in this list.
     filter_pattern : str
         The filter pattern to use. If not provided, all the events are matched.
@@ -432,7 +436,7 @@ def filter_log_events(
     """
     if log_stream_name_prefix and log_stream_names:
         raise exceptions.InvalidArgumentCombination(
-            "Cannot call filter_log_events with both log_stream_names and log_stream_name_prefix"
+            "Cannot call `filter_log_events` with both `log_stream_names` and `log_stream_name_prefix`"
         )
     _logger.debug("log_group_name: %s", log_group_name)
 

tests/unit/test_cloudwatch.py

@@ -12,7 +12,7 @@
 pytestmark = pytest.mark.distributed
 
 
-def test_query_cancelled(loggroup):
+def test_query_cancelled(loggroup: str) -> None:
     client_logs = boto3.client("logs")
     with pytest.raises(exceptions.QueryCancelled):
         while True:
@@ -28,7 +28,7 @@ def test_query_cancelled(loggroup):
         wr.cloudwatch.wait_query(query_id=query_id)
 
 
-def test_start_and_wait_query(loggroup):
+def test_start_and_wait_query(loggroup: str) -> None:
     query_id = wr.cloudwatch.start_query(
         log_group_names=[loggroup], query="fields @timestamp, @message | sort @timestamp desc | limit 5"
     )
@@ -38,23 +38,32 @@ def test_start_and_wait_query(loggroup):
     assert len(results[0]) == 3
 
 
-def test_query(loggroup):
+def test_query(loggroup: str) -> None:
     results = wr.cloudwatch.run_query(
         log_group_names=[loggroup], query="fields @timestamp, @message | sort @timestamp desc | limit 5"
     )
     assert len(results) == 5
     assert len(results[0]) == 3
 
 
-def test_read_logs(loggroup):
+def test_read_logs(loggroup: str) -> None:
     df = wr.cloudwatch.read_logs(
         log_group_names=[loggroup], query="fields @timestamp, @message | sort @timestamp desc | limit 5", limit=5
     )
     assert len(df.index) == 5
     assert len(df.columns) == 3
 
 
-def test_describe_log_streams_and_filter_log_events(loggroup):
+def test_read_logs_by_log_group_arn(loggroup: str, account_id: str, region: str) -> None:
+    loggroup_arn = f"arn:aws:logs:{region}:{account_id}:log-group:{loggroup}"
+    df = wr.cloudwatch.read_logs(
+        log_group_names=[loggroup_arn], query="fields @timestamp, @message | sort @timestamp desc | limit 5", limit=5
+    )
+    assert len(df.index) == 5
+    assert len(df.columns) == 3
+
+
+def test_describe_log_streams_and_filter_log_events(loggroup: str) -> None:
     cloudwatch_log_client = boto3.client("logs")
     log_stream_names = [
         "aws_sdk_pandas_log_stream_one",