AWSLogs CLI Tool

Common errors

• awslogs: command not found

  cause The `awslogs` executable is not installed or not available in the system's PATH.
  fix Install the package using `pip install awslogs`. If installed, ensure `~/.local/bin` (or equivalent pip install location) is in your system's PATH environment variable.

• No credentials found. Unable to authenticate.

  cause The `awslogs` tool could not find valid AWS credentials in any of the expected locations (environment variables, AWS config/credentials files, IAM instance profile).
  fix Run `aws configure` to set up your AWS credentials and default region, or manually set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_DEFAULT_REGION` environment variables.

• An error occurred (ResourceNotFoundException) when calling the DescribeLogGroups operation: The specified log group does not exist.

  cause The provided log group name is incorrect, misspelled, or does not exist in the AWS region that `awslogs` is configured to use.
  fix Verify the exact log group name and ensure the correct AWS region is specified (e.g., via `--region` flag, `AWS_DEFAULT_REGION` env var, or `aws configure`). Use `awslogs groups` to list available log groups.

Warnings

• breaking `awslogs` requires Python 3.8 or newer. Running it in older Python environments (e.g., Python 2.x or Python 3.7 and below) will result in installation or runtime errors.
  Fix: Ensure your environment uses Python 3.8 or later. Upgrade Python or use a virtual environment with a compatible version.
• gotcha Authentication failures are common if AWS credentials are not correctly configured. `awslogs` relies on the standard AWS credential chain (environment variables, shared credential file `~/.aws/credentials`, IAM roles).
  Fix: Configure AWS CLI using `aws configure` or set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_DEFAULT_REGION` environment variables.
• gotcha Incorrect IAM permissions for the AWS user or role accessing CloudWatch Logs can lead to 'AccessDeniedException'.
  Fix: Ensure the IAM policy associated with your credentials has `logs:GetLogEvents`, `logs:DescribeLogGroups`, and `logs:DescribeLogStreams` permissions for the relevant resources.

Install

• pip install awslogs Install with pip

Quickstart

This quickstart demonstrates how to programmatically execute the `awslogs` command-line tool using Python's `subprocess` module. It attempts to retrieve recent log events from a specified CloudWatch Log Group. Users must have AWS credentials configured (e.g., via `aws configure` or environment variables) and specify an existing log group name and optionally an AWS profile and region.

import subprocess
import os

# Ensure AWS credentials are set up (e.g., via AWS CLI 'aws configure' or environment variables)
# For demonstration, we'll try to get logs from a common AWS Lambda log group.
# Replace 'my-lambda-function' with an actual Lambda function name in your AWS account.
# Set the AWS_DEFAULT_REGION environment variable or configure it via `aws configure`.
# Example: os.environ['AWS_DEFAULT_REGION'] = 'us-east-1'

try:
    # List log groups (example for initial exploration)
    # result = subprocess.run(['awslogs', 'groups', '--profile', os.environ.get('AWS_PROFILE', 'default')], capture_output=True, text=True, check=True)
    # print('Available Log Groups:\n', result.stdout)

    # Get logs from a specific group (replace with a real log group name)
    log_group_name = '/aws/lambda/my-example-function'
    print(f"Attempting to retrieve logs from: {log_group_name}")
    
    # Run the awslogs command to get logs from a hypothetical Lambda function for the last hour
    # Using --start='1h ago' to limit output for quickstart
    cmd = ['awslogs', 'get', log_group_name, '--start', '1h ago', '--profile', os.environ.get('AWS_PROFILE', 'default')]
    
    # It's good practice to specify --region if not set via environment variables or AWS CLI config
    # For example: cmd = ['awslogs', 'get', log_group_name, '--start', '1h ago', '--region', os.environ.get('AWS_DEFAULT_REGION', 'us-east-1')]

    # Execute the command
    process = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
    
    # Read output line by line
    for line in process.stdout:
        print(line.strip())
    
    # Check for errors
    stderr_output = process.stderr.read()
    if process.wait() != 0:
        print(f"Error executing awslogs: {stderr_output}")
    elif stderr_output:
        print(f"awslogs warnings/info: {stderr_output}")

except FileNotFoundError:
    print("Error: 'awslogs' command not found. Please ensure it is installed and in your system's PATH.")
except subprocess.CalledProcessError as e:
    print(f"Error during awslogs execution: {e.stderr}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")