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

View on GitHub
"""Snapshot payload parsing helpers for snapshot tools."""

import json
import re
from typing import Dict


def _preview_captured_value(captured_value: object) -> object:
    """Return a compact preview for one snapshot CapturedValue."""
    if not isinstance(captured_value, dict):
        return captured_value

    preview: Dict[str, object] = {}
    value_type = captured_value.get("type")
    if value_type not in (None, ""):
        preview["type"] = value_type

    if captured_value.get("is_null") is True:
        preview["is_null"] = True
        return preview

    if "not_captured_reason" in captured_value:
        preview["not_captured_reason"] = captured_value.get("not_captured_reason")
        return preview

    if "value" in captured_value:
        preview["value"] = captured_value.get("value")
        if captured_value.get("truncated") is True:
            preview["truncated"] = True
        if "size" in captured_value:
            preview["size"] = captured_value.get("size")
        return preview

    if isinstance(captured_value.get("fields"), dict):
        fields = captured_value["fields"]
        # Expand one level: show primitive field values directly,
        # collapse nested objects to just their type.
        fields_preview: Dict[str, object] = {}
        for fname, fval in fields.items():
            if not isinstance(fval, dict):
                fields_preview[fname] = fval
                continue
            if fval.get("is_null") is True:
                fields_preview[fname] = None
            elif "not_captured_reason" in fval:
                fields_preview[fname] = f'<{fval["not_captured_reason"]}>'
            elif "value" in fval:
                fields_preview[fname] = fval["value"]
            else:
                # Nested object/collection — show type only
                fields_preview[fname] = f'<{fval.get("type", "object")}>'
        preview["fields_preview"] = fields_preview
        if "size" in captured_value:
            preview["size"] = captured_value.get("size")
        return preview

    if isinstance(captured_value.get("elements"), list):
        preview["element_count"] = len(captured_value["elements"])
        if captured_value["elements"]:
            preview["first_element"] = _preview_captured_value(captured_value["elements"][0])
        return preview

    if isinstance(captured_value.get("entries"), list):
        preview["entry_count"] = len(captured_value["entries"])
        return preview

    return preview or captured_value


def _escape_logs_insights_regex(value: object) -> str:
    """Escape dynamic values for use inside a /.../ CloudWatch Logs Insights regex."""
    return re.escape(str(value)).replace("/", r"\/")


def _escape_logs_insights_string(value: object) -> str:
    """Escape a value for a double-quoted CloudWatch Logs Insights string literal.

    Logs Insights string literals are double-quoted with backslash escaping.
    Escape backslashes first (so the escapes added next are not themselves
    re-escaped), then double-quotes, so an embedded quote cannot terminate the
    literal and inject caller-controlled query syntax. This is distinct from
    ``_escape_logs_insights_regex``, which escapes for ``/.../`` regex context,
    not ``"..."`` literal context.
    """
    return str(value).replace("\\", "\\\\").replace('"', '\\"')


