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',
                        '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',
                                '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”.

            • 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 used to query this metric’s telemetry. Keys are the metric store’s own label names, not bare OTel attribute names: service identity arrives as “@resource.service.name” and “@resource.service.namespace”, and the instrumentation scope as “@instrumentation.@name”, while span-derived metrics label the service as a bare “service.name”. Cloud provider, account and region are not repeated per metric — read those from the node. Values are RAW, deliberately NOT the node’s normalized or merged identity, so a selector built from them matches the emitted series. A merged node can carry different values per metric, which is why these 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) –

          LOGS query selectors: a list of blocks to OR together, each block an AND of exact store column to raw value. Present on node metadata only — edges carry trace selectors. Returned when the request sets includeMetadata.

          • (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: an exact log-store column mapped to the raw value it carries, so the selector matches the emitted signal. Keys are store column names, not bare attribute names. Every block carries “@logGroupName”; alongside it a block carries either the entity columns (” @entities.KeyAttributes.Name”, “.Type”, “.Environment”, “ @entities.Attributes.PlatformType”) or OTel columns (“resource.attributes[‘service.name’]”, “resource.attributes[‘service.namespace’]”, “resource.attributes[‘cloud.provider’|’cloud.account.id’|’cloud.region’]”). A dimension seen under several values — several log groups, or a service under two namespaces — becomes several blocks with the same columns and different values, to be OR’d together.

              • (string) –

                • (string) –

        • traces (list) –

          TRACES query selectors, same block shape as the logs selectors. Present on both node and edge metadata. Returned when the request sets includeMetadata.

          • (dict) –

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

            • attributes (dict) –

              One TRACES query-selector block: an exact span-store column mapped to the raw value it carries. Keys are store column names, not bare attribute names — the service identity and cloud dimensions arrive as “resource.attributes[‘service.name’]”, “resource.attributes[‘service.namespace’]”, “resource.attributes[‘cloud.provider’]”, “resource.attributes[‘cloud.account.id’]”, “resource.attributes[‘cloud.region’]” and “resource.attributes[‘deployment.environment’]”, and span-level identity as “attributes[‘aws.local.service’]” and “attributes[‘aws.local.environment’]”. Not every column is present on every block; which ones appear depends on what the span carried.

              • (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”.

                • 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 used to query this metric’s telemetry. Keys are the metric store’s own label names, not bare OTel attribute names: service identity arrives as “@resource.service.name” and “@resource.service.namespace”, and the instrumentation scope as “@instrumentation.@name”, while span-derived metrics label the service as a bare “service.name”. Cloud provider, account and region are not repeated per metric — read those from the node. Values are RAW, deliberately NOT the node’s normalized or merged identity, so a selector built from them matches the emitted series. A merged node can carry different values per metric, which is why these 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) –

              LOGS query selectors: a list of blocks to OR together, each block an AND of exact store column to raw value. Present on node metadata only — edges carry trace selectors. Returned when the request sets includeMetadata.

              • (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: an exact log-store column mapped to the raw value it carries, so the selector matches the emitted signal. Keys are store column names, not bare attribute names. Every block carries “@logGroupName”; alongside it a block carries either the entity columns (” @entities.KeyAttributes.Name”, “.Type”, “.Environment”, “ @entities.Attributes.PlatformType”) or OTel columns (“resource.attributes[‘service.name’]”, “resource.attributes[‘service.namespace’]”, “resource.attributes[‘cloud.provider’|’cloud.account.id’|’cloud.region’]”). A dimension seen under several values — several log groups, or a service under two namespaces — becomes several blocks with the same columns and different values, to be OR’d together.

                  • (string) –

                    • (string) –

            • traces (list) –

              TRACES query selectors, same block shape as the logs selectors. Present on both node and edge metadata. Returned when the request sets includeMetadata.

              • (dict) –

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

                • attributes (dict) –

                  One TRACES query-selector block: an exact span-store column mapped to the raw value it carries. Keys are store column names, not bare attribute names — the service identity and cloud dimensions arrive as “resource.attributes[‘service.name’]”, “resource.attributes[‘service.namespace’]”, “resource.attributes[‘cloud.provider’]”, “resource.attributes[‘cloud.account.id’]”, “resource.attributes[‘cloud.region’]” and “resource.attributes[‘deployment.environment’]”, and span-level identity as “attributes[‘aws.local.service’]” and “attributes[‘aws.local.environment’]”. Not every column is present on every block; which ones appear depends on what the span carried.

                  • (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

• CloudWatchOmni.Client.exceptions.ThrottlingException

• CloudWatchOmni.Client.exceptions.ValidationException

• CloudWatchOmni.Client.exceptions.AccessDeniedException

• CloudWatchOmni.Client.exceptions.InternalServerException