# Grafana

{% hint style="info" %}
Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.
{% endhint %}

[Grafana](https://grafana.com/) is an open-source observability platform that provides monitoring and visual analytics for application performance. Use Grafana to [visualize](https://grafana.com/docs/grafana/latest/panels-visualizations/visualizations/) your data, from bar charts and histograms to pie charts and geomaps.

Integrating Grafana with Cortex allows you to:

* [View Grafana charts on entity pages](#viewing-grafana-graphs-on-an-entity) in Cortex
* Create [Scorecards](#scorecards-and-cql) that include rules related to Grafana dashboards

## How to configure Grafana with Cortex

### Prerequisites

Before getting started:

* Your Grafana dashboard must have [`allow_embedding` enabled](https://grafana.com/docs/grafana/next/setup-grafana/configure-grafana/#allow_embedding).
* Your [Grafana dashboard must be public](https://grafana.com/docs/grafana/latest/dashboards/share-dashboards-panels/shared-dashboards/) OR if you are on a [Self-managed Cortex](/self-managed.md) instance, then Cortex and Grafana must be accessible within the same private network (such as a VPN).
  * You will need the public embed link provided in the iframe snippet.

### Embed the chart in an entity's YAML file

Define the public embed link in the [entity descriptor YAML](/ingesting-data-into-cortex/entities-overview/entities.md#defining-entities-via-yaml-file) for each entity where you want to embed a chart.

1. For the entity where you want to embed a chart, open its YAML file.
   * You can do this locally if following a [GitOps](/configure/gitops.md) approach, or you can edit a YAML file directly in the Cortex UI on the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details.md).
2. Add the `x-cortex-dashboards` block. Include the `type` (`grafana`) and the `url` (the public embed link you obtained from Grafana). See the example below:

```yaml
x-cortex-dashboards:
  embeds:
    - type: grafana
      url: https://snapshots.raintank.io/dashboard-solo/snapshot/y7zwi2bZ7FcoTlB93WN7yWO4aMiz3pZb?from=1493369923321&to=1493377123321&panelId=4&orgId=0
```

| Field  | Description                             | Required |
| ------ | --------------------------------------- | :------: |
| `type` | Type of embed (in this case, `grafana`) |   **✓**  |
| `url`  | Embed URL for the Grafana dashboard     |   **✓**  |

Repeat the steps above for each entity you want to add a Grafana chart to.

To modify the integration configuration, see [Modifying an existing integration configuration](/ingesting-data-into-cortex/integrations.md#modifying-an-existing-integration-configuration).

## Using the Grafana integration

### Viewing Grafana charts on an entity

Once you've defined the chart in an entity's YAML, you can view the graphs from an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details.md).

In an entity's sidebar, click **Dashboard**. All charts defined in the entity descriptor will be embedded on this page.

### Scorecards and CQL

With the Grafana integration, you can create Scorecard rules and write CQL queries based on Grafana charts.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

<details>

<summary>Embeds</summary>

Query against embeds associated with an entity.

**Definition:** `embeds()`

**Example**

If Grafana charts are a core part of operations at your organization, you can set a Scorecard rule to make sure entities have embedded charts.

```
embeds().any((embed) => embed.type == "GRAFANA")
```

</details>

### View integration logs <a href="#still-need-help" id="still-need-help"></a>

## Background sync

Grafana charts are updated in real time.

## FAQs and troubleshooting

**I've correctly added the embed URL, but the graph is showing an error or a blank screen.**

You may need to [enable embedding](https://grafana.com/docs/grafana/latest/administration/configuration/#allow_embedding) in your Grafana instance.

## Still need help?[​](https://docs.cortex.io/docs/reference/integrations/aws#still-need-help) <a href="#still-need-help" id="still-need-help"></a>

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: <help@cortex.io>, or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cortex.io/ingesting-data-into-cortex/integrations/grafana.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.