Documentation Grafana documentation Data sources Parca Configure

Configure the Parca data source

This document explains how to install and configure the Parca data source in Grafana.

To use the Parca data source, you must build it from source and install it into your local Grafana plugin directory. After it’s installed, you can configure the data source using the Grafana UI, a YAML provisioning file, or Terraform. If you make any changes in the UI, select Save & test to preserve those changes.

Before you begin

Before you install the Parca data source, ensure you have:

• Grafana: A self-managed Grafana instance, version 12.3 or later. The Parca data source isn’t available in Grafana Cloud.
• Server access: Shell access to the host running Grafana, with permission to write to the plugin directory and restart Grafana.
• Grafana permissions: Organization administrator role to add and configure the data source.
• Parca instance: A running Parca instance (v0.19 or later) accessible from your Grafana server.
• Build tools: Node.js, npm, and Go. For the required versions, refer to the engines field in package.json and the go directive in go.mod in the data source repository.

Install the data source

The Parca data source has both a frontend and a Go backend, so you must build both and then copy the result into your Grafana plugin directory.

Build the data source from source

Clone the repository and build the frontend and backend:

sh Copy

git clone https://github.com/grafana/grafana-parca-datasource.git
cd grafana-parca-datasource
npm ci
npm run build
go run github.com/magefile/mage -v buildAll

Both build commands are required. npm run build produces the frontend assets, and the mage buildAll target compiles the backend executables for each supported platform. Running only npm run build produces a data source that Grafana loads but can’t query, because the backend executable is missing.

Both commands write their output to the dist/ directory.

Deploy the data source to Grafana

Copy the contents of dist/ into a parca directory inside your Grafana plugin directory. On a package-based Linux installation, the plugin directory is /var/lib/grafana/plugins:

sh Copy

sudo mkdir -p /var/lib/grafana/plugins/parca
sudo cp -a dist/. /var/lib/grafana/plugins/parca/
sudo chown -R grafana:grafana /var/lib/grafana/plugins/parca

The Grafana process must be able to read every file in the directory and execute the backend binary.

If you run Grafana in Docker, mount the dist/ directory at /var/lib/grafana/plugins/parca instead:

sh Copy

docker run -d \
  -v "$(pwd)/dist:/var/lib/grafana/plugins/parca" \
  -e GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS=parca \
  -p 3000:3000 \
  grafana/grafana:latest

The plugin directory path is set by the plugins configuration option. If you’ve changed it, use your configured path instead. For more information, refer to Configure Grafana.

Allow the unsigned plugin

A data source you build yourself isn’t signed, and Grafana refuses to load unsigned plugins by default. Add the parca plugin ID to the allow_loading_unsigned_plugins option in your Grafana configuration file, typically /etc/grafana/grafana.ini:

ini Copy

[plugins]
allow_loading_unsigned_plugins = parca

Restart Grafana to load the data source:

sh Copy

sudo systemctl restart grafana-server

When Grafana loads an unsigned plugin, it writes a warning to the server log:

text Copy

WARN[...] Permitting unsigned plugin. This is not recommended   pluginId=parca

For more information, refer to Plugin signatures and the allow_loading_unsigned_plugins option.

Verify the data source loaded

To confirm Grafana loaded the Parca data source:

1. Click Connections in the left-side menu.
2. Click Add new connection.
3. Type Parca in the search bar.

If Parca doesn’t appear, check the Grafana server log for plugin loading errors. Refer to Troubleshoot Parca data source issues.

Migrate from the bundled data source

Grafana 13.1 and earlier include a bundled Parca data source. Grafana 13.2 and later don’t, so you must install the external Parca data source, which you build from the grafana/grafana-parca-datasource repository. Both use the plugin ID parca, so your existing Parca data sources work with the external Parca data source without any changes.

The external Parca data source is available in Grafana 12.3 and later. If you already have Parca data sources configured, switch to the external Parca data source before you upgrade to Grafana 13.2:

