Documentation Grafana Cloud Knowledge graph Reference Knowledge graph data source

Knowledge graph data source

The Grafana Cloud Knowledge Graph data source (grafana-knowledgegraph-datasource) provides programmatic access to the knowledge graph through the data source interface in Grafana. Use the data source to query entities, relationships, health status, and insights.

The data source supports metrics, annotations, alerting, and template variables. You can use it in dashboards, Explore, and other Grafana features that support data sources.

Before you begin

Ensure you have a Grafana Cloud account with Grafana Cloud Knowledge Graph enabled.

Data source

Every Grafana Cloud stack with Knowledge Graph enabled includes a pre-configured Knowledge Graph data source. You can use this built-in data source or add additional instances if needed.

To add an additional knowledge graph data source:

1. In Grafana, click Connections in the left menu.

2. Under Your connections, click Data sources.

3. Click Add new data source.

4. Search for and select Knowledge Graph.

5. Configure the data source settings:

   Expand table

   Setting	Description	Required
   Name	Name to reference this data source in panels and queries.	Yes
   Backend URL	Knowledge Graph API endpoint URL.	Yes
   Basic Auth User	Username for backend authentication.	Yes
   GCOM API Key	Grafana.com API key with asserts:read scope (stored securely).	Yes

6. Click Save & test to verify the connection.

Query modes

The knowledge graph data source provides three query modes for selecting entities. Each mode offers different levels of control and flexibility for building queries.

Code mode is the default for new queries.

Code mode (Cypher)

Code mode lets you write Cypher graph queries directly using a Monaco-based editor. Use this mode for precise control over entity traversal, pattern matching, and relationship filtering.

Code mode supports the Entity Graph and Table output types.

The query editor includes the following features:

• Autocompletion: Schema-driven suggestions for entity types, relationship types, and property names. Property value suggestions are also available based on your data.
• Schema reference: A sidebar panel showing available entity types, their properties, and the relationships between them. Use this to explore the graph structure while building queries.
• Natural-language generation: An AI assistant that can generate Cypher queries from plain-language descriptions.

To write a Cypher query:

1. In the query editor, select Code as the query mode.

2. Write a Cypher query in the editor. For example, to find all services:

   cypher Copy

   MATCH (n:Service) RETURN n

3. Select Entity Graph or Table as the output type.

4. Run the query.

Only read operations are supported. Write operations such as CREATE, MERGE, or DELETE are rejected by the API.

Builder mode

Builder mode provides full control over entity selection with custom query criteria. Use this mode when you need dynamic filtering based on entity types, properties, and relationships.

To build a query:

1. In the query editor, select Builder as the query mode.

2. Select one or more entity types such as Service, Pod, Node, Database, or KubeCluster.

3. Add property matchers to filter entities:

   • Select a property name
   • Choose an operator: =, !=, >, <, >=, <=, contains, starts with, is null, or is not null
   • Enter a value for comparison

   Properties can be STRING or DOUBLE typed depending on the entity type.

4. Optionally, filter by connected entity types.

   Select entity types that must connect to your selected entities.

5. Optionally, filter by insights:

   • Check With own insights to show only entities with active insights
   • Check With propagated insights to include entities with insights from connected entities

6. Optionally, add scope criteria to narrow by environment, site, or namespace dimensions.

You can combine multiple filter criteria groups for complex queries.

From Labels mode

From Labels mode resolves entities from telemetry labels. This mode is available for annotation queries and enables cross-application integration by mapping telemetry labels to knowledge graph entities.

Use this mode when:

• Annotating dashboards with entity insights
• Correlating logs, traces, or profiles with entities
• Building integrations that reference entities by their telemetry labels

To use From Labels mode:

1. In the annotation query editor, select From Labels as the query mode.

2. Select the telemetry type: log, trace, profile, or metric.

3. Provide the telemetry labels for entity resolution.

The data source resolves entities using a three-strategy fallback chain:

