Skip to content

opensite-ai/opensite-skills / aws-observability

aws-observability

Unverified

Builds, configures, debugs, and optimizes AWS observability - operator-symptom questions and detecting Omni vs classic CloudWatch. CloudWatch on an already-reporting service: Log Insights, metric/composite/anomaly alarms, custom metrics/EMF, dashboards, X-Ray/ADOT tracing, canaries, CloudTrail, Dynamic Instrumentation (live breakpoints/snapshots), the Application Signals service map, and fleet health views. CloudWatch Omni on an existing Space: SQL over logs and traces, PromQL over metrics, Omni dashboards, Omni alerts, context graph for root cause, programmatic/IaC access (API/SDK/CLI/CloudFormation), driving Omni from a coding agent or skills, and evaluating AI agent quality from traces - on-demand and online scoring of live traffic, readback, custom evaluators. For first-time setup - creating an Omni Space, granting access, ingestion, or ADOT instrumentation for Application Signals (ServiceEvents, CI/CD metadata) or Omni - use setting-up-cloudwatch-observability. Not for app logging or threat detection.

FileKindSize
.aws-skill-metadataother18 B
SKILL.mdskill md28.3 KB
assets/cloudwatch/alarm-template.tsscript3.9 KB
assets/cloudwatch/otel-config.yamlconfig1.9 KB
references/cloudwatch-omni/agent-evaluation.mdmarkdown98.9 KB
references/cloudwatch-omni/alerts.mdmarkdown103.3 KB
references/cloudwatch-omni/concepts.mdmarkdown28.8 KB
references/cloudwatch-omni/context-graph.mdmarkdown29.2 KB
references/cloudwatch-omni/dashboards.mdmarkdown75.5 KB
references/cloudwatch-omni/programmatic-access.mdmarkdown8.6 KB
references/cloudwatch-omni/query/promql-metrics.mdmarkdown63.9 KB
references/cloudwatch-omni/query/sql-logs-traces.mdmarkdown43.0 KB
references/cloudwatch-omni/query/views.mdmarkdown12.7 KB
references/cloudwatch/alarms.mdmarkdown11.5 KB
references/cloudwatch/cloudtrail.mdmarkdown5.3 KB
references/cloudwatch/dashboards.mdmarkdown5.8 KB
references/cloudwatch/dynamic-instrumentation.mdmarkdown39.4 KB
references/cloudwatch/dynamic-instrumentation/breakpoint-creation.mdmarkdown16.3 KB
references/cloudwatch/dynamic-instrumentation/call-tree-and-directions.mdmarkdown5.7 KB
references/cloudwatch/dynamic-instrumentation/snapshot-parsing.mdmarkdown4.2 KB
references/cloudwatch/log-insights.mdmarkdown7.0 KB
references/cloudwatch/metrics.mdmarkdown7.4 KB
references/cloudwatch/synthetics.mdmarkdown6.5 KB
references/cloudwatch/tracing.mdmarkdown9.4 KB
references/cloudwatch/troubleshooting.mdmarkdown7.5 KB
scripts/cloudwatch-omni/capture_dataset_from_traces.pyscript19.2 KB
scripts/cloudwatch-omni/evaluate_traces.pyscript41.8 KB
scripts/cloudwatch-omni/test_evaluate_traces.pyscript12.0 KB
scripts/cloudwatch/di_app_signals_client.pyscript3.3 KB
scripts/cloudwatch/di_capture.pyscript8.5 KB
scripts/cloudwatch/di_constants.pyscript560 B
scripts/cloudwatch/di_crud_rendering.pyscript13.1 KB
scripts/cloudwatch/di_crud_tools.pyscript28.8 KB
scripts/cloudwatch/di_error_translation.pyscript5.6 KB
scripts/cloudwatch/di_formatting.pyscript992 B
scripts/cloudwatch/di_gateway.pyscript7.0 KB
scripts/cloudwatch/di_instrumentation.pyscript13.0 KB
scripts/cloudwatch/di_location.pyscript15.3 KB
scripts/cloudwatch/di_logs_client.pyscript4.2 KB
scripts/cloudwatch/di_region.pyscript2.0 KB
scripts/cloudwatch/di_result.pyscript2.0 KB
scripts/cloudwatch/di_session.pyscript2.0 KB
scripts/cloudwatch/di_snapshot_parsing.pyscript11.4 KB
scripts/cloudwatch/di_snapshot_queries.pyscript2.4 KB
scripts/cloudwatch/di_snapshot_rendering.pyscript12.5 KB
scripts/cloudwatch/di_snapshot_tools.pyscript12.0 KB
scripts/cloudwatch/di_snapshots.pyscript12.8 KB
scripts/cloudwatch/di_status_assessment.pyscript4.7 KB
scripts/cloudwatch/di_status_rendering.pyscript11.8 KB
scripts/cloudwatch/di_status_tools.pyscript13.0 KB
scripts/cloudwatch/di_validation.pyscript11.2 KB

scripts/cloudwatch/di_error_translation.py

View on GitHub
"""Translate botocore exceptions into the human-readable failure text used by the operations.

Replaces the ad-hoc ``Failed to ...`` blocks that the AWS-CLI-based code
emitted from ``subprocess`` failure ladders. Keeps the section headers
(``Error:``, ``ATTEMPTED PARAMETERS:``, ``POSSIBLE CAUSES:``,
``TROUBLESHOOTING:``) so callers see no contract change.
"""

