Documentation Plugins AWS Application Signals Configure

Configure the AWS Application Signals data source

This document explains how to configure the AWS Application Signals data source in Grafana, including authentication options, IAM permissions, cross-account observability, and provisioning with YAML or Terraform.

Before you begin

Before you configure the data source, ensure you have:

• Grafana permissions: The Organization Administrator role in your Grafana organization so you can add and edit data sources. For provisioning, you need access to the Grafana configuration directory on the host.
• AWS account: Access to an AWS account with AWS X-Ray and/or AWS Application Signals enabled.
• IAM credentials: An IAM identity (user or role) with read access to X-Ray and Application Signals. See IAM policy.
• Grafana version: Grafana 10.4.0 or later.

Key concepts

If you’re new to AWS X-Ray or Application Signals, these terms are used throughout the configuration:

Add the data source

To add the data source:

1. Click Connections in the left-side menu.
2. Click Add new connection.
3. Type AWS Application Signals in the search bar.
4. Select AWS Application Signals.
5. Click Add new data source in the upper right.

You’re taken to the Settings tab where you can configure the data source.

Configure settings

The following settings are available in the data source configuration page:

Choose an authentication method

The AWS Application Signals data source uses the shared Grafana AWS SDK authentication component, which supports the following methods. Choose the method that matches where Grafana is running and how you manage credentials.

After selecting an authentication method, fill in the following fields as needed:

Grafana Assume Role

Grafana Assume Role lets Grafana use its own IAM identity to assume a role you control in your AWS account, without sharing long-lived credentials.

To use Grafana Assume Role:

1. In your AWS account, create an IAM role with the IAM policy attached.
2. Add a trust policy to the role that allows Grafana’s IAM identity to assume it. Refer to the Grafana Assume Role documentation for the exact trust policy.
3. In the Grafana data source settings, select Grafana Assume Role as the authentication provider.
4. Enter the Assume Role ARN and, if used, the External ID.

Grafana automatically refreshes the temporary session credentials returned by sts:AssumeRole, so you don’t need to rotate them. This behavior requires plugin version 2.17.0 or later.

Credentials file

To authenticate with a credentials file, create a file at ~/.aws/credentials under the HOME path of the user running grafana-server:

ini Copy

[default]
aws_access_key_id = <ACCESS_KEY>
aws_secret_access_key = <SECRET_KEY>
region = us-east-1

In the data source settings, enter the profile name in the Credentials Profile Name field. Leave it blank to use the [default] profile.

AWS SDK Default

When the authentication method is AWS SDK Default, Grafana uses the standard AWS SDK credential provider chain. The SDK looks for credentials in this order:

1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and optionally AWS_SESSION_TOKEN).
2. Shared credentials file (~/.aws/credentials), using the profile named by AWS_PROFILE or the [default] profile.
3. Shared configuration file (~/.aws/config).
4. IAM role for an ECS task, if running as an ECS task.
5. IAM role for an EC2 instance, via instance metadata.

This method is the right choice when Grafana runs on AWS infrastructure that already provides credentials (EC2, ECS, EKS with IRSA, or Amazon Managed Grafana’s workspace IAM role) and when you don’t need to assume a role.

For more information, refer to Configuring the AWS SDK for Go in the AWS documentation.

IAM policy

The IAM identity Grafana uses must have permission to read X-Ray data, Application Signals resources, EC2 region metadata, and - for cross-account observability - OAM sinks and links.

The following policy grants the minimum permissions needed by the plugin:

JSON Copy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "XrayPermissions",
      "Effect": "Allow",
      "Action": [
        "xray:BatchGetTraces",
        "xray:GetTraceSummaries",
        "xray:GetTraceGraph",
        "xray:GetGroups",
        "xray:GetTimeSeriesServiceStatistics",
        "xray:GetInsightSummaries",
        "xray:GetInsight",
        "xray:GetServiceGraph"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ApplicationSignalsPermissions",
      "Effect": "Allow",
      "Action": [
        "application-signals:ListServices",
        "application-signals:ListServiceOperations",
        "application-signals:ListServiceDependencies",
        "application-signals:ListServiceLevelObjectives"
      ],
      "Resource": "*"
    },
    {
      "Sid": "EC2Regions",
      "Effect": "Allow",
      "Action": ["ec2:DescribeRegions"],
      "Resource": "*"
    },
    {
      "Sid": "CrossAccountObservability",
      "Effect": "Allow",
      "Action": [
        "oam:ListSinks",
        "oam:ListAttachedLinks"
      ],
      "Resource": "*"
    }
  ]
}

Cross-account observability

AWS Application Signals supports cross-account observability through CloudWatch cross-account observability, which uses OAM to connect a monitoring account to one or more source accounts.

To enable cross-account observability in Grafana:

1. In AWS, configure a CloudWatch cross-account observability sink in your monitoring account and links from the source accounts. Refer to the AWS cross-account observability documentation.
2. Attach the oam:ListSinks and oam:ListAttachedLinks permissions to the Grafana IAM identity. Refer to IAM policy.
3. Configure the Grafana data source in the monitoring account.

After configuration, Service Map queries and Service queries include an account-ID drop-down you can use to filter across accounts.

