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_validation.py

View on GitHub
"""Validation and normalization helpers for instrumentation inputs."""

import re
from typing import List, Optional, Tuple

from di_constants import SNAPSHOT_SIGNAL_TYPE

_LOCATION_HASH_RE = re.compile(r"[0-9a-f]{16}")

_CANONICAL_LANGUAGES = {"python": "Python", "java": "Java", "javascript": "Javascript"}


def canonical_language(language: Optional[str]) -> Optional[str]:
    """Return the API's canonical ``ProgrammingLanguage`` casing, or None if unknown.

    The API's ``ProgrammingLanguage`` enum is case-sensitive (``Java``, ``Python``,
    ``Javascript``). Callers accept any casing (e.g. ``"javascript"``,
    ``"JavaScript"``) and map to the canonical form before sending to the API,
    so a validated language is not rejected by the backend on a casing mismatch.
    """
    return _CANONICAL_LANGUAGES.get((language or "").strip().lower())


def normalize_instrumentation_type(
    instrumentation_type: str,
) -> Tuple[str, Optional[str]]:
    """Normalize the type to upper-case; return ``(normalized, error)``.

    The normalized value is always a ``str`` (the upper-cased received value
    even on the error path) so callers get a non-optional type once they
    return early on ``error``. Callers must check ``error`` before using
    ``normalized``.
    """
    normalized = (instrumentation_type or "").strip().upper()
    allowed = {"BREAKPOINT", "PROBE"}
    if normalized not in allowed:
        return normalized, (
            "ERROR: instrumentation_type must be one of BREAKPOINT, PROBE "
            f"(received: {instrumentation_type})"
        )
    return normalized, None


def validate_capture_names(field_name: str, names: Optional[List[str]]) -> Optional[str]:
    """Validate a capture-name list (``capture_arguments`` / ``capture_locals``).

    Returns an error string if invalid, else ``None``. An omitted list
    (``None``) is valid and means "capture nothing for that field". A provided
    list must be non-empty and may not contain the ``*`` wildcard — both the
    empty list and ``*`` are rejected so the ambiguous "capture all" shapes
    never reach the API.
    """
    if names is None:
        return None
    if not names:
        return (
            f"ERROR: {field_name} must contain at least one name if provided. "
            "Omit it to capture none."
        )
    if "*" in names:
        return (
            f'ERROR: {field_name} does not support the wildcard "*". '
            "List explicit names, or omit it to capture none."
        )
    return None


def validate_probe_constraints(
    normalized_type: str,
    language: Optional[str],
    line_number: Optional[int],
) -> Optional[str]:
    """Validate PROBE-only constraints; return error text if invalid, else None.

    PROBE differs from BREAKPOINT in two ways the SDKs enforce:

    * PROBE is not supported for JavaScript.
    * PROBE is method/function-level only — the SDKs ignore line_number, so a
      PROBE with line_number set would silently not behave as written.
    """
    if normalized_type != "PROBE":
        return None
    lang = (language or "").strip().lower()
    if lang == "javascript":
        return (
            "ERROR: PROBE is not supported for JavaScript. "
            "Use instrumentation_type=BREAKPOINT for JavaScript targets."
        )
    if line_number is not None:
        return (
            "ERROR: PROBE does not support line_number (the SDKs ignore it). "
            "Omit line_number for PROBE — it is method/function-level only."
        )
    return None


def is_valid_location_hash(location_hash: Optional[str]) -> bool:
    """Return True for a 16-character lowercase hexadecimal location hash.

    Location hashes are 16 lowercase hex characters by API design. Validating
    against this shape (rather than only checking length) lets snapshot/status
    tools reject malformed input before it is interpolated into a CloudWatch
    Logs Insights query — hex can never contain the double-quote that would
    otherwise break out of a query string literal.
    """
    return bool(location_hash and _LOCATION_HASH_RE.fullmatch(location_hash))


def validate_snapshot_signal(signal_type: str) -> Optional[str]:
    """Return an error message unless ``signal_type`` is SNAPSHOT, else None."""
    normalized = (signal_type or "").strip().upper()
    if normalized != SNAPSHOT_SIGNAL_TYPE:
        return f"ERROR: signal_type must be SNAPSHOT for this API (received: {signal_type})"
    return None