def _parse_snapshot_fields(result: dict) -> dict:
    """Extract key debugging fields from a raw CloudWatch Logs snapshot result.

    Handles the OTLP log record format where:
    - Metadata is in top-level `attributes` (aws.di.*)
    - Resource info is in `resource.attributes` (service.name, deployment.environment —
      the Java agent's autoconfig path may alternatively publish deployment.environment.name)
    - Captures and stack are nested under `body`
    - Trace/span IDs are at root level (`traceId`, `spanId`)
    - Stack frames use `file_path`/`line_number` (not `fileName`/`lineNumber`)
    - Return value key is `return_value` (not `returnValue`)
    """
    message = result.get("@message", "")
    try:
        snapshot_data = json.loads(message)
    except (json.JSONDecodeError, TypeError):
        snapshot_data = {}

    if not isinstance(snapshot_data, dict):
        snapshot_data = {}

    attributes = snapshot_data.get("attributes", {})
    if not isinstance(attributes, dict):
        attributes = {}

    resource = snapshot_data.get("resource", {})
    if not isinstance(resource, dict):
        resource = {}
    resource_attributes = resource.get("attributes", {})
    if not isinstance(resource_attributes, dict):
        resource_attributes = {}

    body = snapshot_data.get("body", {})
    if not isinstance(body, dict):
        body = {}

    location = {
        "class_name": attributes.get("aws.di.class_name"),
        "method_name": attributes.get("aws.di.method_name"),
        "file_path": attributes.get("aws.di.file_path"),
        "code_unit": attributes.get("aws.di.code_unit"),
        "instrumentation_level": attributes.get("aws.di.instrumentation_level"),
        "instrumentation_type": attributes.get("aws.di.instrumentation_type"),
    }

    trace = {
        "traceId": snapshot_data.get("traceId"),
        "spanId": snapshot_data.get("spanId"),
    }

    stack = body.get("stack", [])
    if not isinstance(stack, list):
        stack = []

    captures = body.get("captures", {})
    if not isinstance(captures, dict):
        captures = {}

    entry_capture = captures.get("entry", {})
    if not isinstance(entry_capture, dict):
        entry_capture = {}

    return_capture = captures.get("return", {})
    if not isinstance(return_capture, dict):
        return_capture = {}

    line_captures = captures.get("lines", {})
    if not isinstance(line_captures, dict):
        line_captures = {}

    entry_arguments = entry_capture.get("arguments", {})
    if not isinstance(entry_arguments, dict):
        entry_arguments = {}

    entry_locals = entry_capture.get("locals", {})
    if not isinstance(entry_locals, dict):
        entry_locals = {}

    return_arguments = return_capture.get("arguments", {})
    if not isinstance(return_arguments, dict):
        return_arguments = {}

    return_locals = return_capture.get("locals", {})
    if not isinstance(return_locals, dict):
        return_locals = {}

    return_value = return_capture.get("return_value")
    throwable = return_capture.get("throwable", {})
    if not isinstance(throwable, dict):
        throwable = {}

    line_locals: Dict[str, list[str]] = {}
    line_local_previews: Dict[str, Dict[str, object]] = {}
    line_arguments: Dict[str, list[str]] = {}
    line_argument_previews: Dict[str, Dict[str, object]] = {}
    line_return_values: Dict[str, object] = {}
    line_throwables: Dict[str, object] = {}
    for line_number, line_capture in line_captures.items():
        if not isinstance(line_capture, dict):
            continue
        ln = str(line_number)

        locals_map = line_capture.get("locals", {})
        if isinstance(locals_map, dict) and locals_map:
            line_locals[ln] = list(locals_map.keys())
            line_local_previews[ln] = {
                name: _preview_captured_value(value) for name, value in locals_map.items()
            }

        args_map = line_capture.get("arguments", {})
        if isinstance(args_map, dict) and args_map:
            line_arguments[ln] = list(args_map.keys())
            line_argument_previews[ln] = {
                name: _preview_captured_value(value) for name, value in args_map.items()
            }

        ret_val = line_capture.get("return_value")
        if ret_val is not None:
            line_return_values[ln] = _preview_captured_value(ret_val)

        throwable_val = line_capture.get("throwable")
        if isinstance(throwable_val, dict) and throwable_val:
            line_throwables[ln] = {
                "type": throwable_val.get("type"),
                "message": throwable_val.get("message"),
                "stacktrace_frame_count": (
                    len(throwable_val.get("stacktrace", []))
                    if isinstance(throwable_val.get("stacktrace"), list)
                    else 0
                ),
            }

    duration_ms = attributes.get("aws.di.duration_ms")

    stack_preview = []
    for frame in stack[:5]:
        if not isinstance(frame, dict):
            continue
        stack_preview.append(
            {
                "file_path": frame.get("file_path"),
                "function": frame.get("function"),
                "line_number": frame.get("line_number"),
            }
        )

    def _line_key(value):
        """Order numeric line keys first (by value), non-numeric keys last (lexically).

        Returns a ``(group, sort_value)`` tuple so the two kinds never compare
        across types. A bare ``int(v) if v.isdigit() else v`` key would mix
        ``int`` and ``str`` and raise ``TypeError`` the moment a non-digit key
        appears alongside numeric ones (e.g. a negative line ``'-1'``, since
        ``'-1'.isdigit()`` is ``False``), crashing snapshot parsing.
        """
        text = str(value)
        if text.isdigit():
            return (0, int(text), "")
        return (1, 0, text)

    all_line_numbers = sorted(
        set(line_locals.keys())
        | set(line_arguments.keys())
        | set(line_return_values.keys())
        | set(line_throwables.keys()),
        key=_line_key,
    )

    return {
        "@timestamp": result.get("@timestamp"),
        "snapshot_id": attributes.get("aws.di.snapshot_id"),
        "timeUnixNano": snapshot_data.get("timeUnixNano"),
        "duration_ms": duration_ms,
        "location_hash": attributes.get("aws.di.location_hash"),
        "location": location,
        "trace": trace,
        "stack_preview": stack_preview,
        "stack_frame_count": len(stack),
        "entry_argument_names": list(entry_arguments.keys()),
        "entry_arguments": {
            name: _preview_captured_value(value) for name, value in entry_arguments.items()
        },
        "entry_local_names": list(entry_locals.keys()),
        "entry_locals": {
            name: _preview_captured_value(value) for name, value in entry_locals.items()
        },
        "return_argument_names": list(return_arguments.keys()),
        "return_arguments": {
            name: _preview_captured_value(value) for name, value in return_arguments.items()
        },
        "return_local_names": list(return_locals.keys()),
        "return_locals": {
            name: _preview_captured_value(value) for name, value in return_locals.items()
        },
        "return_value": _preview_captured_value(return_value) if return_value is not None else None,
        "throwable": (
            {
                "type": throwable.get("type"),
                "message": throwable.get("message"),
                "stacktrace_frame_count": (
                    len(throwable.get("stacktrace", []))
                    if isinstance(throwable.get("stacktrace"), list)
                    else 0
                ),
            }
            if throwable
            else None
        ),
        "line_numbers": all_line_numbers,
        "line_locals": line_locals,
        "line_local_previews": line_local_previews,
        "line_arguments": line_arguments if line_arguments else None,
        "line_argument_previews": line_argument_previews if line_argument_previews else None,
        "line_return_values": line_return_values if line_return_values else None,
        "line_throwables": line_throwables if line_throwables else None,
        "raw_snapshot": snapshot_data,
    }
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