• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
No results for ""
EXPAND ALL

GIVE DOCS FEEDBACK

Grafana

Read time: 4 minutes
Last edited: Jan 19, 2024
The Grafana integration is a Pro and Enterprise feature

The Grafana integration is available to customers on a Pro or Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

Overview

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.

An example Grafana dashboard configured with LaunchDarkly feature flag change event annotations.
An example Grafana dashboard configured with LaunchDarkly feature flag change event annotations.

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 with the "Annotation writer" role and a corresponding service account token.

To create a Grafana service account and generate a service account token:

  1. In Grafana, open the the Administration menu and select "Service accounts." The "Service accounts" tab appears.
The "Service accounts" tab in Grafana.
The "Service accounts" tab in Grafana.
  1. Click Add service account. The "Create service account" page appears.
  2. Enter a Display name.
  3. Change the Role selection to "Annotation writer."
The "Create service account" page with the "Annotation writer" role selected.
The "Create service account" page with the "Annotation writer" role selected.
  1. Click Create. The "Service token" page appears.
  2. Click Add service account token.
An example "Service token" page with the mouse cursor hovering over the "Add service account token" button.
An example "Service token" page with the mouse cursor hovering over the "Add service account token" button.
  1. Enter a Display name for the token.
  2. Click Generate token.
  3. Copy the token and save if somewhere secure. Grafana displays this token only once, so you must copy and store it now. You will use it to set up the Grafana integration in LaunchDarkly.

Setting up the Grafana integration

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

  1. Navigate to the Integrations page and find "Grafana."
  2. Click Add integration. The "Create Grafana configuration" panel appears.
  3. (Optional) Give your integration a human-readable Name.
  4. Enter your Grafana instance URL. Do not include a trailing /.
  5. Enter the Grafana service account token. You created this token in the Prerequisites section.
  6. (Optional) Configure a custom policy to control which events LaunchDarkly sends to Grafana. To learn more, read Filtering the events you send to Grafana.
  7. After reading the Integration Terms and Conditions, check the I have read and agree to the Integration Terms and Conditions checkbox.
  8. 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.

Filtering 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 custom roles feature to filter the events sent to Grafana.

For more information about writing policies, read Policies in custom roles.

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:

[
{
"effect": "allow",
"actions": ["*"],
"resources": ["proj/*:env/your-test-environment:flag/*"]
}
]

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.
The configuration overflow menu with the "Edit integration configuration" option called out.
The configuration overflow menu with the "Edit integration configuration" option called out.
  1. In the "Policy" section, click Advanced editor. The Advanced editor appears.
  2. Enter your custom policy.
  3. Click Save configuration.

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

Adding 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."
The Grafana "Add annotation" page.
The Grafana "Add annotation" page.


  1. 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:
TagDescription
launchdarklyThis tag is added to all LaunchDarkly annotation events.
ld_tag:TAG

The LaunchDarkly tag associated with the resource that changed. For example, if a feature flag has the tag grafana in LaunchDarky, all event annotations associated with that flag will be sent to Grafana with the tag ld_tag:grafana.

project_key:PROJECT_KEYThe LaunchDarkly project key that is associated with the change event.
environment_key:ENVIRONMENT_KEYThe LaunchDarkly environment key that is associated with the change event.
flag_key:FLAG_KEY

The LaunchDarkly feature flag key that is associated with the change event. This tag is only applied to feature flag change events.

segment_key:SEGMENT_KEY

The LaunchDarkly segment flag key that is associated with the change event. This tag is only applied to segment change events.

kind:RESOURCE_KIND

The resource kind associated with the change event where RESOURCE_KIND is one of flag, segment, project, environment, or member.

  1. Click Apply.