def _format_code_location_troubleshooting(
    language: Optional[str],
    file_path: Optional[str],
    code_unit: Optional[str],
    class_name: Optional[str],
    method_name: Optional[str],
    line_number: Optional[int],
) -> str:
    """Build troubleshooting guidance for code-location create failures.

    ``language``/``file_path`` are ``Optional`` because callers pass raw,
    unvalidated inputs (which may be ``None``); the body renders them
    verbatim and guards with ``(language or '')`` where it matters.
    """
    lang = (language or "").strip().lower()

    lines = [
        "CODE LOCATION TROUBLESHOOTING:",
        "- file_path: source file path for the target code.",
        "- code_unit: Python runtime module path OR Java package name.",
        "- class_name: use for class methods (Java: simple class name only).",
        "- method_name: function/method name.",
        "- line_number: set only for line-level breakpoints (1-based).",
    ]

    if line_number is None:
        lines.append("- Breakpoint level: FUNCTION/METHOD-level (line_number omitted).")
    else:
        lines.append(f"- Breakpoint level: LINE-LEVEL (L{line_number}).")
        if lang in ("python", "java"):
            lines.append(
                "  * NOTE: target an executable statement. In Python/Java a non-executable "
                "line (blank, comment, decorator, signature) is ignored and the breakpoint "
                "never fires."
            )
        elif lang == "javascript":
            lines.append(
                "  * NOTE: in JavaScript a breakpoint on a non-executable line slides to the "
                "next parseable line and fires there — verify it lands where you intend."
            )

    if lang == "python":
        lines.extend(
            [
                "- Python rules:",
                "  * Set code_unit to the dotted runtime import path for the module that defines the target code.",
                "  * Example: services.billing, not billing.py or /app/services/billing.py.",
                '  * Use code_unit="__main__" only when the target file is executed',
                "    directly as the process entry script.",
                "  * If call site uses direct import aliasing, target importing module and alias name.",
                "  * If you cannot determine the runtime module path confidently, inspect first instead of guessing.",
            ]
        )
    elif lang == "java":
        lines.extend(
            [
                "- Java rules:",
                "  * Set code_unit to the Java package name (e.g., com.amazon.sampleapp).",
                "  * class_name must be simple name (e.g., OrderContext), not fully qualified.",
            ]
        )
    elif lang == "javascript":
        lines.extend(
            [
                "- JavaScript rules:",
                "  * JavaScript binds by file_path + line_number; line_number is required (>= 1).",
                "  * code_unit, class_name, and method_name are not used for JavaScript.",
                "  * Point line_number at the executable statement you want to observe.",
            ]
        )

    lines.extend(
        [
            "LOCATION INPUTS RECEIVED:",
            f"- language={language}",
            f"- file_path={file_path}",
            f"- code_unit={code_unit}",
            f"- class_name={class_name}",
            f"- method_name={method_name}",
            f"- line_number={line_number}",
        ]
    )

    return "\n".join(lines)


def _validate_location_inputs(
    language: str,
    file_path: str,
    code_unit: Optional[str],
    class_name: Optional[str],
    method_name: Optional[str],
    line_number: Optional[int],
) -> Optional[str]:
    """Validate location fields and return actionable error text if invalid.

    Enforces the per-language fields the SDK needs to bind the instrumentation;
    without them the SDK silently drops the configuration and nothing fires:

    * Java       — requires code_unit, class_name, and method_name.
    * Python     — requires code_unit and method_name (class_name optional).
    * JavaScript — requires line_number (>= 1); binds by file + line.
    """
    lang = (language or "").strip().lower()

    errors: List[str] = []
    suggestions: List[str] = []

    if not file_path or not str(file_path).strip():
        errors.append("file_path is required and must be non-empty.")

    if line_number is not None and line_number < 1:
        errors.append(f"line_number must be >= 1 (received: {line_number}).")

    if lang not in {"python", "java", "javascript"}:
        errors.append(f"language must be Python, Java, or JavaScript (received: {language}).")

    if lang == "java":
        if not code_unit:
            errors.append("Java requires code_unit (the package name, e.g. com.amazon.sampleapp).")
        if not class_name:
            errors.append("Java requires class_name (the simple class name, e.g. OrderContext).")
        if not method_name:
            errors.append("Java requires method_name.")
        if class_name and "." in class_name:
            errors.append(
                'For Java, class_name must be simple (e.g., "OrderContext"), '
                'not fully qualified (e.g., "com.example.OrderContext").'
            )
            if not code_unit:
                parts = class_name.split(".")
                if len(parts) > 1:
                    suggestions.append(
                        f'Use code_unit="{".".join(parts[:-1])}" and class_name="{parts[-1]}".'
                    )
        if code_unit and "/" in code_unit:
            suggestions.append(
                "Java code_unit should be a package name with dots, not a path with slashes."
            )

    elif lang == "python":
        if not code_unit:
            errors.append(
                "Python requires code_unit (the dotted runtime module path, e.g. services.billing)."
            )
        if not method_name:
            errors.append("Python requires method_name.")
        if code_unit and code_unit.endswith(".py"):
            suggestions.append(
                "Python code_unit should be a module path (e.g., services.billing), not a .py filename."
            )

    elif lang == "javascript":
        if line_number is None:
            errors.append("JavaScript requires line_number (>= 1); it binds by file and line.")

    if not errors:
        return None

    message = "Invalid breakpoint location inputs:\n"
    for idx, err in enumerate(errors, 1):
        message += f"{idx}. {err}\n"

    if suggestions:
        message += "\nSuggestions:\n"
        for idx, item in enumerate(suggestions, 1):
            message += f"{idx}. {item}\n"

    message += "\n" + _format_code_location_troubleshooting(
        language=language,
        file_path=file_path,
        code_unit=code_unit,
        class_name=class_name,
        method_name=method_name,
        line_number=line_number,
    )

    return message
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