1. Build, deploy, and allow the external Parca data source. Refer to Build the data source from source, Deploy the data source to Grafana, and Allow the unsigned plugin.

2. Add the following to your Grafana configuration file. Without this setting, Grafana 12.3 through 13.1 load the bundled Parca data source and ignore the external one.

   ini Copy

   [plugin.parca]
   as_external = true

3. Restart Grafana.

If you upgrade to Grafana 13.2 or later before you install the external Parca data source, your existing Parca data sources and any panels that query them report the parca plugin isn’t found. To resolve this, install the external Parca data source and restart Grafana. You don’t need to change your data sources.

Add the data source

After the data source is installed, add it in Grafana:

1. Click Connections in the left-side menu.
2. Click Add new connection.
3. Type Parca in the search bar.
4. Select Parca.
5. Click Add new data source.

Configure settings

The Settings tab contains the following configuration sections.

Basic settings

Connection

Authentication

Use this section to select an authentication method to access the data source. The available methods are:

TLS settings

Configure TLS for secure communication with your Parca instance.

Custom HTTP headers

Add custom HTTP headers to requests sent to the Parca instance. Click Add header to add a new row with Header (name) and Value (secret) fields.

Custom headers are useful for passing authentication tokens or routing information required by proxies between Grafana and Parca.

Additional settings

Click the down arrow to expand the Additional settings section. These settings are optional.

Advanced HTTP settings

Secure SOCKS proxy

Verify the connection

Click Save & test to verify that Grafana can connect to your Parca instance. The health check queries the available profile types from the Parca server. A successful connection displays the message

Data source is working.

If the test fails, verify that the URL is correct and that your Parca instance is running and accessible from the Grafana server. For more help, refer to Troubleshoot Parca data source issues.

Provision the data source

You can define the data source in YAML files as part of the Grafana provisioning system. For more information, refer to Provisioning Grafana.

Provisioning doesn’t install the data source. Install it first, as described in Install the data source, or Grafana fails to provision it because the parca plugin ID isn’t registered.

YAML provisioning example

Create a file such as /etc/grafana/provisioning/datasources/parca.yaml and restart Grafana:

YAML Copy

apiVersion: 1

datasources:
  - name: Parca
    type: parca
    uid: parca
    access: proxy
    url: http://localhost:7070

Set url to an address the Grafana server can reach. If Grafana and Parca run in separate containers, localhost resolves to the Grafana container, so use the Parca service name instead, for example http://parca:7070.

Set uid explicitly so dashboards can reference the data source by a stable UID. If you’re replacing an existing Parca data source, use its current UID.

To provision with basic authentication:

YAML Copy

apiVersion: 1

datasources:
  - name: Parca
    type: parca
    uid: parca
    access: proxy
    url: http://localhost:7070
    basicAuth: true
    basicAuthUser: <USERNAME>
    secureJsonData:
      basicAuthPassword: <PASSWORD>

Replace the following:

• <USERNAME>: Your Parca username.
• <PASSWORD>: Your Parca password.

Terraform example

To provision the data source with Terraform, use the grafana_data_source resource:

hcl Copy

resource "grafana_data_source" "parca" {
  type = "parca"
  name = "Parca"
  uid  = "parca"
  url  = "http://localhost:7070"
}

To provision with basic authentication:

hcl Copy

resource "grafana_data_source" "parca" {
  type                = "parca"
  name                = "Parca"
  uid                 = "parca"
  url                 = "http://localhost:7070"
  basic_auth_enabled  = true
  basic_auth_username = "<USERNAME>"

  secure_json_data_encoded = jsonencode({
    basicAuthPassword = "<PASSWORD>"
  })
}

Replace the following:

• <USERNAME>: Your Parca username.
• <PASSWORD>: Your Parca password.

Next steps

• Query profiling data with the Parca query editor