For more details about how cross-account filtering appears in the query editor, refer to Filter by account ID.

Private Data source Connect

This data source supports Private Data source Connect (PDC) on Grafana 10.0.0 and later. Use PDC to reach AWS endpoints that aren’t exposed to the public internet, such as VPC endpoints for X-Ray.

To enable PDC:

1. Set up a PDC agent in your private network. Refer to the PDC setup documentation.
2. In the data source settings, scroll to the Secure Socks Proxy section and select your PDC network.

Verify the connection

Click Save & test at the bottom of the configuration page. On success, Grafana displays the message Data source is working.

If the test fails, refer to Troubleshoot AWS Application Signals data source issues.

Provision the data source

You can define the AWS Application Signals data source in YAML as part of Grafana’s provisioning system. Provisioning lets you manage data source configuration in version control.

Access and secret key

YAML Copy

apiVersion: 1

datasources:
  - name: AWS Application Signals
    type: grafana-x-ray-datasource
    access: proxy
    jsonData:
      authType: keys
      defaultRegion: us-east-1
    secureJsonData:
      accessKey: <ACCESS_KEY>
      secretKey: <SECRET_KEY>

Credentials file

YAML Copy

apiVersion: 1

datasources:
  - name: AWS Application Signals
    type: grafana-x-ray-datasource
    access: proxy
    jsonData:
      authType: credentials
      defaultRegion: us-east-1
      profile: default

Default AWS SDK credential chain

Use this when Grafana runs on an EC2 instance or in another AWS environment that provides credentials automatically:

YAML Copy

apiVersion: 1

datasources:
  - name: AWS Application Signals
    type: grafana-x-ray-datasource
    access: proxy
    jsonData:
      authType: default
      defaultRegion: us-east-1

Grafana Assume Role

YAML Copy

apiVersion: 1

datasources:
  - name: AWS Application Signals
    type: grafana-x-ray-datasource
    access: proxy
    jsonData:
      authType: grafana_assume_role
      defaultRegion: us-east-1
      assumeRoleARN: <ROLE_ARN>
      externalId: <EXTERNAL_ID>

Custom endpoint

You can add a custom endpoint to any of the examples above, for example to use a VPC endpoint or AWS GovCloud:

YAML Copy

jsonData:
  authType: keys
  defaultRegion: us-gov-west-1
  endpoint: https://xray.us-gov-west-1.amazonaws.com

Configure with Terraform

You can configure the AWS Application Signals data source using the Grafana Terraform provider. This approach enables infrastructure-as-code workflows and version control for your Grafana configuration.

Terraform prerequisites

• Terraform installed.
• The Grafana Terraform provider configured with appropriate credentials.
• For Grafana Cloud: A Cloud Access Policy token with data source permissions.

Provider configuration

Configure the Grafana provider to connect to your Grafana instance:

hcl Copy

terraform {
  required_providers {
    grafana = {
      source  = "grafana/grafana"
      version = ">= 2.0.0"
    }
  }
}

provider "grafana" {
  url  = "<GRAFANA_URL>"
  auth = "<API_KEY_OR_SERVICE_ACCOUNT_TOKEN>"
}

Terraform examples

The following examples show how to configure the AWS Application Signals data source for each authentication method.

Access and secret key:

hcl Copy

resource "grafana_data_source" "application_signals" {
  type = "grafana-x-ray-datasource"
  name = "AWS Application Signals"

  json_data_encoded = jsonencode({
    authType      = "keys"
    defaultRegion = "us-east-1"
  })

  secure_json_data_encoded = jsonencode({
    accessKey = "<ACCESS_KEY>"
    secretKey = "<SECRET_KEY>"
  })
}

Default AWS SDK credential chain:

hcl Copy

resource "grafana_data_source" "application_signals" {
  type = "grafana-x-ray-datasource"
  name = "AWS Application Signals"

  json_data_encoded = jsonencode({
    authType      = "default"
    defaultRegion = "us-east-1"
  })
}

Grafana Assume Role with external ID:

hcl Copy

resource "grafana_data_source" "application_signals" {
  type = "grafana-x-ray-datasource"
  name = "AWS Application Signals"

  json_data_encoded = jsonencode({
    authType      = "grafana_assume_role"
    defaultRegion = "us-east-1"
    assumeRoleARN = "<ROLE_ARN>"
    externalId    = "<EXTERNAL_ID>"
  })
}

Custom endpoint:

Add endpoint to json_data_encoded for any of the preceding examples:

hcl Copy

resource "grafana_data_source" "application_signals" {
  type = "grafana-x-ray-datasource"
  name = "AWS Application Signals (GovCloud)"

  json_data_encoded = jsonencode({
    authType      = "keys"
    defaultRegion = "us-gov-west-1"
    endpoint      = "https://xray.us-gov-west-1.amazonaws.com"
  })

  secure_json_data_encoded = jsonencode({
    accessKey = "<ACCESS_KEY>"
    secretKey = "<SECRET_KEY>"
  })
}

For more information about the Grafana Terraform provider, refer to the provider documentation and the grafana_data_source resource.

Next steps

• Query AWS Application Signals
• Build alert rules
• Use template variables
• Troubleshoot issues