{"id":7965,"library":"awslogs","title":"AWSLogs CLI Tool","description":"awslogs is a simple command-line interface (CLI) tool designed to read and query Amazon CloudWatch Logs. It provides an intuitive way to interact with log groups, streams, and events directly from the terminal. The current version is 0.15.0, and releases are infrequent, indicating a stable tool focused on its core CLI functionality.","status":"active","version":"0.15.0","language":"en","source_language":"en","source_url":"https://github.com/jorgebastida/awslogs","tags":["aws","cloudwatch","logs","cli","monitoring","command-line-tool"],"install":[{"cmd":"pip install awslogs","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"AWS SDK for Python, used for interacting with AWS services like CloudWatch Logs.","package":"boto3","optional":false},{"reason":"Utilities for parsing and manipulating dates and times.","package":"python-dateutil","optional":false},{"reason":"Python timezone library.","package":"pytz","optional":false},{"reason":"Command-line interface creation kit.","package":"click","optional":false},{"reason":"Syntax highlighting for terminal output.","package":"Pygments","optional":false}],"imports":[],"quickstart":{"code":"import subprocess\nimport os\n\n# Ensure AWS credentials are set up (e.g., via AWS CLI 'aws configure' or environment variables)\n# For demonstration, we'll try to get logs from a common AWS Lambda log group.\n# Replace 'my-lambda-function' with an actual Lambda function name in your AWS account.\n# Set the AWS_DEFAULT_REGION environment variable or configure it via `aws configure`.\n# Example: os.environ['AWS_DEFAULT_REGION'] = 'us-east-1'\n\ntry:\n    # List log groups (example for initial exploration)\n    # result = subprocess.run(['awslogs', 'groups', '--profile', os.environ.get('AWS_PROFILE', 'default')], capture_output=True, text=True, check=True)\n    # print('Available Log Groups:\\n', result.stdout)\n\n    # Get logs from a specific group (replace with a real log group name)\n    log_group_name = '/aws/lambda/my-example-function'\n    print(f\"Attempting to retrieve logs from: {log_group_name}\")\n    \n    # Run the awslogs command to get logs from a hypothetical Lambda function for the last hour\n    # Using --start='1h ago' to limit output for quickstart\n    cmd = ['awslogs', 'get', log_group_name, '--start', '1h ago', '--profile', os.environ.get('AWS_PROFILE', 'default')]\n    \n    # It's good practice to specify --region if not set via environment variables or AWS CLI config\n    # For example: cmd = ['awslogs', 'get', log_group_name, '--start', '1h ago', '--region', os.environ.get('AWS_DEFAULT_REGION', 'us-east-1')]\n\n    # Execute the command\n    process = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)\n    \n    # Read output line by line\n    for line in process.stdout:\n        print(line.strip())\n    \n    # Check for errors\n    stderr_output = process.stderr.read()\n    if process.wait() != 0:\n        print(f\"Error executing awslogs: {stderr_output}\")\n    elif stderr_output:\n        print(f\"awslogs warnings/info: {stderr_output}\")\n\nexcept FileNotFoundError:\n    print(\"Error: 'awslogs' command not found. Please ensure it is installed and in your system's PATH.\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error during awslogs execution: {e.stderr}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your environment uses Python 3.8 or later. Upgrade Python or use a virtual environment with a compatible version.","message":"`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.","severity":"breaking","affected_versions":"<0.15.0 (for older Python versions), all versions requiring >=3.8"},{"fix":"Configure AWS CLI using `aws configure` or set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_DEFAULT_REGION` environment variables.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the IAM policy associated with your credentials has `logs:GetLogEvents`, `logs:DescribeLogGroups`, and `logs:DescribeLogStreams` permissions for the relevant resources.","message":"Incorrect IAM permissions for the AWS user or role accessing CloudWatch Logs can lead to 'AccessDeniedException'.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The `awslogs` executable is not installed or not available in the system's PATH.","error":"awslogs: command not found"},{"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.","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).","error":"No credentials found. Unable to authenticate."},{"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.","cause":"The provided log group name is incorrect, misspelled, or does not exist in the AWS region that `awslogs` is configured to use.","error":"An error occurred (ResourceNotFoundException) when calling the DescribeLogGroups operation: The specified log group does not exist."}]}