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

# Grafana

<View title="Developer" />

<View title="Federal docs" />

<View title="EU docs" />

<Note>
  **The Grafana integration is available to customers on select plans**

  The Grafana integration is only available to customers on select plans. To learn more, [read about our pricing](https://launchdarkly.com/pricing/). To upgrade your plan, [contact Sales](https://launchdarkly.com/contact-sales/).
</Note>

This topic explains how to use the LaunchDarkly Grafana integration. You can use the integration to send flag, environment, and project updates to Grafana as annotations to add context to your graphs.

<Frame caption="An example Grafana dashboard configured with LaunchDarkly feature flag change event annotations.">
  <img src="https://mintcdn.com/launchdarkly/unfRSXbmQkdGxJjN/images/__third_party/grafana-dashboard-with-annotations.png?fit=max&auto=format&n=unfRSXbmQkdGxJjN&q=85&s=574fcd92b16af14066fa5c4ea9cf19b4" alt="An example Grafana dashboard configured with LaunchDarkly feature flag change event annotations." width="878" height="574" data-path="images/__third_party/grafana-dashboard-with-annotations.png" />
</Frame>

## Prerequisites

To use the Grafana integration, you must have the following prerequisites:

* A Grafana instance that is accessible to LaunchDarkly's servers.
* A Grafana [service account](https://grafana.com/docs/grafana/latest/administration/service-accounts/#service-accounts) with the "Annotation writer" role and a corresponding service account token.

### Create a Grafana service account and service account token

To create a Grafana service account, follow [Grafana's service account creation instructions](https://grafana.com/docs/grafana/latest/administration/service-accounts/#to-create-a-service-account). Change the **Role** selection to "Annotation writer."

For the display name, we recommend "LaunchDarkly integration" or similar.

Next, generate a service account token for the service account you just created following [Grafana's service account token instructions](https://grafana.com/docs/grafana/latest/administration/service-accounts/#add-a-token-to-a-service-account-in-grafana).

## Set up the Grafana integration

After you create a service account token in Grafana, you can set up the integration in LaunchDarkly.

1. Click the **gear** icon in the left sidebar to view Organization settings.
2. Click **Integrations** and find "Grafana."
3. Click **Add integration**. The "Create Grafana configuration" panel appears.
4. (Optional) Give your integration a human-readable **Name**.
5. Enter your Grafana instance URL. Do not include a trailing `/`.
6. Enter the Grafana **service account token**. You created this token in the [Prerequisites](#prerequisites) section.
7. (Optional) Configure a custom policy to control which events LaunchDarkly sends to Grafana. To learn more, read [Filter the events you send to Grafana](#filter-the-events-you-send-to-grafana).
8. After reading the Integration Terms and Conditions, check the **I have read and agree to the Integration Terms and Conditions** checkbox.
9. Click **Save configuration**. The new integration appears on the **Integrations** page. It is switched **On** by default.

After you set up the Grafana integration, events from LaunchDarkly appear in your Grafana dashboard.

## Filter the events you send to Grafana

By default, LaunchDarkly sends events to Grafana for changes made to any feature flag, environment, or project. If you have a more limited use case for using the integration, or you wish to restrict which data you send to Grafana, you can filter which events LaunchDarkly sends.

To filter events, write a policy using the same syntax as the [role policy builder](/docs/home/account/roles/role-create#create-policies-for-roles) to filter the events sent to Grafana.

For more information about writing policies, read [Using policies](/docs/home/account/roles/role-policies).

For example, if you only want to receive an event when a change is made to one of the feature flags in your testing environment, you can add the following policy to your events stream:

<CodeGroup>
  ```json title="Example Grafana policy" lines wrap theme={null}
  [
    {
      "effect": "allow",
      "actions": ["*"],
      "resources": ["proj/*:env/your-test-environment:flag/*"]
    }
  ]
  ```
</CodeGroup>

To add a custom filter:

1. Navigate to the **Integrations** page and find "Grafana."
2. Click the **overflow menu** next to the configuration you wish to modify, and select "Edit integration configuration." The "Edit Grafana configuration" panel appears.

<Frame caption="The configuration overflow menu with the &#x22;Edit integration configuration&#x22; option called out.">
  <img src="https://mintcdn.com/launchdarkly/A4UXoRTW8ATNw4yq/images/auto/manage-integrations-edit-integration-callout.auto.png?fit=max&auto=format&n=A4UXoRTW8ATNw4yq&q=85&s=ec84cd9dbabfe504e718626dec9fb47b" alt="The configuration overflow menu with the &#x22;Edit integration configuration&#x22; option called out." width="2640" height="374" data-path="images/auto/manage-integrations-edit-integration-callout.auto.png" />
</Frame>

3. In the "Policy" section, click **Advanced editor**. The Advanced editor appears.
4. Enter your custom **policy**.
5. Click **Save configuration**.

You can verify that LaunchDarkly is sending a customized set of events by viewing the events in your Grafana dashboard.

## Add LaunchDarkly annotations to Grafana dashboards

To add LaunchDarkly events as annotations in Grafana dashboards:

1. Open the Grafana dashboard in edit mode.
2. Click the Dashboard settings **gear** icon button located at the top of the page.
3. Click **Annotations**.
4. Click **New query**. The "New annotation" page appears.
5. Enter a human readable name for the annotation, such as "LaunchDarkly feature flags."
6. In the **Data source** menu, select "-- Grafana --."
7. In the **Filter by** menu, select **Tags**.

<Frame caption="The Grafana &#x22;Add annotation&#x22; page.">
  <img src="https://mintcdn.com/launchdarkly/unfRSXbmQkdGxJjN/images/__third_party/grafana-add-annotation.png?fit=max&auto=format&n=unfRSXbmQkdGxJjN&q=85&s=3ca6c7748e0fba4f88604c769ccaedd1" alt="The Grafana &#x22;Add annotation&#x22; page." width="645" height="1002" data-path="images/__third_party/grafana-add-annotation.png" />
</Frame>

8. The LaunchDarkly integration sends annotation events to Grafana with event-specific tags. You can use one or more of the following tags to filter the annotations that appear on your dashboard:

<table>
  <thead>
    <tr>
      <th>Tag</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>launchdarkly</code></td>
      <td>This tag is added to all LaunchDarkly annotation events.</td>
    </tr>

    <tr>
      <td><code>ld\_tag:TAG</code></td>

      <td>
        The LaunchDarkly tag associated with the resource that changed. For example, if a feature flag has the tag
        <code>grafana</code> in LaunchDarky, all event annotations associated with that flag will be sent to Grafana with the tag
        <code>ld\_tag:grafana</code>.
      </td>
    </tr>

    <tr>
      <td><code>project\_key:PROJECT\_KEY</code></td>
      <td>The LaunchDarkly project key that is associated with the change event.</td>
    </tr>

    <tr>
      <td><code>environment\_key:ENVIRONMENT\_KEY</code></td>
      <td>The LaunchDarkly environment key that is associated with the change event.</td>
    </tr>

    <tr>
      <td><code>flag\_key:FLAG\_KEY</code></td>

      <td>
        The LaunchDarkly feature flag key that is associated with the change event. This tag is only applied to feature
        flag change events.
      </td>
    </tr>

    <tr>
      <td><code>segment\_key:SEGMENT\_KEY</code></td>

      <td>
        The LaunchDarkly segment flag key that is associated with the change event. This tag is only applied to segment
        change events.
      </td>
    </tr>

    <tr>
      <td><code>kind:RESOURCE\_KIND</code></td>

      <td>
        The resource kind associated with the change event where <code>RESOURCE\_KIND</code> is one of <code>flag</code>, <code>segment</code>, <code>project</code>,
        <code>environment</code>, or <code>member</code>.
      </td>
    </tr>
  </tbody>
</table>

9. Click **Apply**.