Grafana

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

The Grafana integration is only available to customers on select plans. 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.

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.

Create a Grafana service account and service account token

To create a Grafana service account, follow Grafana’s service account creation instructions. 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.

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 sidenav 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 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.
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 to filter the events sent to Grafana.

For more information about writing policies, read Using 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:

Example Grafana policy

    [
      {
        "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.

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 Launch

Darkly 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.

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:

| Tag

Description

| --- | | launchdarkly

| This 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_KEY

| The LaunchDarkly project key that is associated with the change event. | | environment_key:ENVIRONMENT_KEY

| The 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. |

9. Click Apply.