1. Telemetry config reverse mapping - Checks user-configured label mappings
2. Entity type schema matching - Matches labels against entity type name/lookup patterns
3. Builtin label mappings - Uses predefined mappings for common label conventions

For metric telemetry, the data source uses a specialized resolution path through the alert-affected-entity endpoint.

Output types

The data source provides four output types that determine how query results are formatted.

Entity Graph

Returns data in node-graph visualization format showing entities and their relationships.

Each node includes:

• Entity name, type, and scope (environment/site/namespace)
• Health arcs showing proportions of success, errors, amendments, and warnings
• Icon and radius based on entity type
• Data links to entity detail drawer and RCA workbench

Edges represent relationships between entities such as CALLS, HOSTS, ROUTES, and GROUPS relationships with traffic metrics.

Use this output type for visualizing entity dependencies and health status in graph format.

Table

Returns tabular entity data with the following columns:

• id, name, type
• env, site, namespace
• severity, criticalCount, warningCount, infoCount, totalAssertions
• connectedEntities
• Dynamic property columns based on entity properties

Each row includes data links to entity graph views for further investigation.

Use this output type when you need structured entity data for analysis or reporting.

Insights / State Timeline

Returns state timeline visualization showing entity health over time.

The data source creates one DataFrame per entity with severity states over time intervals. Severity follows this hierarchy: amendment > critical > warning > null.

States are color-coded:

• Red: critical
• Yellow: warning
• Blue: amendment

Use this output type to track entity health changes and identify patterns over time.

Annotations

Returns annotation events from entity insights.

The data source processes assertion data and creates annotation intervals showing:

• Severity-based region coloring (critical = red, warning = yellow)
• Severity icon (warning triangle or info circle, color-coded)
• Insight name
• Clickable links to Entity Graph and RCA workbench

Use this output type to overlay entity insights on dashboard panels or time series visualizations.

Annotations

The knowledge graph data source supports the annotation system in Grafana with full annotation capabilities.

Configure annotations

To add knowledge graph annotations to a dashboard:

1. Open the dashboard settings.

2. Navigate to Annotations.

3. Click Add annotation query.

4. Select your knowledge graph data source.

5. Configure the annotation query:

   • Select a query mode (Builder or From Labels)
   • Add severity filters by checking: critical, warning, or info
   • Configure additional query criteria based on your selected mode

The data source automatically sets the query type to annotations.

Annotation processing

The data source processes annotations through these steps:

1. Queries the Knowledge Graph API for assertions matching your criteria
2. Walks the hierarchical assertion tree to extract only leaf-level assertions (avoiding duplicates)
3. Filters health states by requested severity levels
4. Creates one annotation frame per health state interval
5. Maps severity to Grafana alert states for region coloring
6. Adds interactive buttons linking to Entity Graph and RCA workbench

Each query returns a maximum of 7 annotations to avoid overwhelming the visualization.

Cross-application annotations

The From Labels mode enables other observability applications to add knowledge graph annotations without knowing specific entity details.

Applications pass their telemetry labels (from logs, traces, spans, or metrics), and the knowledge graph backend resolves the entity and returns its insights as annotations.

The data source supports labels from multiple sources:

Template variables

The knowledge graph data source supports four variable query types for dynamic dashboards.

Entity Types variable

Returns all available entity types from the knowledge graph.

Use this variable to create dropdowns that let users select entity types for filtering.

Scope Values variable

Returns values for a specific scope dimension: environment, site, or namespace.

Configure the variable with a scopeType parameter specifying which dimension to query.

Use this variable to filter entities by environment, deployment site, or Kubernetes namespace.

Search Definitions variable

Returns saved search definitions filtered by pattern and custom-only status.

Configure with optional parameters:

• searchPattern: Filter definitions by name pattern
• includeCustomOnly: Boolean to show only user-created definitions

Entity Names variable

Returns entity names for a given entity type.

Configure with required parameters:

• entityType: The entity type to query
• namePattern: Optional filter for entity names

