diff --git a/doc-server/docs/features/ai/index.md b/doc-server/docs/features/ai/index.md index 5e4add13..b734145a 100644 --- a/doc-server/docs/features/ai/index.md +++ b/doc-server/docs/features/ai/index.md @@ -4,7 +4,7 @@ sidebar_position: 1 # AI & Pre-built Agents -NudgeBee delivers **Cloud-Ops Intelligence** through **NuBi**, the SRE AI Agent, and a library of 30+ pre-built Cloud-Ops agents. These agents analyze incidents across logs, metrics, traces, and alerts — powered by the [Semantic Knowledge Graph](../knowledge-graph.md) — to identify root causes and recommend actions. The result: MTTR reduced from hours to minutes. +NudgeBee delivers **Cloud-Ops Intelligence** through **NuBi**, the SRE AI Agent, and a library of 30+ pre-built Cloud-Ops agents. These agents analyze incidents across logs, metrics, traces, and alerts — powered by the [Semantic Knowledge Graph](../knowledge-graph/index.md) — to identify root causes and recommend actions. The result: MTTR reduced from hours to minutes. NudgeBee's AI capabilities are **pre-packaged but not a black box** — every agent is fully extensible, modular, and controllable, with enterprise guardrails like RBAC, approval workflows, and audit trails. diff --git a/doc-server/docs/features/ai/use-cases/incident-rca.md b/doc-server/docs/features/ai/use-cases/incident-rca.md index 1faa3812..60829107 100644 --- a/doc-server/docs/features/ai/use-cases/incident-rca.md +++ b/doc-server/docs/features/ai/use-cases/incident-rca.md @@ -18,7 +18,7 @@ Ask the question you'd ask a senior engineer. > > Checkout is throwing errors in the demo namespace. What's the root cause? -NuBi checks checkout, then walks the [Knowledge Graph](../../knowledge-graph.md) downstream to follow the failure to its source. It answers with a 5-Whys chain: +NuBi checks checkout, then walks the [Knowledge Graph](../../knowledge-graph/index.md) downstream to follow the failure to its source. It answers with a 5-Whys chain: ![NuBi's root cause analysis for the checkout failure: a 5-Whys causality chain ending at the enabled "Product Catalog Fail" feature flag, with supporting evidence and recommended next steps](./img/uc-checkout-rca.png) diff --git a/doc-server/docs/features/dashboards.md b/doc-server/docs/features/dashboards.md index cbae3e74..5676489f 100644 --- a/doc-server/docs/features/dashboards.md +++ b/doc-server/docs/features/dashboards.md @@ -241,4 +241,4 @@ Dashboards warn before you navigate away with unsaved changes. A brand-new dashb ## Related - [Application Grouping](./application-grouping.md) — group workloads so a dashboard can chart them as one application -- [Semantic Knowledge Graph](./knowledge-graph.md) +- [Semantic Knowledge Graph](./knowledge-graph/index.md) diff --git a/doc-server/docs/features/index.md b/doc-server/docs/features/index.md index d15d7b4e..b970844c 100755 --- a/doc-server/docs/features/index.md +++ b/doc-server/docs/features/index.md @@ -30,7 +30,7 @@ Explore everything NudgeBee offers for Cloud-Ops Intelligence, troubleshooting, - **[Service Criticality](./service-criticality.md)** — Tier your workloads so triage surfaces failures on what matters and downranks noise from demo and test. -- **[Semantic Knowledge Graph](./knowledge-graph.md)** — See how everything connects across your entire infrastructure. The Semantic Knowledge Graph correlates logs, metrics, traces, and code into a single visual map of services, workloads, and dependencies — powering NudgeBee's AI analysis. +- **[Semantic Knowledge Graph](./knowledge-graph/index.md)** — See how everything connects across your entire infrastructure. The Semantic Knowledge Graph correlates logs, metrics, traces, and code into a single visual map of services, workloads, and dependencies — powering NudgeBee's AI analysis. - **[Kubernetes](./Kubernetes/index.md)** — Monitor all your connected Kubernetes clusters, workloads, pods, and nodes from a single dashboard. Track cluster health, resource utilization, and workload status in real time. diff --git a/doc-server/docs/features/knowledge-graph.md b/doc-server/docs/features/knowledge-graph.md deleted file mode 100644 index 73479bfd..00000000 --- a/doc-server/docs/features/knowledge-graph.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -sidebar_position: 8 ---- - -# Semantic Knowledge Graph - -## Overview - -The Semantic Knowledge Graph is NudgeBee's intelligence layer — it goes beyond simple infrastructure topology by correlating logs, metrics, traces, and code to build a rich, contextual map of your entire environment. It provides a visual representation of your infrastructure, showing resources and their relationships across cloud providers, Kubernetes clusters, and observability platforms, while enabling NudgeBee's AI agents to reason about your infrastructure with full context. - -## Why Use the Semantic Knowledge Graph - -- **Correlate signals** - Automatically links logs, metrics, traces, and code changes to build a unified context for every resource -- **Visualize dependencies** - See service-to-service communication and infrastructure topology at a glance -- **Understand connections** - Trace how resources connect across different cloud accounts -- **Impact analysis** - Identify what depends on a resource before making changes -- **Power AI troubleshooting** - The Semantic Knowledge Graph feeds context to [NuBi and the pre-built AI agents](../ai/), enabling faster and more accurate root cause analysis - -## Getting Started - -To access the Knowledge Graph: - -1. Click **Troubleshoot** in the left navigation sidebar -2. Select the **Knowledge Graph** tab at the top of the page (next to "All Events") - -The graph will load with your infrastructure resources and their relationships. - -![Knowledge Graph Overview](./img/knowledge-graph-overview.png) -*The Knowledge Graph interface showing nodes and their connections* - -## Filtering Your Graph - -Use the **Filters** panel on the left of the page to focus on specific resources, then click **Apply Filters**. - -![Filter Controls](./img/knowledge-graph-filters.png) -*The Filters panel on the left of the Knowledge Graph* - -### Account - -Select one or more cloud accounts to display only resources from those accounts. This is useful when you have multiple AWS accounts or cloud providers connected. - -### Node - -Select specific nodes/workloads to focus the graph on particular services or resources. The dropdown shows all available resources by their unique identifier. - -### Node Type - -Filter by resource type to see only certain categories of resources: -- **Workload** - Application deployments and workloads -- **Pod** - Kubernetes pods -- **Service** - Kubernetes services -- **LoadBalancer** - Load balancers and ingress controllers -- **Database** - RDS, databases, and data stores -- **Storage** - S3 buckets, EBS volumes, persistent volumes - -### Label Filter - -Filter resources by their Kubernetes labels using the Query panel. Type a label name or select from the autocomplete suggestions. - -**Common labels available:** -- `app` - Application name -- `app.kubernetes.io/name` - Kubernetes recommended app name -- `app.kubernetes.io/component` - Component within the application -- `app.kubernetes.io/instance` - Instance identifier -- `app.kubernetes.io/managed-by` - Tool managing the resource - -**Example:** To find all resources with the `app` label, click the Label Filter field and select `app` from the dropdown, then enter your desired value. - -### Attribute Filter - -Filter resources by their properties or attributes using the Query panel. Type an attribute name or select from the autocomplete suggestions. - -**Example:** To find all production resources, click the Attribute Filter field and select `environment` from the dropdown, then enter `production` as the value. - -## Navigation Controls - -### Zoom Controls (Left Side) - -The graph canvas has navigation controls on the left side: - -- **Zoom In (+)** - Increase zoom level for closer inspection -- **Zoom Out (-)** - Decrease zoom level to see more of the graph -- **Fit to View** - Automatically center and fit all nodes in the viewport -- **MiniMap Toggle** - Show or hide the minimap overview -- **Scroll Wheel** - Use your mouse scroll wheel to zoom in and out directly on the canvas - -### MiniMap - -When enabled, the minimap shows an overview of the entire graph. Click on any area of the minimap to quickly navigate to that section of the graph. - -### Drag and Pan - -- **Drag nodes** - Click and drag any node to reposition it on the canvas -- **Pan canvas** - Click and drag on the background to move the entire view - -![Knowledge Graph walkthrough: navigating from Home to Troubleshoot, opening the Knowledge Graph, narrowing the graph with the Node filter, then using the zoom, fit-to-screen, and drill-down controls](./img/knowledge-graph-navigation.gif) -*Zoom controls (top-left) and MiniMap (bottom-right)* - -## Understanding the Visualization - -### Nodes - -Each node represents a resource in your infrastructure. Nodes display: - -- **Name** - The resource name (title) -- **Type** - Resource type and kind (subtitle, e.g., "Workload - Deployment") -- **Account** - The cloud account the resource belongs to -- **Icon** - Visual indicator of the service type or programming language - -Node border colors indicate the resource category: -- **Blue border** - Workload resources -- **Green border** - Other resource types - -### Edges - -Edges are the animated lines connecting nodes, representing relationships between resources. Each edge shows: - -- **Arrow direction** - Indicates the direction of the relationship -- **Label** - The type of relationship (e.g., "CALLS", "RUNS_ON") - -### Relationship Types - -| Relationship | Description | -|-------------|-------------| -| CALLS | Service-to-service communication | -| RUNS_ON | Workload running on a specific node | -| HOSTED_ON | Infrastructure hosting the resource | -| EXPOSES | Service exposing a port or endpoint | -| ROUTES_THROUGH | Network traffic routing path | -| RESOLVES_TO | DNS or service discovery resolution | -| PULLS_FROM | Container image retrieval source | -| MOUNTS | Storage volume attachment | -| PROVIDES_STORAGE | Storage provisioning source | -| IS_BOUND_TO | Resource binding configuration | -| IS_CONFIGURED_BY | Configuration source (ConfigMap/Secret) | -| IS_ENCRYPTED_BY | Security encryption provider | -| BELONGS_TO | Logical grouping or ownership | -| BUILT_FROM | Source image or build origin | -| EMITS_LOGS_TO | Logging destination | - -Click the info icon in the top bar to view the full legend at any time. - -## Interacting with the Graph - -### Click a Node (Graph Traversal) - -Clicking on a node adds it to the **Node** filter and refreshes the graph to show only that node and its direct neighbors. This allows you to **traverse the graph** by clicking through connected nodes: - -- **Explore dependencies** - Click a node to see what it connects to -- **Drill down** - From a large graph, click to focus on one service -- **Trace connections** - Follow upstream and downstream relationships -- **Navigate step-by-step** - Click on a neighbor to move to that node's neighborhood - -To traverse further, simply click on any visible neighbor node. The graph will refresh to show that node's connections, allowing you to walk through the infrastructure one hop at a time. - -### Hover over a Node - -Hovering highlights the node and its connections: -- **Hovered node** - Blue glow effect -- **Connected nodes** - Highlighted with blue border -- **Connected edges** - Turn blue with increased thickness -- **Unconnected nodes** - Dimmed to 30% opacity for clarity - -This makes it easy to trace dependencies and understand what a resource connects to. - -![Hover Highlighting](./img/knowledge-graph-hover.png) -*Hovering highlights connected nodes and dims unrelated ones* - -### Click an Edge - -Clicking on an edge (connection line) opens the Edge Details modal showing: -- Source node name -- Destination node name -- Relationship type -- Cloud account association -- Additional edge properties - -### Info Button - -Click the info icon on any node to directly open its properties table without adding it to the filter. - -## Understanding Nodes and Edges - -### Node Categories - -**Application Layer:** -- Workload, Service, ExternalService, ServerlessFunction - -**Kubernetes Resources:** -- Cluster, Namespace, Pod, Node, K8sService, Ingress, ConfigMap, Secret, PersistentVolume, PersistentVolumeClaim - -**Cloud Resources:** -- LoadBalancer, Database, Storage, VPC, Subnet, SecurityGroup, IAMRole, IAMPolicy - -### Edge Data - -Each edge contains: -- Source and destination node identifiers -- Relationship type describing how resources connect -- Cloud account association -- Additional properties specific to the relationship - -## Limits and Performance - -- **Maximum 2000 nodes** can be displayed at once -- A warning message appears if your graph exceeds this limit -- Use filters to narrow down the view when working with large infrastructures - -## Tips for Effective Use - -1. **Start broad, then filter** - Begin with Account and Node Type filters to focus on relevant resources -2. **Use labels for precision** - Kubernetes labels help find specific applications or environments -3. **Explore dependencies** - Click on a node to filter the graph to just that node and its neighbors -4. **Navigate large graphs** - Use the MiniMap to quickly jump to different areas -5. **Trace visually** - Hover over nodes to see their direct connections highlighted -6. **Check relationship types** - The legend explains what each edge type means for your infrastructure diff --git a/doc-server/docs/features/knowledge-graph/_category_.json b/doc-server/docs/features/knowledge-graph/_category_.json new file mode 100644 index 00000000..9a4bb8b6 --- /dev/null +++ b/doc-server/docs/features/knowledge-graph/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Semantic Knowledge Graph", + "position": 8, + "collapsed": false, + "link": { "type": "doc", "id": "features/knowledge-graph/index" } +} diff --git a/doc-server/docs/features/knowledge-graph/data-sources.md b/doc-server/docs/features/knowledge-graph/data-sources.md new file mode 100644 index 00000000..4e20003d --- /dev/null +++ b/doc-server/docs/features/knowledge-graph/data-sources.md @@ -0,0 +1,89 @@ +--- +sidebar_position: 4 +sidebar_label: Where the Data Comes From +keywords: [knowledge graph, data sources, flow sources, coverage, ebpf, traces, rebuild] +--- + +# Where the Data Comes From + +NudgeBee builds the graph from three kinds of source: + +- **Inventory** — the resources in your clusters, cloud accounts and integrations. +- **Flow sources** — the calls services actually make to each other, from eBPF, traces and APM tools. +- **Links between them** — NudgeBee joins resources from different sources, such as a Kubernetes node and the EC2 instance it runs on. + +You do not set up the graph separately. Connect a cluster, an account or an integration, and its data appears at the next hourly rebuild. + +## Inventory + +| Source | Adds | You need | +|:---|:---|:---| +| **Kubernetes** | Clusters, namespaces, nodes, workloads, pods, services, ingresses, persistent volumes, config maps, secrets, service accounts, Helm charts, Karpenter node pools | A cluster connected with the NudgeBee agent. Workloads, pods and nodes come from the cluster inventory. Services, volumes, config maps, secrets, ingresses, service accounts and Karpenter objects are read live from the agent, so they drop out while the agent is disconnected and return when it reconnects. | +| **AWS, GCP, Azure** | Compute, databases, storage, queues, load balancers, networks, DNS, IAM and the rest of the cloud inventory | A connected cloud account. Resources appear once NudgeBee has discovered them. | +| **GitHub, GitLab** | Organizations or groups, repositories or projects, teams, users, and who can access which repository | An enabled GitHub or GitLab integration | +| **PagerDuty** | On-call services, teams and users | An enabled PagerDuty integration | +| **Ownership** | Which user or team owns each workload, namespace, cluster and cloud resource | Owners set under **Admin → Access & Users → Ownership** | +| **Identity** | One node per NudgeBee user, linked to the same person's GitHub, GitLab or PagerDuty account | Users matched to their integration accounts | +| **You** | Dependencies and resources no collector can see | Declared in Knowledge Graph **Settings** | + +## Flow sources + +Flow sources add the calls between services, as `CALLS` relationships. Each one can be switched off under [Coverage](#choose-what-feeds-the-graph-coverage). + +| Flow source | What it observes | You need | +|:---|:---|:---| +| **eBPF** | Network calls between workloads in a cluster, captured by the NudgeBee agent | A cluster with the agent connected | +| **Traces** | Calls in your OpenTelemetry traces, from the last 2 hours at each rebuild | A cluster with the agent connected, and a trace provider connected for its account. See [Observability integrations](../../integrations/Observability/index.md). | +| **Datadog APM** | Service-to-service calls Datadog APM has observed | A Datadog integration with an API key and application key, linked to an account | +| **New Relic APM** | Outgoing calls in New Relic span data, from the last 24 hours | A New Relic integration with an API key and account id, linked to an account | + +eBPF and Traces can add a service or an external dependency the graph did not have yet. Datadog APM and New Relic APM only add calls between resources that are already in the graph. + +When several sources see the same call, NudgeBee keeps one edge and records what each source measured. See [Edge details](./nodes-and-relationships.md#edge-details). + +## Links between sources + +After collecting, NudgeBee connects resources that describe the same thing or depend on each other across sources, for example: + +- A Kubernetes node `RUNS_ON` the EC2 or Compute Engine instance behind it. +- A cluster `RUNS_ON` its EKS, GKE or AKS cluster. +- A Kubernetes service account `ASSUMES` the IAM role or GCP service account it is mapped to. +- A persistent volume is backed by (`PROVIDES_STORAGE`) an EBS volume or persistent disk. +- A workload `PULLS_FROM` its ECR repository, and a Cloud Run service from Artifact Registry. +- An AWS load balancer `ROUTES_TO` the Kubernetes service and pods behind it. +- A DNS zone `RESOLVES_TO` the load balancer it points at. + +When traces or eBPF show a call to a hostname, NudgeBee replaces the generic external dependency with the real cloud resource where it can, such as the RDS instance or S3 bucket the hostname belongs to. + +## How fresh it is + +| What | When it updates | +|:---|:---| +| The whole graph | Rebuilt every hour. There is no button to rebuild on demand. | +| A newly connected cluster, account or integration | Appears at the next rebuild after NudgeBee has collected from it. | +| A resource you delete | Disappears at the next rebuild after NudgeBee stops seeing it. | +| A call between services | Taken from what each flow source observes at each rebuild: the last 2 hours of traces, and the last 24 hours of Datadog APM and New Relic APM data. Removed once it has not been seen for 7 days. | +| An external dependency (`ExternalService`) | Removed once nothing has called it for 7 days. | +| An account that is disabled or deleted | Its resources are removed at the next rebuild, or straight away when the account is deleted. | + +## Choose what feeds the graph (Coverage) + +Tenant admins can choose which cloud accounts and flow sources feed the graph. + +1. Open **Troubleshoot → Knowledge Graph** and click **Settings**. +2. On the **Coverage** tab, tick the **Cloud accounts** and **Flow sources** to include. Use **Search accounts** to find an account by name, number or provider. +3. Click **Save**. + +How the selection works: + +- **Leaving everything ticked means "all"**, including accounts you connect later. If you untick every box, NudgeBee also saves "all", not "none", and says so before you save. +- **Removing takes effect immediately.** When you untick an account, every node and edge it owns is removed on save. When you untick a flow source, every edge it created is removed. The **Save** button turns red and asks you to confirm. +- **Adding takes effect at the next hourly rebuild.** Ticking an account or flow source again does not bring its data back until then. +- Every change is recorded in the audit log under the **Knowledge graph** category. + +## Related + +- [Explore the Graph](./exploring.md) +- [Nodes and Relationships](./nodes-and-relationships.md) +- [Connect a Kubernetes cluster](../../installation/agent/index.md) +- [Cloud accounts](../Cloud/index.md) diff --git a/doc-server/docs/features/knowledge-graph/exploring.md b/doc-server/docs/features/knowledge-graph/exploring.md new file mode 100644 index 00000000..b9f61eda --- /dev/null +++ b/doc-server/docs/features/knowledge-graph/exploring.md @@ -0,0 +1,84 @@ +--- +sidebar_position: 2 +sidebar_label: Explore the Graph +keywords: [knowledge graph, filters, search, focus, traversal, level] +--- + +# Explore the Graph + +The Knowledge Graph screen has two parts: the **Filters** panel on the left decides which slice of the graph is loaded, and the canvas on the right draws it. Start broad, narrow with filters, then click through nodes to follow a dependency chain. + +![Knowledge Graph walkthrough: navigating from Home to Troubleshoot, opening the Knowledge Graph, narrowing the graph with the Node filter, then using the zoom, fit-to-screen, and drill-down controls](../img/knowledge-graph-navigation.gif) +*Opening the Knowledge Graph, narrowing it with the Node filter, and drilling down* + +## Filters + +![The Filters panel: Account, Node Type, Node and Level dropdowns, the Label and Attribute filters, and the Apply Filters and Clear All buttons](../img/knowledge-graph-filters.png) +*The Filters panel* + +Choose filters, then click **Apply Filters**. The button stays disabled until something has changed. **Clear All** removes every filter and reloads the whole graph. The ⓘ next to each filter explains it in the app. + +| Filter | What it does | +|:---|:---| +| **Account** | Show only resources owned by the selected accounts, grouped by cloud provider. Leave it empty to include every connected AWS, GCP, Azure and Kubernetes account. | +| **Node Type** | Show only certain kinds of resource. Each broad type, such as **ComputeInstance**, **Database** or **Workload**, can be expanded to pick only some of its sub-types, for example just **EC2Instance** under ComputeInstance. | +| **Node** | Center the graph on one or more specific resources. Each option shows where it came from, its type, its name, and where it lives (cluster · namespace for Kubernetes, region · VPC for cloud). Typing matches name, cluster, namespace, region and type. | +| **Level** | How many relationship hops to expand out from the selected nodes: **1 - Direct neighbors**, **2 - 2 hops** or **3 - 3 hops**. It only applies when a node is selected. | +| **Label filter** | Match nodes by label, for example `app = checkout`. | +| **Attribute filter** | Match nodes by a property of the resource, for example `namespace = payments`. | + +Things worth knowing: + +- **Selecting a node clears Account, Node Type, Label and Attribute.** The node becomes the center of the graph and everything else is reached from it by Level. +- **Once nodes are selected, the Node list narrows to their neighbors,** so you can keep picking the next hop. +- **Several label or attribute conditions must all match** (they are combined with AND). The only comparison is equals. +- **Filters are not saved.** They reset when you reload the page, and there is no link that carries them. + +## Search and focus + +**Search nodes…** at the top right finds a node among those currently on the canvas. A name that exists in more than one account is shown as `name · account`. + +Picking a result enters **focus**: the canvas shows only that node and its direct neighbors, laid out again so they are easy to read. A **Focus: name** banner appears above the canvas; click its × or clear the search to return to the full view. + +You can also focus from a node itself with its focus button (tooltip "Focus on this node"). + + +## Click through the graph + +Clicking a node makes it the center of the graph: it is added to the **Node** filter, the other filters are cleared, and the graph reloads around it at the current Level. Click one of its neighbors to move one hop further, and so on, to walk a dependency chain one step at a time. + +Above the canvas: + +- **Path** lists the nodes you have clicked through. NudgeBee fills in any nodes between them on the shortest route, shown with a dashed border. Click a step to go back to it, or its × to remove it. **Details** shows the full path with the relationship between each pair. +- **Back** and **Forward** step through the filter states you have applied in this visit, up to 20. + + +## Read the canvas + +- **Hover a node** to highlight it, its neighbors and the edges between them; everything else fades. +- **Hover an edge** to see the relationship, for example "Runs On". +- **Click an edge** to open its details, and click a node's ⓘ to open the node's details. See [Nodes and Relationships](./nodes-and-relationships.md). +- **Drag** a node to move it, or drag the background to pan. +- **Controls** at the top left zoom in and out, fit the graph to the screen, and lock the canvas. +- **MiniMap** at the bottom right shows an overview of the whole graph and where you are in it. It is hidden on graphs of more than 1,000 nodes. +- When you zoom far out, nodes shrink to dots with short labels so a large graph stays readable. +- **Hover Relationships** at the top right for a legend of the common relationship types. The full list is in [Nodes and Relationships](./nodes-and-relationships.md#relationship-types). + +![Hovering a node highlights it and its connections and fades the rest](../img/knowledge-graph-hover.png) +*Hovering highlights a node's connections* + +## Limits and empty states + +The canvas draws at most **1,500 nodes**. When the current selection is larger you see **Graph Too Large to Render**, with the number of nodes it contains. Narrow it with Account, Node Type or Node and apply again. + +| You see | It means | +|:---|:---| +| **Building your Knowledge Graph** | The tenant has no graph yet. It appears at the first hourly rebuild after NudgeBee has collected from your first cluster or account. | +| **No nodes match your filters** | The filters exclude everything. Try another node, a broader Level, or **Clear Filters**. | + +## Tips + +1. **Start from a node.** Picking one service in **Node** and stepping out with **Level** is faster than filtering the whole tenant down. +2. **Use Node Type for infrastructure questions.** For example, select only VPC and Subnet in one account to see its network layout. +3. **Use focus for busy nodes.** A shared database or gateway can have dozens of neighbors; focus shows them without the rest of the graph. +4. **Check Path when two things look connected.** Its Details view shows exactly which relationships link them. diff --git a/doc-server/docs/features/knowledge-graph/how-nudgebee-uses-it.md b/doc-server/docs/features/knowledge-graph/how-nudgebee-uses-it.md new file mode 100644 index 00000000..4b35d6ae --- /dev/null +++ b/doc-server/docs/features/knowledge-graph/how-nudgebee-uses-it.md @@ -0,0 +1,63 @@ +--- +sidebar_position: 5 +sidebar_label: How NudgeBee Uses the Graph +keywords: [knowledge graph, nubi, impact, blast radius, criticality, incident] +--- + +# How NudgeBee Uses the Graph + +You can browse the Knowledge Graph directly, but most of the time it works in the background. These are the places it changes what you see. + +## NuBi's answers about dependencies + +When you ask NuBi a dependency question, it hands the question to the **Dependency Mapper** agent, which reads the graph. It answers questions such as: + +- What does `checkout` call, and what calls it? +- Where is this workload hosted, and what does it run on? +- Which load balancer routes to this service? +- What is in this VPC? +- Find the database named `orders`. + +The agent only reports relationships the graph has actually recorded, and asks you to choose when a name matches more than one resource. + +During an investigation, NuBi also follows the graph downstream from the failing service to find where a problem started. See [Incident RCA](../ai/use-cases/incident-rca.md). + +## Alert impact and grouping + +When an alert fires, NudgeBee looks up the alerted resource in the graph and walks outward to the services that depend on it. It uses that to put the alert in context on the event's investigation page: + +- **Possible Cause & Impact** groups the alerts that belong together: other alerts about the same service, what probably caused it, what it affected, other alerts from the same node running out of memory, and alerts it set aside as background noise. When there is too little graph data around the resource, the card says it can't tell what was affected. +- **Service Dependencies** draws a small map around the alerted service, with callers and callees, and summarizes it, for example "3 services call checkout". + +The richer the graph around a service, the better this works. Where the graph has little around a service, NudgeBee leans on other signals, such as recent configuration changes and alerts from the same node or namespace. + +## Blast radius on recommendations + +On an [Optimization](../optimizations/index.md) recommendation, the **Blast Radius & Safety** card uses the graph to show what the change could affect. Its headline is the resource's **dependents**: the services that call or rely on it, which decide how carefully the change should be applied. Open the neighborhood below it for context: + +- **Depends on** — what the resource itself calls, publishes to or subscribes to. These are not at risk from the change. +- **Runs on this machine** — workloads currently scheduled on the instance, which reschedule if the machine changes. +- **Attached infrastructure** — resources directly attached to it, such as the instance a volume backs. + +Each dependency is tagged with how NudgeBee knows about it, such as *Observed in traces*, *Observed traffic*, *Observed via APM*, *User-declared*, *Platform metadata* or *Inferred*. A coverage rating says how well the graph's view of the workload is backed: **High** when two or more independent signals agree, **Observed** for one live signal, **Low** for a single source that has not been cross-checked, and **None** when the workload is not in the graph. Use it to judge how much to trust an empty list. + +## Service criticality + +[Service Criticality](../service-criticality.md) uses two graph facts to suggest which workloads matter most: + +- **Customer-facing** — the workload sits behind an ingress or load balancer. +- **Shared dependency** — ten or more other workloads call it. + +Either one nominates the workload for a higher tier. An AI review then sets the tier, and you can change it on the Service Criticality screen. + +## Making the graph more useful + +- **Turn on flow sources.** eBPF, traces, Datadog APM and New Relic APM give the graph the calls between services. Without them it knows where things run, but much less about who talks to whom. +- **Set owners.** Owners set under **Admin → Access & Users → Ownership** appear in the graph as `OWNS` relationships. +- **Declare what NudgeBee cannot see.** A call that no flow source observes, or a database outside your connected accounts, can be added in Knowledge Graph **Settings**. + +## Related + +- [Semantic Knowledge Graph](./index.md) +- [Where the Data Comes From](./data-sources.md) +- [NuBi and the pre-built AI agents](../ai/index.md) diff --git a/doc-server/docs/features/knowledge-graph/index.md b/doc-server/docs/features/knowledge-graph/index.md new file mode 100644 index 00000000..61eb9704 --- /dev/null +++ b/doc-server/docs/features/knowledge-graph/index.md @@ -0,0 +1,66 @@ +--- +sidebar_position: 1 +sidebar_label: Overview +keywords: [knowledge graph, service map, dependencies, topology] +--- + +# Semantic Knowledge Graph + +The Semantic Knowledge Graph is a live map of your environment: every service, workload and cloud resource NudgeBee knows about, and how they depend on each other. It joins what NudgeBee collects from your Kubernetes clusters and cloud accounts with the calls it observes between services, so a dependency that crosses a cluster, an account or a cloud provider still shows up as one connected picture. + +NudgeBee uses the same graph to work out what an alert affects, to rank which failures matter, and to give [NuBi and the pre-built AI agents](../ai/) the context they need to trace a problem to its source. + +![Knowledge Graph Overview](../img/knowledge-graph-overview.png) +*The Knowledge Graph, with the Filters panel on the left and the graph on the right* + +## Why use it + +- **See real dependencies.** The calls services make to each other come from eBPF, distributed traces and APM data, not from a hand-drawn diagram. +- **Follow a problem across boundaries.** A pod, the node it runs on, the EC2 instance behind that node and the database it calls are all in one graph. +- **Check impact before you change something.** Select a resource and expand outward to see what depends on it. +- **Get better answers from the AI.** NuBi reads the graph to answer questions such as "what calls this service?" and to walk an incident back to its cause. + +## Where to find it + +- **Troubleshoot → Knowledge Graph.** The tab sits between Event Resolutions and Analytics. You can also type "Knowledge Graph" in the search bar at the top of any page. +- **b-Cortex → Knowledge Graph.** In the Enterprise edition, the same graph is a tab of b-Cortex, opened from the button at the bottom of the left rail. + +The first time you open it, a welcome card offers a short guided tour of how to read and drive the graph. + +## What is in the graph + +| Kind of data | Examples | Comes from | +|:---|:---|:---| +| Kubernetes resources | Clusters, namespaces, nodes, workloads, pods, services, ingresses, volumes, config maps | The NudgeBee agent in each cluster | +| Cloud resources | EC2 instances, load balancers, RDS and Cloud SQL databases, S3 buckets, queues, VPCs, IAM roles | Your connected AWS, GCP and Azure accounts | +| Service-to-service calls | `CALLS` | eBPF, distributed traces, Datadog APM, New Relic APM | +| Code and on-call | Repositories, teams, users, on-call services | GitHub, GitLab and PagerDuty integrations | +| Ownership | Which team owns which workload or resource | **Admin → Access & Users → Ownership** (see [User Management](../user-management.md)) | + +NudgeBee also links resources across sources, for example a Kubernetes node to the EC2 instance it runs on, or a Kubernetes service account to the IAM role it assumes. See [Where the Data Comes From](./data-sources.md). + +## How fresh it is + +The graph rebuilds every hour. The **Last synced** time at the top of the Filters panel shows when the last rebuild finished. + +- Calls between services come from what each flow source observes at each rebuild. A call that has not been seen for 7 days drops out. +- A resource you delete from a cluster or account disappears at the next rebuild after NudgeBee stops seeing it. +- There is no button to rebuild on demand; changes appear at the next hourly rebuild. + +## Who can see it + +Every role that can use Troubleshoot can open the Knowledge Graph, from namespace admins to tenant admins. A user with a custom role needs the `kg:Read` permission; without it the tab is shown but grayed out. + +Only tenant admins see the **Settings** button. It controls which accounts and flow sources feed the graph (see [Coverage](./data-sources.md#choose-what-feeds-the-graph-coverage)), and is where dependencies and resources no collector can see are declared by hand. + +## In this section + +- [Explore the Graph](./exploring.md) — filters, search, focus, traversal and the canvas controls +- [Nodes and Relationships](./nodes-and-relationships.md) — reading a node, node and edge details, and the full type reference +- [Where the Data Comes From](./data-sources.md) — every source, what it needs, rebuild timing, and the Coverage settings +- [How NudgeBee Uses the Graph](./how-nudgebee-uses-it.md) — AI answers, alert impact, blast radius and criticality + +## Related + +- [Service Criticality](../service-criticality.md) — tiers derived from the graph's topology +- [Troubleshooting](../troubleshooting/index.md) diff --git a/doc-server/docs/features/knowledge-graph/nodes-and-relationships.md b/doc-server/docs/features/knowledge-graph/nodes-and-relationships.md new file mode 100644 index 00000000..dae42284 --- /dev/null +++ b/doc-server/docs/features/knowledge-graph/nodes-and-relationships.md @@ -0,0 +1,141 @@ +--- +sidebar_position: 3 +sidebar_label: Nodes and Relationships +keywords: [knowledge graph, node types, relationship types, edges, node details] +--- + +# Nodes and Relationships + +Every node in the graph is one resource, and every edge is one relationship between two resources, drawn as an arrow from the first to the second. This page explains how to read them and lists every type the graph uses. + +## Reading a node + +Each node card shows: + +- **Icon** — the vendor or language logo, for example PostgreSQL, Redis, Kafka, Go or Java, when NudgeBee can tell; otherwise an icon for the type. +- **Name** — the resource's name. +- **Type line** — the node's type, for example *Workload* or *ComputeInstance*, sometimes with a role such as *Database*, *Cache* or *Queue*, and its location, such as a region. +- **Account line** — the account it belongs to, and its namespace for a Kubernetes resource. A resource you declared by hand outside any connected account reads *Not in a connected account*. + +The border is **blue** for workloads and **green** for everything else. + +### Type and sub-type + +Every node has a **type**, such as `Database`, `ComputeInstance` or `Workload`, that means the same thing in every cloud. Most also have a **sub-type** that says exactly what it is: a `Database` can be an `RDSInstance`, a `CloudSQLInstance` or an `AzureSQLDatabase`; a `Workload` can be a `KubernetesDeployment` or a `KubernetesStatefulSet`. The **Node Type** filter is organized the same way: select a type to see all of it, or expand it to pick sub-types. + +## Node details + +Click the ⓘ on a node to open **Node Details**. + +| Shows | What it is | +|:---|:---| +| **Unique Key** | The identifier NudgeBee uses for the resource across rebuilds, with a copy button. | +| **Last Seen** | When the graph last saw the resource. | +| **Path to this node** | When you have clicked through nodes, the route from the first one to this one, with each relationship. | +| **Labels** | The resource's properties: its labels, tags and collected details such as region, engine or replica count. | + +Kubernetes resources have more tabs: + +| Resource | Extra tabs | +|:---|:---| +| Namespace, Node, Pod | Utilization Trends, Related Events | +| Workload, Job, CronJob | Utilization Trends, Related Events, Traces (last 24 hours), Logs (last 60 minutes), App Dashboard, Log Group | + +## Edge details + +Click an edge to open **Edge Details**. It shows the relationship type, when the edge was last seen, and the properties recorded for it. What those are depends on where the edge came from: + +| Edge from | Properties you may see | +|:---|:---| +| eBPF | Protocol, latency, status, the source and destination workloads | +| Distributed traces | Protocol, latency, request and failure counts, bytes sent and received, status | +| Datadog APM | Operation, span kind, protocol, the Datadog services at each end | +| New Relic APM | Request count, protocol, the New Relic services at each end | + +When more than one source sees the same call, NudgeBee keeps one edge and records the metrics from each source, with the other sources' values prefixed by the source's name, for example `traces_latency_ms`. + +## Node types + +| Group | Types | +|:---|:---| +| Applications | Service, Workload, ExternalService, ServerlessFunction, Job, CronJob | +| Data | Database, Cache, MessageQueue, Queue, Topic | +| Kubernetes | Cluster, ManagedCluster, Namespace, Node, Pod, K8sService, Ingress, ConfigMap, K8sSecret, K8sServiceAccount, PersistentVolume, PersistentVolumeClaim, ComputeInstancePool, CustomResource | +| Compute and network | ComputeInstance, LoadBalancer, BackendPool, VPC, Subnet, SecurityGroup, NetworkInterface, RouteTable, NetworkGateway, PrivateEndpoint, PublicIP, DNSZone, CDN, APIGateway | +| Storage and build | Storage, ContainerRegistry, ContainerImage, BackupVault, BackupPolicy, HelmChart, Repository | +| Security and operations | ServiceIdentity, SecretVault, EncryptionKey, SecurityService, MonitoringService, LogAggregator, EmailService, AIService, InfraStack | +| People and code | SourceControlOrg, UserAccount, UserGroup, OnCallService | +| Other | CloudResource — a cloud resource that does not fit another type | + +`ExternalService` is something your services call that NudgeBee cannot place in a connected account, for example a SaaS API. Where it can, NudgeBee replaces it with the real cloud resource behind the hostname. + +Kubernetes Jobs and CronJobs from your cluster inventory appear as **Workload** nodes, with the sub-type (`KubernetesJob`, `KubernetesCronJob`) telling them apart. The `Job` and `CronJob` types are used for scheduled jobs found in other ways, such as GCP Cloud Scheduler jobs. + +## Relationship types + +Read each one as *source → destination*. + +### Communication + +| Relationship | Meaning | +|:---|:---| +| `CALLS` | The source sends requests to the destination: an HTTP or gRPC call, a database query. | +| `PUBLISHES_TO` | The source writes messages to a queue or topic. | +| `SUBSCRIBES_TO` | The source reads messages from a queue or topic. | +| `ROUTES_TO` | A load balancer, CDN or gateway sends traffic to a backend. | +| `ROUTES_TO_SERVICE` | An ingress sends traffic to a Kubernetes service. | +| `ROUTES_THROUGH` | Traffic passes through the destination, for example a route table through a gateway. | +| `RESOLVES_TO` | A DNS name resolves to the destination. | +| `EXPOSES` | A workload is exposed through a Kubernetes service. | +| `CONNECTION_REJECTED` | The network refused connections from the source to the destination. | + +### Infrastructure + +| Relationship | Meaning | +|:---|:---| +| `RUNS_ON` | The source runs on or in the destination: a pod on a node, a node on an EC2 instance, a cluster on EKS, a workload in a namespace, a namespace or node in a cluster. | +| `RUNS_IN` | An ECS service runs in an ECS cluster. | +| `HOSTED_ON` | The source is placed in or attached to the destination, such as a VPC, subnet, host or security group. | +| `BELONGS_TO` | The source is part of the destination, for example a config map in a namespace. | +| `MANAGES` | The source manages the destination, for example a CloudFormation stack and its resources, or a Karpenter node pool and the node claims it creates. | +| `ASSOCIATED_WITH` | The two are attached, for example an elastic IP and an instance. | +| `PROTECTS` | A security group or firewall protects the destination. | + +### Storage, configuration and images + +| Relationship | Meaning | +|:---|:---| +| `MOUNTS` | A workload mounts a persistent volume claim. | +| `IS_BOUND_TO` | A persistent volume claim is bound to a persistent volume. | +| `PROVIDES_STORAGE` | A persistent volume is backed by a cloud disk. | +| `STORES_IN` | A backup plan stores its backups in a backup vault. | +| `USES_CONFIG` | A workload reads a config map. | +| `USES_SECRET` | A workload reads a secret. | +| `USES_IMAGE` | A workload or function runs a container image. | +| `PULLS_FROM` | A workload pulls images from a container registry. | +| `IS_CONFIGURED_BY` | A workload is deployed from a Helm chart, or a chart comes from a Git repository. | +| `BUILT_FROM` | A workload is built from a Git repository. | + +### Identity and security + +| Relationship | Meaning | +|:---|:---| +| `USES_SERVICE_ACCOUNT` | A workload runs as a Kubernetes service account. | +| `RUNS_AS` | A compute resource runs as a cloud identity, such as an IAM role. | +| `ASSUMES` | An identity can assume another identity, such as a Kubernetes service account assuming an IAM role. | +| `HAS_ACCESS_TO` | An identity or user has access to a resource or repository. | +| `IS_ENCRYPTED_BY` | A resource is encrypted with a key. | +| `EMITS_LOGS_TO` | A resource sends its logs to a log destination. | + +### People and ownership + +| Relationship | Meaning | +|:---|:---| +| `OWNS` | A user or team owns a workload, namespace, cluster or cloud resource; an organization, group or user owns a repository; a team owns an on-call service. | +| `MEMBER_OF` | A user or team belongs to a team or organization. | +| `SAME_AS` | A GitHub, GitLab or PagerDuty user is the same person as a NudgeBee user. | + +## Related + +- [Explore the Graph](./exploring.md) +- [Where the Data Comes From](./data-sources.md) — which source produces which nodes and relationships diff --git a/doc-server/docs/features/service-criticality.md b/doc-server/docs/features/service-criticality.md index e8755c7c..62cf0d4f 100644 --- a/doc-server/docs/features/service-criticality.md +++ b/doc-server/docs/features/service-criticality.md @@ -75,4 +75,4 @@ Start with the workloads NudgeBee derived as `high` and decide which are genuine ## Related - [Event Lifecycle & Triage](./troubleshooting/event-lifecycle.md) -- [Semantic Knowledge Graph](./knowledge-graph.md) — the topology behind fan-in and customer-facing signals +- [Semantic Knowledge Graph](./knowledge-graph/index.md) — the topology behind fan-in and customer-facing signals diff --git a/doc-server/docs/features/troubleshooting/index.md b/doc-server/docs/features/troubleshooting/index.md index 336111a9..3e8aa46c 100644 --- a/doc-server/docs/features/troubleshooting/index.md +++ b/doc-server/docs/features/troubleshooting/index.md @@ -3,7 +3,7 @@ sidebar_position: 1 --- # Troubleshooting -NudgeBee's troubleshooting dashboard gives you a real-time view of events, errors, and anomalies across all your connected Kubernetes clusters. Instead of switching between multiple monitoring tools, you get a single pane of glass — powered by the [Semantic Knowledge Graph](../knowledge-graph.md) — that correlates metrics, logs, traces, and code to help you find the root cause of issues faster, reducing MTTR from hours to minutes. +NudgeBee's troubleshooting dashboard gives you a real-time view of events, errors, and anomalies across all your connected Kubernetes clusters. Instead of switching between multiple monitoring tools, you get a single pane of glass — powered by the [Semantic Knowledge Graph](../knowledge-graph/index.md) — that correlates metrics, logs, traces, and code to help you find the root cause of issues faster, reducing MTTR from hours to minutes. ![NudgeBee Troubleshoot dashboard showing NuBi's daily briefing above the triage inbox, with event severity and triage scores, and the All Events, Investigations, Event Resolutions, Knowledge Graph, and Analytics tabs](./img/troubleshoot-overview.png) @@ -11,7 +11,7 @@ NudgeBee's troubleshooting dashboard gives you a real-time view of events, error - **Monitor real-time events** — See pod crashes, OOM kills, deployment failures, and other Kubernetes events as they happen. - **AI-powered root cause analysis with NuBi** — When an [LLM is connected](../../integrations/LLM/), NuBi (the SRE AI Agent) and NudgeBee's [pre-built AI agents](../ai/) automatically analyze incidents, correlate signals across the Semantic Knowledge Graph, and suggest root causes in plain language. -- **Explore the Semantic Knowledge Graph** — Visualize your infrastructure dependencies and trace how issues propagate across services. See [Semantic Knowledge Graph](../knowledge-graph.md). +- **Explore the Semantic Knowledge Graph** — Visualize your infrastructure dependencies and trace how issues propagate across services. See [Semantic Knowledge Graph](../knowledge-graph/index.md). - **Configure alerting rules** — Set up custom alerting rules to get notified when specific conditions are met. See [Alerting](./alerting.md). - **Attach event playbooks** — Run evidence-collection actions (logs, metrics, custom SQL, kubectl, cloud CLI, SSH, …) automatically on each event so the LLM has the data it needs. See [Playbook Catalog](./playbook-catalog.md). - **Understand the split between playbooks and workflows** — Playbooks gather evidence for the LLM; [workflows](../workflow-builder/index.md) post-process the resulting event (triage, ticketing, remediation). See [Event Playbooks vs Workflows](./event-playbooks-vs-workflows.md). diff --git a/doc-server/docs/index.md b/doc-server/docs/index.md index 5e0dea48..3eee9288 100644 --- a/doc-server/docs/index.md +++ b/doc-server/docs/index.md @@ -160,7 +160,7 @@ NudgeBee ships with 30+ pre-built Cloud-Ops Agents and 30+ integrations. Capabil | Integration | What It Unlocks | When It's Needed | |---|---|---| -| **[Kubernetes cluster](./installation/agent/installation/index.md)** or **[Cloud account](./features/Cloud/index.md)** | Core monitoring, [Semantic Knowledge Graph](./features/knowledge-graph.md), [cost optimizations](./features/optimizations/index.md) | **Required for infrastructure visibility** | +| **[Kubernetes cluster](./installation/agent/installation/index.md)** or **[Cloud account](./features/Cloud/index.md)** | Core monitoring, [Semantic Knowledge Graph](./features/knowledge-graph/index.md), [cost optimizations](./features/optimizations/index.md) | **Required for infrastructure visibility** | | **[Observability source](./integrations/Observability/index.md)** (Prometheus, Datadog, New Relic, etc.) | Metrics, [SLOs](./features/slo.md), alerting, [troubleshooting](./features/troubleshooting/index.md) | **Required for metrics, SLOs, and utilization graphs** | | **[LLM connection](./integrations/LLM/index.md)** (BYOM) | NuBi AI agent, natural-language triage, [auto-runbooks](./features/optimizations/autopilot/auto_runbook/index.md) | **Required for NuBi and AI-powered features** | | **[IM channel](./integrations/Notifications/index.md)** (Slack, Teams, Google Chat) | [Notifications](./features/notifications.md), interactive alerts, ChatOps | **Optional; recommended for operational alerting** | diff --git a/doc-server/docs/installation/agent/index.md b/doc-server/docs/installation/agent/index.md index 13b61702..06ee4cf3 100644 --- a/doc-server/docs/installation/agent/index.md +++ b/doc-server/docs/installation/agent/index.md @@ -5,7 +5,7 @@ sidebar_label: K8s Agent # K8s Agent -The NudgeBee Agent is a lightweight software component that runs inside your Kubernetes cluster. It collects data about workloads, performance, cost, and security, and sends it to the NudgeBee server — feeding the [Semantic Knowledge Graph](../../features/knowledge-graph.md) that powers NudgeBee's Cloud-Ops Intelligence. You need to install an agent in every cluster that you want NudgeBee to monitor. The agent supports AWS, Azure, GCP, and on-premises Kubernetes environments. +The NudgeBee Agent is a lightweight software component that runs inside your Kubernetes cluster. It collects data about workloads, performance, cost, and security, and sends it to the NudgeBee server — feeding the [Semantic Knowledge Graph](../../features/knowledge-graph/index.md) that powers NudgeBee's Cloud-Ops Intelligence. You need to install an agent in every cluster that you want NudgeBee to monitor. The agent supports AWS, Azure, GCP, and on-premises Kubernetes environments. :::info **Both Cloud SaaS and self-hosted users** need to install the agent. This is how NudgeBee gets visibility into your Kubernetes clusters, regardless of your deployment model. diff --git a/doc-server/docs/integrations/Observability/index.md b/doc-server/docs/integrations/Observability/index.md index 5a5f1740..aa5da247 100644 --- a/doc-server/docs/integrations/Observability/index.md +++ b/doc-server/docs/integrations/Observability/index.md @@ -12,7 +12,7 @@ Connecting at least one observability source is **required** for NudgeBee to fun You need this integration as part of your initial NudgeBee setup. Connect your observability tools so NudgeBee can: -- Pull metrics to power the [Knowledge Graph](../../features/knowledge-graph.md) and [Optimizations](../../features/optimizations/index.md). +- Pull metrics to power the [Knowledge Graph](../../features/knowledge-graph/index.md) and [Optimizations](../../features/optimizations/index.md). - Access logs and traces for [AI-powered troubleshooting](../../features/troubleshooting/). - Monitor [SLOs](../../features/slo.md) and trigger alerts when thresholds are breached. diff --git a/doc-server/src/css/custom.css b/doc-server/src/css/custom.css index 713a9429..f5c2a252 100755 --- a/doc-server/src/css/custom.css +++ b/doc-server/src/css/custom.css @@ -166,6 +166,16 @@ html { color: var(--ifm-color-emphasis-600); } +/* Only top-level sections are headings. A nested section (Troubleshooting, + Semantic Knowledge Graph) reads like the pages beside it. */ +.menu__list .menu__list .menu__list-item-collapsible .menu__link { + font-weight: inherit; + text-transform: none; + font-size: inherit; + letter-spacing: normal; + color: inherit; +} + /* Sidebar chevron icons — SVG-based with rounded ends */ .menu__link--sublist-caret::after, .menu__caret::before {