> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Grafana

> Connect Grafana to CloudThinker for dashboard integration, metric analysis, and unified observability

Connect your Grafana instance to enable CloudThinker agents to access dashboards, query metrics, and reference visualizations during analysis.

Grafana authenticates with a **service account token** scoped to the Viewer role.

***

## Supported platforms

| Platform               | Support      |
| ---------------------- | ------------ |
| **Grafana OSS**        | 9.x, 10.x    |
| **Grafana Enterprise** | All versions |
| **Grafana Cloud**      | All tiers    |

***

## Prerequisites

* A **Grafana instance** (OSS, Enterprise, or Cloud) reachable from CloudThinker.
* Admin access to create a service account under **Administration → Users and access → Service Accounts**.
* The Grafana instance URL.

***

## Setup

<Steps>
  <Step title="Open Grafana">
    Navigate to your Grafana instance and sign in with admin access.
  </Step>

  <Step title="Navigate to service accounts">
    Go to **Administration → Users and access → Service Accounts**.
  </Step>

  <Step title="Create service account">
    Click **Add service account** and enter:

    * **Name**: `cloudthinker-readonly`
    * **Role**: Select **Viewer**

    Click **Create** to create the service account.
  </Step>

  <Step title="Generate token">
    On the new service account page:

    1. Click **Add service account token**
    2. Enter a token name (e.g., `cloudthinker-token`)
    3. Optionally set an expiration date
    4. Click **Generate token**
    5. **Immediately copy the token** — it won't be shown again
  </Step>

  <Step title="Add connection in CloudThinker">
    Navigate to **Connections → Grafana** and enter:

    * **Grafana URL**: your instance URL (e.g., `https://grafana.your-domain.com`)
    * **Service Account Token**: the token you just copied

    Click **Connect**. CloudThinker verifies the credentials and shows a **Connected** status.
  </Step>
</Steps>

<Warning>
  Copy the service account token immediately after generation. Grafana will not show it again, and you'll need to create a new token if lost.
</Warning>

***

## Connection details

| Field                                | Description                         | Example                             |
| ------------------------------------ | ----------------------------------- | ----------------------------------- |
| **GRAFANA\_URL**                     | Your Grafana instance URL           | `https://your-instance.grafana.net` |
| **GRAFANA\_SERVICE\_ACCOUNT\_TOKEN** | The generated service account token | `glsa_xxxxx...`                     |

***

## Required permissions

| Role       | What it grants                                                                |
| ---------- | ----------------------------------------------------------------------------- |
| **Viewer** | View dashboards, query data sources, view annotations, access folder contents |
| **Editor** | Viewer permissions, plus create annotations and save dashboard snapshots      |

<Tip>
  Assign the **Viewer** role for read-only investigation. Only use Editor if you need annotation creation or dashboard snapshots.
</Tip>

***

## Agent capabilities

Once connected, agents can:

| Capability             | Description                               |
| ---------------------- | ----------------------------------------- |
| **Dashboard access**   | Reference existing dashboards in analysis |
| **Metric queries**     | Query data sources through Grafana        |
| **Annotation reading** | Access dashboard annotations for context  |
| **Alert status**       | Check Grafana alerting rules status       |

### Verify the connection

```text theme={null}
@alex check Grafana for active alert rules and summarize any that are firing
```

### Example prompts

```text theme={null}
@alex check the AWS cost dashboard for anomalies
@kai reference the Kubernetes cluster dashboard for pod health
@tony query database metrics from the Grafana data source
```

### Supported data sources

CloudThinker can query through Grafana's configured data sources:

| Data source   | Query support      |
| ------------- | ------------------ |
| Prometheus    | PromQL queries     |
| InfluxDB      | InfluxQL / Flux    |
| Elasticsearch | Lucene / KQL       |
| CloudWatch    | CloudWatch metrics |
| Loki          | LogQL queries      |

***

## Troubleshooting

<Accordion title="Connection failed">
  * Verify the Grafana URL is accessible from CloudThinker.
  * Check the SSL certificate is valid.
  * Ensure no proxy is blocking the connection.
  * Confirm Grafana is running and reachable.
</Accordion>

<Accordion title="Authentication failed">
  * Verify the service account token is correct.
  * Check the token has not expired.
  * Ensure the service account is active.
  * Confirm no IP restrictions are set on the account.
</Accordion>

<Accordion title="Token expired">
  * Navigate to **Administration → Service Accounts**.
  * Select the CloudThinker service account.
  * Generate a new token.
  * Update the token in CloudThinker connection settings.
</Accordion>

<Accordion title="Cannot access dashboards">
  * Verify the service account has the Viewer role.
  * Check folder permissions include the service account.
  * Ensure the dashboards are not in restricted folders.
</Accordion>

***

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Viewer role only** — never grant Editor or Admin roles to the CloudThinker service account
- **Token expiration** — set an expiration date and rotate the service account token every 90 days

***

## Related

<CardGroup cols={2}>
  <Card title="Elasticsearch Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/elasticsearch.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=c7389cfcd0bc8d303aeeb68bd19199ca" href="/guide/connections/elasticsearch" width="24" height="24" data-path="images/icons/elasticsearch.svg">
    Connect log data source
  </Card>

  <Card title="AWS Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/aws.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=45d526a3e9345214c0345f277da2e829" href="/guide/connections/aws" width="24" height="24" data-path="images/icons/aws.svg">
    Connect CloudWatch metrics
  </Card>
</CardGroup>