All query parameters support template variable interpolation. Multi-value variables are automatically split by comma for use in filters and criteria.

Common workflows

This section describes common workflows for using the knowledge graph data source.

Visualize entity relationships

To create a node graph showing entity dependencies:

1. Add a panel to your dashboard.
2. Select the knowledge graph data source.
3. Choose a query mode to select entities (Code or Builder).
4. Select Entity Graph as the output type.
5. Configure the panel visualization to use node graph format.

The resulting visualization shows entities as nodes with health status arcs and their relationships as edges.

Create entity health dashboards

To display entity health metrics in a table:

1. Add a panel to your dashboard.
2. Select the knowledge graph data source.
3. Use Builder mode to filter entities by type and scope.
4. Select Table as the output type.
5. The table displays entities with their severity, assertion counts, and properties.

Use template variables to make the dashboard interactive, allowing users to filter by environment or entity type.

Track entity health over time

To monitor entity health state changes:

1. Add a panel to your dashboard.
2. Select the knowledge graph data source.
3. Use Builder mode to select the entities to monitor.
4. Select Insights / State Timeline as the output type.
5. Set an appropriate time range to show health transitions.

The state timeline shows when entities entered critical, warning, or amendment states.

Add entity annotations to metrics panels

To overlay entity insights on existing metrics:

1. Open your dashboard settings and navigate to Annotations.
2. Add an annotation query using the knowledge graph data source.
3. Use From Labels mode with telemetry labels from your metrics.
4. Select severity filters (critical, warning, info).
5. The data source maps your metrics labels to entities and displays their insights as annotations.

This workflow works with metrics from Prometheus, Loki, Tempo, or other telemetry sources.

Build dynamic dashboards with variables

To create dashboards that filter by environment or entity type:

1. Create template variables using the knowledge graph data source:
   • Entity Types variable for entity type selection
   • Scope Values variable for environment/site/namespace filtering
   • Entity Names variable for specific entity selection
2. Reference these variables in your panel queries using Builder mode filters.
3. Users can change variable values to dynamically filter entities across all panels.

API endpoints

The data source backend proxies requests to these Knowledge Graph API endpoints:

Troubleshooting

This section covers common issues when using the knowledge graph data source.

Connection fails during Save & test

If the data source connection test fails, verify the following:

• Backend URL: Ensure the Knowledge Graph API endpoint URL is correct and accessible from your Grafana instance.
• Basic Auth User: Verify the username matches your backend authentication configuration.
• GCOM API Key: Confirm the API key has the asserts:read scope and hasn’t expired. You can verify and regenerate API keys in your Grafana Cloud account.
• Network connectivity: Check that your Grafana instance can reach the backend URL. Verify firewall rules and network policies allow outbound connections.

No data returned from queries

If queries return no data:

• Time range: Verify the dashboard or panel time range includes periods when entities existed.
• Query filters: Check that your Builder mode filters match actual entities in your environment. For Code mode, verify that your Cypher query syntax is correct.
• Scope criteria: If using scope filters (env/site/namespace), confirm the values match your entity scopes.
• Entity types: Verify the selected entity types exist in your knowledge graph.

Annotations not appearing

If annotations don’t appear on your dashboard:

• Severity filters: Check that your annotation query includes the severity levels you want to display (critical, warning, info).
• Time range: Ensure the dashboard time range includes periods when insights were active.
• Query mode: Verify your query mode configuration correctly selects entities with insights.
• Annotation layer enabled: Confirm the annotation layer is enabled in your dashboard annotation settings.

Template variables not populating

If template variables show no options:

• Data source selection: Verify the correct knowledge graph data source is selected for the variable query.
• Query type: Confirm the variable query type matches what you want to retrieve (entity types, scope values, search definitions, or entity names).
• Required parameters: For entity names variables, ensure the entityType parameter is provided.
• Data source connectivity: Check that the data source can reach the backend API endpoints.