CloudWatchOmni / Client / get_context_graph

get_context_graph

CloudWatchOmni.Client.get_context_graph(**kwargs)

Queries the context graph with filtering, traversal, and pagination support.

Pagination note: nodes and edges are returned together as a coherent subgraph. Pagination cursors advance over nodes (the primary collection); each page includes all edges connecting nodes within that page. Callers should treat nodes as the paginated collection and edges as supplementary relationship data attached to those nodes.

See also: AWS API Documentation

Request Syntax

response = client.get_context_graph(
    nodeFilters={
        'nodeId': 'string',
        'nodeType': 'SERVICE'|'RESOURCE'|'REMOTE_SERVICE',
        'name': 'string',
        'tags': [
            {
                'key': 'string',
                'values': [
                    'string',
                ]
            },
        ],
        'telemetryAttributes': [
            {
                'key': 'string',
                'values': [
                    'string',
                ]
            },
        ],
        'region': [
            'string',
        ],
        'cloudProvider': [
            'string',
        ],
        'sourceAccountId': [
            'string',
        ],
        'namespace': [
            'string',
        ],
        'category': [
            'GEN_AI_AGENT'|'GEN_AI_MODEL'|'DATABASE'|'MESSAGING_QUEUE'|'COMPUTE'|'STORAGE'|'NETWORK',
        ],
        'stage': [
            'string',
        ],
        'sources': [
            'VPC_FLOW_LOG'|'CLOUDTRAIL'|'IAM_POLICY'|'CODE_SEMANTICS'|'TELEMETRY'|'AZURE_VNET_FLOW_LOG'|'ELB_ACCESS_LOG'|'CLOUDFRONT_ACCESS_LOG'|'S3_ACCESS_LOG'|'WAF_ACCESS_LOG'|'AWS_INTEGRATION'|'CONFIG',
        ]
    },
    edgeFilters={
        'edgeId': 'string',
        'from': 'string',
        'to': 'string',
        'edgeType': 'CALLS'|'ACCESSES'|'RUNS_ON',
        'operations': [
            'string',
        ],
        'telemetryAttributes': [
            {
                'key': 'string',
                'values': [
                    'string',
                ]
            },
        ],
        'sources': [
            'VPC_FLOW_LOG'|'CLOUDTRAIL'|'IAM_POLICY'|'CODE_SEMANTICS'|'TELEMETRY'|'AZURE_VNET_FLOW_LOG'|'ELB_ACCESS_LOG'|'CLOUDFRONT_ACCESS_LOG'|'S3_ACCESS_LOG'|'WAF_ACCESS_LOG'|'AWS_INTEGRATION'|'CONFIG',
        ]
    },
    startTime=datetime(2015, 1, 1),
    endTime=datetime(2015, 1, 1),
    depth=123,
    maxResults=123,
    maxEdgesPerNode=123,
    includeMetadata=True|False,
    nextToken='string'
)
Parameters:

  • nodeFilters (dict) –

    Criteria restricting which nodes are returned.

    • nodeId (string) –

      Match only the node with this identifier.

    • nodeType (string) –

      Match only nodes of this type.

    • name (string) –

      Match only nodes with this name.

    • tags (list) –

      Match nodes by the tags on the underlying resource.

      • (dict) –

        Key-value filter used for tags and attributes filtering. Multiple KeyFilters are AND’ed. Multiple values within a single KeyFilter are OR’ed. Values support pattern syntax: exact, negation (!value), wildcard (value, value*, *value).

        • key (string) – [REQUIRED]

          The tag or attribute key to filter on.

        • values (list) –

          The values to match for this key, OR’ed together. Each supports exact, negation (!value), and wildcard (value, value*, *value) syntax.

          • (string) –

            Key filter value string.

    • telemetryAttributes (list) –

      Match nodes by their OpenTelemetry (OTel) telemetry attributes.

      • (dict) –

        Key-value filter used for tags and attributes filtering. Multiple KeyFilters are AND’ed. Multiple values within a single KeyFilter are OR’ed. Values support pattern syntax: exact, negation (!value), wildcard (value, value*, *value).

        • key (string) – [REQUIRED]

          The tag or attribute key to filter on.

        • values (list) –

          The values to match for this key, OR’ed together. Each supports exact, negation (!value), and wildcard (value, value*, *value) syntax.

          • (string) –

            Key filter value string.

    • region (list) –

      Match nodes in any of these regions.

      • (string) –

    • cloudProvider (list) –

      Match nodes on any of these cloud providers.

      • (string) –

    • sourceAccountId (list) –

      Match nodes discovered from telemetry produced by any of these accounts.

      • (string) –

    • namespace (list) –

      Match nodes in any of these logical service groupings.

      • (string) –

    • category (list) –

      Match nodes of any of these categories.

      • (string) –

        Coarse classification of what a node is. Orthogonal to NodeType, which says whether the node is a service, a resource, or a remote service. Absent on most nodes today because few producers emit the source attribute.

    • stage (list) –

      Match nodes observed in any of these deployment environments.

      • (string) –

    • sources (list) –

      Match nodes contributed by any of these discovery sources.

      • (string) –

        Data source enum for context graph queries.

  • edgeFilters (dict) –

    Criteria restricting which edges are returned.

    • edgeId (string) –

      Match only the edge with this identifier.

    • from (string) –

      Match only edges originating from this node identifier.

    • to (string) –

      Match only edges pointing to this node identifier.

    • edgeType (string) –

      Match only edges of this relationship kind.

    • operations (list) –

      Match edges carrying any of these operations.

      • (string) –

    • telemetryAttributes (list) –

      Match edges by their OpenTelemetry (OTel) telemetry attributes. Not yet enforced: currently accepted but ignored (does not filter), matching nodeFilters.telemetryAttributes.

      • (dict) –

        Key-value filter used for tags and attributes filtering. Multiple KeyFilters are AND’ed. Multiple values within a single KeyFilter are OR’ed. Values support pattern syntax: exact, negation (!value), wildcard (value, value*, *value).

        • key (string) – [REQUIRED]

          The tag or attribute key to filter on.

        • values (list) –

          The values to match for this key, OR’ed together. Each supports exact, negation (!value), and wildcard (value, value*, *value) syntax.

          • (string) –

            Key filter value string.

    • sources (list) –

      Match edges contributed by any of these discovery sources.

      • (string) –

        Data source enum for context graph queries.

  • startTime (datetime) –

    [REQUIRED]

    Start of the time range (UTC), inclusive.

  • endTime (datetime) –

    [REQUIRED]

    End of the time range (UTC), inclusive.

  • depth (integer) – How many hops to traverse out from the nodes matched by nodeFilters. 0 returns only the matched nodes themselves.

  • maxResults (integer) – The maximum number of nodes to return in a single page.

  • maxEdgesPerNode (integer) – The maximum number of edges to return per node, bounding the fan-out of a densely connected node.

  • includeMetadata (boolean) – Whether to return the metadata block, semantics included, on each node and edge. Off by default because it costs an extra lookup per returned node.

  • nextToken (string) – Pagination token from a previous response, to retrieve the next page.