from typing import Mapping, Optional, Sequence

from botocore.exceptions import (
    ClientError,
    ConnectTimeoutError,
    EndpointConnectionError,
    NoCredentialsError,
    PartialCredentialsError,
    ReadTimeoutError,
)


def _format_block(label: str, context: Optional[Mapping[str, object]]) -> str:
    if not context:
        return ""
    lines = []
    for key, value in context.items():
        if value is None or value == "":
            continue
        lines.append(f"- {key}: {value}")
    if not lines:
        return ""
    return f"\n{label}\n" + "\n".join(lines) + "\n"


def _format_attempted_block(context: Optional[Mapping[str, object]]) -> str:
    return _format_block("ATTEMPTED PARAMETERS:", context)


def _format_numbered_section(label: str, items: Optional[Sequence[str]]) -> str:
    if not items:
        return ""
    body = "\n".join(f"{idx}. {item}" for idx, item in enumerate(items, 1))
    return f"\n{label}\n{body}\n"


def _client_error_body(exc: ClientError) -> tuple[str, str]:
    error = exc.response.get("Error", {}) if isinstance(exc.response, dict) else {}
    code = error.get("Code") or "ClientError"
    message = error.get("Message") or str(exc)
    return code, message


def render_client_error(
    exc: ClientError,
    *,
    action: str,
    attempted_label: str = "ATTEMPTED PARAMETERS:",
    attempted: Optional[Mapping[str, object]] = None,
    possible_causes: Optional[Sequence[str]] = None,
    troubleshooting: Optional[Sequence[str]] = None,
    trailer: Optional[str] = None,
) -> str:
    """Render a tool-tailored failure block for a botocore ``ClientError``.

    Tools share the same skeleton — ``Failed to {action}``, an ``Error:`` line,
    an attempted-values block, and ``POSSIBLE CAUSES`` / ``TROUBLESHOOTING``
    numbered sections — but each tool tunes the labels and bullet content.
    This helper takes those bullets as parameters so each call site can keep
    its CLI-era wording without re-implementing the skeleton.

    Use ``trailer`` for any tool-specific footer (e.g. the location
    troubleshooting block emitted after a failed create).
    """
    code, message = _client_error_body(exc)
    sections = [
        f"Failed to {action}\n",
        f"\nError: {code} - {message}\n",
        _format_block(attempted_label, attempted),
        _format_numbered_section("POSSIBLE CAUSES:", possible_causes),
        _format_numbered_section("TROUBLESHOOTING:", troubleshooting),
    ]
    body = "".join(sections).rstrip()
    if trailer:
        return f"{body}\n\n{trailer}"
    return body


def translate_aws_error(
    exc: BaseException,
    *,
    action: str,
    context: Optional[Mapping[str, object]] = None,
) -> str:
    """Render a human-readable failure block for an AWS API exception.

    Args:
        exc: The exception raised by a boto3/botocore call.
        action: A short verb phrase such as ``"create BREAKPOINT instrumentation"``.
        context: Optional ordered mapping of attempted parameters.

    Returns:
        A multi-line string starting with ``Failed to {action}`` and including
        an ``Error:`` line, an ``ATTEMPTED PARAMETERS:`` block when context
        is provided, and standard ``POSSIBLE CAUSES``/``TROUBLESHOOTING``
        sections tuned to the exception type.
    """
    attempted = _format_attempted_block(context)

    if isinstance(exc, ClientError):
        code, message = _client_error_body(exc)
        return (
            f"Failed to {action}\n\n"
            f"Error: {code} - {message}\n"
            f"{attempted}"
            "\nPOSSIBLE CAUSES:\n"
            "1. Invalid input parameters (validation error)\n"
            "2. Resource not found, already exists, or scoped to a different account\n"
            "3. Insufficient IAM permissions\n"
            "4. Service-side throttling or transient error\n"
            "\nTROUBLESHOOTING:\n"
            "1. Re-read the error message above for the specific failure cause\n"
            "2. Verify service, environment, and instrumentation_type identifiers\n"
            "3. Verify credentials map to an account/region with access\n"
        )

    if isinstance(exc, EndpointConnectionError):
        return (
            f"Failed to {action}\n\n"
            f"Error: EndpointConnectionError - {exc}\n"
            f"{attempted}"
            "\nTROUBLESHOOTING:\n"
            "1. Check network connectivity to the AWS endpoint\n"
            "2. Verify AWS region resolution (AWS_REGION env var or profile)\n"
        )

    if isinstance(exc, (ReadTimeoutError, ConnectTimeoutError)):
        return (
            f"Failed to {action}\n\n"
            f"Error: TimeoutError - {exc}\n"
            f"{attempted}"
            "\nTROUBLESHOOTING:\n"
            "1. Retry the request — the AWS endpoint did not respond within the socket timeout\n"
            "2. Check network connectivity\n"
        )

    if isinstance(exc, (NoCredentialsError, PartialCredentialsError)):
        return (
            f"Failed to {action}\n\n"
            f"Error: {type(exc).__name__} - {exc}\n"
            f"{attempted}"
            "\nTROUBLESHOOTING:\n"
            "1. Verify AWS credentials: aws configure list\n"
            "2. Set AWS_PROFILE or supply credentials via env vars\n"
        )

    return f"Failed to {action}\n\nUnexpected error: {exc}\n{attempted}"
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall