Intelligence

Scope and neighbours

This reference composes the metric, service-health, context-graph, and SQL references rather than replacing them. Hand the ask back when it is not a cause question: a bare single-signal metric symptom belongs to query/promql-metrics.md; a bare “is <service> healthy” verdict or a role-labelled dependency map belongs to service-health.md; a pure traversal-direction or edge-semantics question belongs to context-graph.md. Use this file when the question is what is wrong and why — status, triage, root cause, or a past incident.

Contents

• Scope and neighbours
• Operations
• When to use
• Using Omni Intelligence in an investigation
• Data model
• ListInsights
• ListObservations
• GetContextGraph
• Cost and performance guardrails
• Gotchas

Operations

Three operations answer the questions in this reference, all on the public CloudWatch Omni SigV4 API (service cloudwatch-omni, signing name cloudwatch) — reachable from the AWS CLI (aws cloudwatchomni …), boto3, or any SigV4 caller:

Observations and insights say what moved; the context graph says how the moving parts are connected. Used together they answer most status and root-cause questions faster than scanning raw telemetry. The CloudWatch Omni Intelligence console view presents the same insights and observations for a human to read; use it as a cross-check, not as a replacement for the API in an automated investigation.

When a call fails

The 403 / 404 / local-client-error model is the same for all three operations and is stated once, in context-graph.md’s Check permissions to access the Context Graph. In short: a 403 AccessDeniedException is an authorization result (a missing access grant or IAM action, or — when the Space has a customer-managed KMS key — a denied kms:Decrypt / kms:GenerateDataKey or an encryption context the key policy does not allow; a merely disabled key is not this cause); a 404 UnknownOperationException means the operation is not available to the account, so the server rejects it as if it did not exist (do not retry or reshape the request); and a local “unknown service” / invalid-choice error is a too-old AWS CLI or boto3/botocore that fails locally, before any request is sent (upgrade the client). Read the error, not the symptom, and never substitute X-Ray GetServiceGraph.

When to use

Use when the user asks to:

• Check status: “Is anything wrong right now?” / “How is <service> doing?” / “Any open issues in my system?”
• Troubleshoot a symptom: “Why is <service> slow / erroring?” / “What changed on <service> this morning?”
• Find a root cause: “Users saw errors between X and Y — what caused it?” / “Explain this insight”
• Look back: “What happened during last night’s incident?” (its insights may be INACTIVE now)
• Trace dependencies and impact: “What does <service> depend on, and which of those is broken?” / “Who is affected if <service> fails?”
• Read Omni’s findings directly: insights, observations, anomalies, the context graph, ListInsights, ListObservations, GetContextGraph

Using Omni Intelligence in an investigation

One way to use the three operations together; adapt it to the question.

1. Insights: what’s going on. List insights for the window the question needs. ACTIVE insights cover “now”, which is also the place to start when no time is given. For a past incident the insight it raised may since have gone INACTIVE — the two statuses are reversible — so an insight you expect may not be ACTIVE in the window; say that you are looking at a past incident.
2. Rank them by relevance to the problem under investigation, and keep the ones that match.
3. Dive into their observations. Resolve a kept insight’s observations[] with one ListObservations call using anomalyIds — the batch-get, up to 100 ids, mutually exclusive with the other filters (see ListObservations). Each observation names a service, a signal, how it changed, and when; these are the evidence for the answer.
4. Context graph: blast radius and causal chain. Start from the affected services and resources and follow their dependencies, to see which one the others depend on and who is impacted.
5. Answer with the evidence. Name the root cause and each impacted service, and for each one cite the observations behind it: service, signal (metric, log pattern, or operation), how it changed, and when.

An insight is a hypothesis to confirm, never the final answer on its own: check that its window actually overlaps the incident, then confirm the candidate on the graph and in telemetry.

Data model

Observation: one anomaly episode detected in a service’s telemetry (logs, metrics, or traces).

Insight: Omni’s correlation of related observations into one explained finding.

ListInsights

Lists insights, most recently updated first. Call it as aws cloudwatchomni list-insights, boto3, or any SigV4 client.

The response returns the insights in items, plus nextToken and (only when insightIds was set) unprocessedIds.