Return type:

dict

Returns:

Response Syntax

{
    'nodes': [
        {
            'nodeId': 'string',
            'nodeType': 'SERVICE'|'RESOURCE'|'REMOTE_SERVICE',
            'name': 'string',
            'alternateNames': [
                'string',
            ],
            'tags': {
                'string': 'string'
            },
            'nodeProperties': {
                'region': 'string',
                'cloudProvider': 'string',
                'sourceAccountId': 'string',
                'namespace': 'string',
                'category': 'GEN_AI_AGENT'|'GEN_AI_MODEL'|'DATABASE'|'MESSAGING_QUEUE'|'COMPUTE'|'STORAGE'|'NETWORK',
                'stage': 'string'
            },
            'telemetryAttributes': {
                'string': 'string'
            },
            'operationDetails': {
                'string': [
                    {
                        'string': 'string'
                    },
                ]
            },
            'signalTypes': [
                'LOGS'|'METRICS'|'TRACES'|'CONFIG'|'UNKNOWN',
            ],
            'sources': [
                'VPC_FLOW_LOG'|'CLOUDTRAIL'|'IAM_POLICY'|'CODE_SEMANTICS'|'TELEMETRY'|'AZURE_VNET_FLOW_LOG'|'ELB_ACCESS_LOG'|'CLOUDFRONT_ACCESS_LOG'|'S3_ACCESS_LOG'|'WAF_ACCESS_LOG'|'AWS_INTEGRATION'|'CONFIG',
            ],
            'metadata': {
                'metrics': [
                    {
                        'name': 'string',
                        'namespace': 'string',
                        'preferredStat': 'string',
                        'metricType': 'string',
                        'attributes': {
                            'string': 'string'
                        },
                        'semantics': {
                            'description': 'string',
                            'unit': 'string'
                        }
                    },
                ],
                'semantics': {
                    'purpose': 'string',
                    'language': 'string',
                    'framework': 'string',
                    'kind': 'string',
                    'repository': 'string'
                },
                'logs': [
                    {
                        'attributes': {
                            'string': 'string'
                        }
                    },
                ],
                'traces': [
                    {
                        'attributes': {
                            'string': 'string'
                        }
                    },
                ]
            },
            'firstObservedAt': datetime(2015, 1, 1),
            'lastObservedAt': datetime(2015, 1, 1),
            'edges': [
                {
                    'edgeId': 'string',
                    'from': 'string',
                    'to': 'string',
                    'edgeType': 'CALLS'|'ACCESSES'|'RUNS_ON',
                    'operations': [
                        'string',
                    ],
                    'edgeProperties': {
                        'protocol': 'string',
                        'sourcePort': 'string',
                        'destinationPort': 'string',
                        'blocked': True|False,
                        'errorCode': 'string',
                        'httpStatusCode': 'string',
                        'httpMethod': 'string',
                        'serviceInitiated': True|False,
                        'trafficStats': {
                            'bytes': 123,
                            'packets': 123,
                            'flows': 123,
                            'sentBytes': 123,
                            'receivedBytes': 123
                        }
                    },
                    'telemetryAttributes': {
                        'string': 'string'
                    },
                    'signalTypes': [
                        'LOGS'|'METRICS'|'TRACES'|'CONFIG'|'UNKNOWN',
                    ],
                    'sources': [
                        'VPC_FLOW_LOG'|'CLOUDTRAIL'|'IAM_POLICY'|'CODE_SEMANTICS'|'TELEMETRY'|'AZURE_VNET_FLOW_LOG'|'ELB_ACCESS_LOG'|'CLOUDFRONT_ACCESS_LOG'|'S3_ACCESS_LOG'|'WAF_ACCESS_LOG'|'AWS_INTEGRATION'|'CONFIG',
                    ],
                    'metadata': {
                        'metrics': [
                            {
                                'name': 'string',
                                'namespace': 'string',
                                'preferredStat': 'string',
                                'metricType': 'string',
                                'attributes': {
                                    'string': 'string'
                                },
                                'semantics': {
                                    'description': 'string',
                                    'unit': 'string'
                                }
                            },
                        ],
                        'semantics': {
                            'purpose': 'string',
                            'language': 'string',
                            'framework': 'string',
                            'kind': 'string',
                            'repository': 'string'
                        },
                        'logs': [
                            {
                                'attributes': {
                                    'string': 'string'
                                }
                            },
                        ],
                        'traces': [
                            {
                                'attributes': {
                                    'string': 'string'
                                }
                            },
                        ]
                    },
                    'firstObservedAt': datetime(2015, 1, 1),
                    'lastObservedAt': datetime(2015, 1, 1)
                },
            ]
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) –

    The response containing the requested slice of the context graph.

    • nodes (list) –

      The page of nodes matching the request. This is the paginated collection.

      • (dict) –

        A node in the context graph representing a service, resource, or remote service.

        • nodeId (string) –

          The unique identifier of the node within the context graph.

        • nodeType (string) –

          Whether the node is a service, a resource, or a remote service.

        • name (string) –

          The primary display name of the node.

        • alternateNames (list) –

          Other names this node was observed under. A node that merged across sources reports one resolved name, and the names it was merged away from appear here.

          • (string) –

        • tags (dict) –

          The tags observed on the underlying resource.

          • (string) –

            • (string) –

        • nodeProperties (dict) –

          Identity attributes promoted out of the flat attribute map onto typed members.

          • region (string) –

            The region the node runs in. Falls back to the region the telemetry was ingested from when the node does not report one.

          • cloudProvider (string) –

            The cloud provider hosting the node, resolved from the reported provider, platform, or vendor namespace, and defaulting to “aws”.

          • sourceAccountId (string) –

            The account that produced the telemetry this node was discovered from.

          • namespace (string) –

            The logical service grouping the node belongs to. This is not a metric namespace.

          • category (string) –

            What kind of thing the node is, coarser than nodeType.

          • stage (string) –

            The node’s deployment environment. A node may be observed in several; this is the highest-precedence one. Match any of them with NodeFilters.stage.

        • telemetryAttributes (dict) –

          The node’s OpenTelemetry (OTel) attributes, as emitted by telemetry — the raw values, as opposed to the normalized nodeProperties. A key promoted onto a nodeProperties member is removed here, so no value appears twice.

          • (string) –

            • (string) –

        • operationDetails (dict) –

          The operations observed on this node, keyed by operation name. Each value lists the dimension sets that identify the metric series for that operation.

          • (string) –

            Operation name on a context graph node (typically OTel span.name).

            • (list) –

              • (dict) –

                One OTel dimension set identifying a metric series for an operation.

                • (string) –

                  OTel dimension key on an operation identifier set (e.g. “http.request.method”).

                  • (string) –

                    OTel dimension value on an operation identifier set.

        • signalTypes (list) –

          The kinds of telemetry signal observed on this node.

          • (string) –

            Signal enum for context graph queries.

        • sources (list) –

          The discovery sources that contributed this node.

          • (string) –

            Data source enum for context graph queries.

        • metadata (dict) –

          Descriptive metadata about the node. Present only when the request sets includeMetadata.

          • metrics (list) –

            The metrics observed on the element.

            • (dict) –

              A single metric observed on a context graph node.

              • name (string) –

                The metric name as emitted, such as “Duration”.

              • namespace (string) –

                DEPRECATED: read attributes[“service.namespace”] instead. Retained (deprecated) for backward compatibility with existing consumers; will be removed once they migrate. The logical service grouping the metric belongs to.

              • preferredStat (string) –

                The statistic to chart or alarm on, such as “p99” or “Sum”. Free-form and frequently absent.

              • metricType (string) –

                OTel metric kind: “gauge”, “sum”, “histogram”, “exponential_histogram”, or “summary” (CloudWatch-vended metrics carry the same kinds). Absent when the producer did not report one.

              • attributes (dict) –

                Per-metric qualifying attributes the console uses to query this metric’s telemetry. These are the RAW, store-matching values keyed by their OTel names (“service.name”, “service.namespace”, “cloud.provider”, “cloud.account.id”, “cloud.region”, “instrumentation_scope”) — deliberately NOT the node’s normalized/merged identity, so the query selectors match the emitted series. A merged node can carry different values per metric, which is why they live here rather than on the node.

                • (string) –

                  • (string) –

              • semantics (dict) –

                What the metric means and the unit it is reported in.

                • description (string) –

                  Human-readable description of what the metric measures.

                • unit (string) –

                  The unit the metric is reported in.

          • semantics (dict) –

            Semantic description of the node. Absent on an edge, because semantics describe a service rather than a relationship.

            • purpose (string) –

              What the service does.

            • language (string) –

              The primary programming language the service is written in.

            • framework (string) –

              The application framework the service is built on.

            • kind (string) –

              The kind of workload the service is.

            • repository (string) –

              The source repository the service is built from.

          • logs (list) –

            Per-signal LOGS query selectors: a LIST of blocks the console ORs, each an AND of exact store column -> raw values. Node-level (edges carry only traces). Populated when the request sets includeMetadata; derived labels (logSourceType) are added by the service projection, not stored here.

            • (dict) –

              One LOGS query selector block on a node. The attributes map’s keys are AND’d; each selects with col = value. Deliberately RAW/un-normalized so the selector matches the store, not the node’s merged identity.

              • attributes (dict) –

                One LOGS query-selector block: EXACT store column -> raw SCALAR value (mirroring the scalar MetadataAttributeMap). Keyed by the store column that carries the value (e.g. resource.attributes['service.name'], attributes['aws.local.service'], @logGroupName) so the selector matches the emitted signal. A dimension seen under several values (a service under two namespaces, several log groups) becomes several blocks with the same columns and different values, which the console ORs. Dedicated to the LOGS selector so its cap evolves independently of the metric attribute map and the TRACES map. Selector caps are deliberately DISTINCT from the metric caps.

                • (string) –

                  • (string) –

          • traces (list) –

            Per-signal TRACES query selectors (same block shape as logs). Present on both node and edge metadata. serviceName is derived at the service projection, not stored here.

            • (dict) –

              One TRACES query selector block on a node/edge (see LogMetadata).

              • attributes (dict) –

                TRACES counterpart of LogMetadataAttributeMap — a dedicated per-signal map so the two evolve independently (same scalar shape and cap today).

                • (string) –

                  • (string) –

        • firstObservedAt (datetime) –

          When this node was first observed (UTC), at minute granularity. For a node that merged across sources, this is the earliest value any source reported.

        • lastObservedAt (datetime) –

          When this node was most recently observed (UTC), at minute granularity. For a node that merged across sources, this is the latest value any source reported.

        • edges (list) –

          Outbound edges originating from this node. Each edge carries its from.

          • (dict) –

            A directed edge in the context graph connecting two nodes.

            • edgeId (string) –

              The unique identifier of the edge within the context graph.

            • from (string) –

              The node identifier the edge originates from.

            • to (string) –

              The node identifier the edge points to.

            • edgeType (string) –

              The kind of relationship the edge represents.

            • operations (list) –

              The operations observed on this edge.

              • (string) –

            • edgeProperties (dict) –

              Attributes promoted out of the flat attribute map onto typed members. Which members are present depends on what produced the edge.

              • protocol (string) –

                The IANA protocol name for the observed network traffic, such as “tcp”.

              • sourcePort (string) –

                The source port of the observed traffic. May be a placeholder when the port is unknown.

              • destinationPort (string) –

                The destination port of the observed traffic. May be a placeholder when the port is unknown.

              • blocked (boolean) –

                Whether the observed network flow was denied. Absent means the edge was not derived from network flow data, which is not the same as allowed.

              • errorCode (string) –

                The error code returned when the call was attempted and refused. Its presence means the edge exists but the dependency is failing.

              • httpStatusCode (string) –

                The HTTP status code observed on the request. Distinct from errorCode.

              • httpMethod (string) –

                The HTTP method observed on the request.

              • serviceInitiated (boolean) –

                Whether the caller was an AWS service principal rather than a user or role. Absent means the edge was not derived from a source that reports it.

              • trafficStats (dict) –

                Traffic counters accumulated over the edge’s observation window.

                • bytes (integer) –

                  Total bytes observed across the edge.

                • packets (integer) –

                  Total packets observed across the edge.

                • flows (integer) –

                  Total network flows observed across the edge.

                • sentBytes (integer) –

                  Total bytes sent to the destination.

                • receivedBytes (integer) –

                  Total bytes received from the destination.

            • telemetryAttributes (dict) –

              The edge’s OpenTelemetry (OTel) attributes, as emitted by telemetry. A key promoted onto an edgeProperties member is removed here, so no value appears twice.

              • (string) –

                • (string) –

            • signalTypes (list) –

              The kinds of telemetry signal observed on this edge.

              • (string) –

                Signal enum for context graph queries.

            • sources (list) –

              The discovery sources that contributed this edge.

              • (string) –

                Data source enum for context graph queries.

            • metadata (dict) –

              Descriptive metadata about the edge. Present only when the request sets includeMetadata.

              • metrics (list) –

                The metrics observed on the element.

                • (dict) –

                  A single metric observed on a context graph node.

                  • name (string) –

                    The metric name as emitted, such as “Duration”.

                  • namespace (string) –

                    DEPRECATED: read attributes[“service.namespace”] instead. Retained (deprecated) for backward compatibility with existing consumers; will be removed once they migrate. The logical service grouping the metric belongs to.

                  • preferredStat (string) –

                    The statistic to chart or alarm on, such as “p99” or “Sum”. Free-form and frequently absent.

                  • metricType (string) –

                    OTel metric kind: “gauge”, “sum”, “histogram”, “exponential_histogram”, or “summary” (CloudWatch-vended metrics carry the same kinds). Absent when the producer did not report one.

                  • attributes (dict) –

                    Per-metric qualifying attributes the console uses to query this metric’s telemetry. These are the RAW, store-matching values keyed by their OTel names (“service.name”, “service.namespace”, “cloud.provider”, “cloud.account.id”, “cloud.region”, “instrumentation_scope”) — deliberately NOT the node’s normalized/merged identity, so the query selectors match the emitted series. A merged node can carry different values per metric, which is why they live here rather than on the node.

                    • (string) –

                      • (string) –

                  • semantics (dict) –

                    What the metric means and the unit it is reported in.

                    • description (string) –

                      Human-readable description of what the metric measures.

                    • unit (string) –

                      The unit the metric is reported in.

              • semantics (dict) –

                Semantic description of the node. Absent on an edge, because semantics describe a service rather than a relationship.

                • purpose (string) –

                  What the service does.

                • language (string) –

                  The primary programming language the service is written in.

                • framework (string) –

                  The application framework the service is built on.

                • kind (string) –

                  The kind of workload the service is.

                • repository (string) –

                  The source repository the service is built from.

              • logs (list) –

                Per-signal LOGS query selectors: a LIST of blocks the console ORs, each an AND of exact store column -> raw values. Node-level (edges carry only traces). Populated when the request sets includeMetadata; derived labels (logSourceType) are added by the service projection, not stored here.

                • (dict) –

                  One LOGS query selector block on a node. The attributes map’s keys are AND’d; each selects with col = value. Deliberately RAW/un-normalized so the selector matches the store, not the node’s merged identity.

                  • attributes (dict) –

                    One LOGS query-selector block: EXACT store column -> raw SCALAR value (mirroring the scalar MetadataAttributeMap). Keyed by the store column that carries the value (e.g. resource.attributes['service.name'], attributes['aws.local.service'], @logGroupName) so the selector matches the emitted signal. A dimension seen under several values (a service under two namespaces, several log groups) becomes several blocks with the same columns and different values, which the console ORs. Dedicated to the LOGS selector so its cap evolves independently of the metric attribute map and the TRACES map. Selector caps are deliberately DISTINCT from the metric caps.

                    • (string) –

                      • (string) –

              • traces (list) –

                Per-signal TRACES query selectors (same block shape as logs). Present on both node and edge metadata. serviceName is derived at the service projection, not stored here.

                • (dict) –

                  One TRACES query selector block on a node/edge (see LogMetadata).

                  • attributes (dict) –

                    TRACES counterpart of LogMetadataAttributeMap — a dedicated per-signal map so the two evolve independently (same scalar shape and cap today).

                    • (string) –

                      • (string) –

            • firstObservedAt (datetime) –

              When this edge was first observed (UTC), at minute granularity. For an edge that merged across sources, this is the earliest value any source reported.

            • lastObservedAt (datetime) –

              When this edge was most recently observed (UTC), at minute granularity. For an edge that merged across sources, this is the latest value any source reported.

    • nextToken (string) –

      Pagination token for the next page; absent when there are no more results.

Exceptions