An insight must match every filter you set; within one filter, any listed value matches. For example, filters.status: [ACTIVE] with filters.severity: [HIGH, CRITICAL] returns active insights that are high or critical. The status, severity, services, and timeRange members live under the filters envelope, not at the top level — only query, insightIds, maxResults, and nextToken are top-level.

A window ranked by severity, as a real request:

Keep the response small by reading only the fields you need to rank and continue (title, severity, status, times, affectedNodes[].name, summary, observations), and read reasoning only for the one insight you examine.

ListObservations

Lists observations (anomaly episodes). Call it as aws cloudwatchomni list-observations, boto3, or any SigV4 client.

The response returns the observations in items, plus nextToken and (only when anomalyIds was set) unprocessedIds.

Getting one insight’s observations. Use the anomalyIds batch-get: one call, passing that insight’s observations[] (up to 100 ids), returns exactly those observations. anomalyIds is mutually exclusive with the other filters, so send it alone. This is the primary, cheapest path — one scoped call rather than listing a window and filtering client-side.

Anomalies on given services and signals in a window — a filtered query, with no anomalyIds:

A filtered query answers specific questions: “what else moved on the services in this path?”, “did traces change before the logs started erroring?”, “is there anything high severity that no insight covers?”.

GetContextGraph

GetContextGraph reads the context graph — which services and resources depend on which — so you can tell the root cause apart from the services it impacts and see the blast radius. It holds services (SERVICE), resources (RESOURCE: a database, queue, cache, host), and remote services (REMOTE_SERVICE: an AWS API or other dependency seen only from the caller), linked by CALLS, ACCESSES (reads or writes a datastore), or RUNS_ON (hosted on compute) edges. Full API and traversal rules are in context-graph.md; the parts used most with insights:

• An insight’s affectedNodes[].nodeId (as nodeFilters.nodeId), or a service or resource name (as nodeFilters.name), is the starting point, with depth 1 and a window around the problem. startTime and endTime are required.
• Edges point from caller to dependency, and each service or resource carries only its outbound edges[]; callers are found with edgeFilters.to. An edge’s to is a nodeId, mapped to a name from the same response.
• An errorCode or non-2xx httpStatusCode on an edge is an observed failure of that dependency; a missing one is unreported, not healthy.
• includeMetadata returns the exact metric names and log/trace selectors behind a service or resource, for follow-up queries.

AWS CLI example:

For the error semantics — in particular that an AccessDeniedException here is an access grant / IAM or customer-KMS cause and never an “intelligence not enabled” signal — see context-graph.md and When a call fails above.

Cost and performance guardrails

Every tool result is re-read on every later turn, so output size and call count drive the cost and latency of an investigation. All three operations have a CLI, so the same projections apply to each.

• Bound calls in time. Use the window the question needs plus modest slack; widen in steps only when a narrow window is empty. Avoid multi-day sweeps.
• Project and cap output. The AWS CLI fetches all pages of a paginated call by default, so use --max-items or --no-paginate, and a JMESPath --query that keeps only the fields you need. Read only what you need to rank and continue (title, severity, status, times, affected service and resource names, summary, observation ids); read reasoning only for the insight you examine. Observation evidenceSamples arrays are large; ignore them unless you need per-sample values.
• Batch, don’t loop. One call scoped to many things beats one call per thing: a single services list rather than a loop, and one anomalyIds call to fetch an insight’s whole observations[] rather than one call per observation.
• Context graph: depth 1 first; maxEdgesPerNode (1–50) to bound a densely connected service or resource; includeMetadata only on a small neighborhood.
• Stop when the evidence agrees. Once the insight’s reasoning, its observations, and the context graph (if you checked it) point to the same root cause, answer. Each extra confirming call adds a turn and rarely changes the result.

Gotchas

• Empty results are usually scope: the wrong Region (the Region of the call selects which CloudWatch dataset is read), a window that misses the problem, a service name that differs from the stored one (compare affectedNodes[].name or the graph’s alternateNames), or retention: older insights and observations may no longer be listed. An empty result is a scoping signal, never a “healthy” verdict.
• Account and Region come from the data. The CloudWatch dataset can hold telemetry from several accounts. Use affectedNodes[].accountId / region and an observation’s sourceAccountId / sourceRegion for follow-up calls.
• A pre-existing insight is not a fresh incident’s cause. Check that an insight’s window overlaps the incident before citing it; a chronic background insight that started hours earlier is not the root cause of something that began at the incident time.