Parca data source on Grafana Labs

Configure the Parca data source

Wed, 22 Apr 2026 07:04:01 +0000

Configure the Parca data source

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

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 configuring the data source, ensure you have:

Grafana permissions: Organization administrator role.
Parca instance: A running Parca instance (v0.19 or later) accessible from your Grafana server.

If you’re provisioning the data source, you also need administrative rights on the server hosting your Grafana instance.

Add the data source

To add the Parca data source:

Click Connections in the left-side menu.
Click Add new connection.
Type Parca in the search bar.
Select Parca.
Click Add new data source.

Configure settings

The Settings tab contains the following configuration sections.

Basic settings

Setting	Description
Name	A name to identify this data source in panels, queries, and Explore.
Default	Toggle to make this the default data source for new panels.

Connection

Setting	Description
URL	The URL of your Parca instance. For example, `http://localhost:7070`. Grafana connects to Parca using gRPC-Web, so the URL should point to the Parca HTTP endpoint.

Authentication

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

Method	Description
Basic authentication	Authenticate with a username and password. Enter values in the User and Password fields.
Forward OAuth Identity	Forward the logged-in user’s OAuth token to the data source.
No Authentication	Connect without credentials. Use this when the Parca instance doesn’t require authentication.

TLS settings

Configure TLS for secure communication with your Parca instance.

Setting	Description
Add self-signed certificate	Toggle to provide a CA certificate. When enabled, paste the CA certificate in the CA Certificate field.
TLS Client Authentication	Toggle to enable mutual TLS. When enabled, provide the Server Name, Client Certificate, and Client Key.
Skip TLS certificate validation	Toggle to skip server certificate verification. Use only for testing.

Note
Use Transport Layer Security (TLS) for an additional layer of security when working with Parca.

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

Setting	Description
Allowed cookies	Cookies that should be forwarded to the data source. The Grafana proxy strips all cookies by default.
Timeout	The HTTP request timeout in seconds.

Secure SOCKS proxy

Note
This section is only visible when the Grafana server has the secure SOCKS proxy feature enabled.

Setting	Description
Enabled	Toggle to route requests to the Parca instance through a 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.

YAML provisioning example

apiVersion: 1

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

To provision with basic authentication:

apiVersion: 1

datasources:
  - name: Parca
    type: parca
    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:

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

To provision with basic authentication:

resource "grafana_data_source" "parca" {
  type                = "parca"
  name                = "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

Parca query editor

Wed, 22 Apr 2026 07:04:01 +0000

Parca query editor

This document explains how to use the Parca query editor to query and visualize continuous profiling data.

The query editor gives you access to a profile type selector, a label selector with autocomplete, and collapsible options for controlling query behavior.

Before you begin

Before using the query editor, ensure you have:

Configured the Parca data source.
Verified the connection using Save & test.

Access the query editor

To access the query editor:

Sign in to Grafana.
Select Explore from the left-side menu.
Select your Parca data source from the data source drop-down.

You can also access the query editor from a dashboard panel by selecting the Parca data source when editing a panel.

Profile type selector

Select a profile type from the cascading drop-down menu. Profile types are grouped by name at the first level, with a second level showing the sample type.

For example, a process_cpu profile might show sample types like cpu or samples.

You must select a profile type for the query to be valid. Grafana doesn’t return any data if the profile type isn’t selected when a query runs.

Profile type ID format

Each profile type has an ID in the format name:sampleType:sampleUnit:periodType:periodUnit. Delta profile types include an additional :delta suffix. You don’t need to construct these IDs manually – the cascading drop-down handles selection for you.

Examples of profile type IDs:

Profile type ID	Description
`process_cpu:samples:count:cpu:nanoseconds`	CPU profile measuring sample counts.
`memory:alloc_objects:count:space:bytes`	Memory profile measuring allocated objects.
`process_cpu:cpu:nanoseconds:cpu:nanoseconds:delta`	Delta CPU profile measuring nanoseconds.

Label selector

Use the label selector to filter profiles by labels. The editor provides autocomplete for both label names and label values.

Syntax

Parca uses a syntax similar to Prometheus for label filtering. Wrap label matchers in curly braces using the {key="value"} format.

The following operators are supported:

Operator	Description	Example
`=`	Equals	`{job="my-service"}`
`!=`	Not equals	`{job!="test-service"}`
`=~`	Regular expression match	`{job=~"prod-.*"}`
`!~`	Negative regular expression match	`{job!~"test-.*"}`

You can combine multiple label matchers separated by commas:

{job="my-service", instance=~"10.0.0.*"}

The label selector can be left empty to query all profiles of the selected type without filtering.

Refer to the Parca documentation for additional syntax details.

Autocomplete

The label selector provides autocomplete suggestions as you type. Autocomplete is triggered by the following characters: {, ,, [, (, =, ~, space, and ".

Label names: Suggested when you start typing inside curly braces or after a comma.
Label values: Suggested after typing a label name followed by = or =".

Keyboard shortcuts

Shortcut	Action
Shift + Enter	Run the query with current input.

Query types

Expand the Options section to select a query type. The query type controls what data is returned and how it’s visualized.

Query type	Description
Metric	Returns aggregated metric data visualized as a time series.
Profile	Returns a merged profile visualized as a flame graph.
Both	Returns both metric and profile data. Only available in Explore.

Note
The Both option is only available in Explore. In dashboard panels, you can select either Metric or Profile because panels support only one visualization type. If a query set to Both is moved from Explore to a dashboard, Grafana automatically changes it to Profile.

Use template variables in queries

The label selector field supports Grafana template variables. You can use variables like $job or $instance in the label selector to create dynamic, reusable dashboards.

For more information about supported variable types, examples, and limitations, refer to Parca template variables.

Query examples

The following examples show common profiling queries.

Query CPU profiles for a specific service

Select process_cpu > cpu from the profile type drop-down.
Enter a label selector to filter by service:
text
```
{job="my-service"}
```
Set query type to Profile to view a flame graph, or Metric to view CPU usage over time.

Compare profiles across instances

Select a profile type such as process_cpu > samples.
Filter to a specific service and instance:
text
```
{job="my-service", instance="10.0.0.1:7070"}
```
Add a second query (click + Add query) with a different instance:
text
```
{job="my-service", instance="10.0.0.2:7070"}
```
Set both queries to Metric to compare time-series data across instances.

Find memory allocation hot spots

Select memory > alloc_objects from the profile type drop-down.
Optionally filter by service:
text
```
{job="api-gateway"}
```
Set query type to Profile to view a flame graph showing which functions allocate the most objects.
Adjust the time range to narrow down to a specific incident window.

Profile query results

Profiles are visualized as a flame graph. Refer to the flame graph documentation to learn about the visualization and its features.

Parca returns profiles aggregated over the selected time range. The absolute values in the flame graph grow as the time range gets bigger while keeping the relative values meaningful. You can zoom in on the time range to get a higher granularity profile, down to the point of a single Parca scrape interval.

The flame graph displays the following columns:

Column	Description
level	The depth of the function in the call stack.
value	The cumulative value including child functions.
self	The value attributable to this function only.
label	The function name or symbol.

Units are automatically mapped from Parca to Grafana formats: nanoseconds displays as ns and count displays as a short number.

Metrics query results

Metrics results represent the aggregated value over time of the selected profile type.

Parca returns a separate time series for each label combination, allowing you to quickly identify spikes in the value of scraped profiles and zoom in to a particular time range for further investigation.

The time-series value field is named after the sample type from the profile type ID. For example, a query using process_cpu:samples:count:cpu:nanoseconds produces a value field named samples.

Parca template variables

Wed, 22 Apr 2026 07:04:01 +0000

Parca template variables

Instead of hard-coding label values in your profiling queries, you can use template variables to create dynamic, reusable dashboards. Variables appear as drop-down menus at the top of the dashboard, making it easy to switch between services, instances, or environments without editing queries.

For an introduction to template variables, refer to the Variables documentation.

Supported variable types

Variable type	Supported	Notes
Custom	Yes	Define a static list of values manually.
Text box	Yes	Enter a free-form value at the top of the dashboard.
Constant	Yes	Define a hidden, fixed value.
Data source	Yes	Select a data source instance by name.
Query	No	Parca doesn’t implement variable queries to dynamically populate drop-downs.

Note
Parca doesn’t support query-type variables. You can’t use the Parca data source to dynamically populate variable drop-downs. Use custom variables to define values manually, or use another data source to populate query variables.

Use variables in the label selector

The Parca query editor’s label selector field supports template variable interpolation. Use the standard $variablename or ${variablename} syntax. Variables are interpolated in the label selector only – the profile type drop-down doesn’t support them.

Variable syntax options

Syntax	Description
`$variablename`	Simple syntax for most cases.
`${variablename}`	Use when the variable is adjacent to other text (for example, `${host}_suffix`).
`${variablename:format}`	Apply a specific format to the variable value.

Example: Filter profiles by service

Create a custom variable to switch between services in your profiling dashboard.

Navigate to Dashboard settings > Variables.
Click Add variable.
Set Type to Custom.
Enter a Name, for example service.
In the Custom options field, enter comma-separated values, for example frontend, backend, api-gateway.
Click Apply.

In your Parca query’s label selector, reference the variable:

{job="$service"}

When you change the drop-down selection, the panel refreshes to show profiles for the selected service.

Example: Filter by service and instance

Create two custom variables to filter by multiple dimensions.

Create a variable named service with custom values frontend, backend, api-gateway.
Create a second variable named instance with custom values for your instance addresses, for example 10.0.0.1:7070, 10.0.0.2:7070, 10.0.0.3:7070.

In your Parca query’s label selector, reference both variables:

{job="$service", instance="$instance"}

Example: Use a text box variable for free-form filtering

Create a text box variable for free-form label filtering.

Navigate to Dashboard settings > Variables.
Click Add variable.
Set Type to Text box.
Enter a Name, for example label_filter.
Optionally set a default value, for example job="my-service".
Click Apply.

In your Parca query’s label selector, reference the variable:

{$label_filter}

This lets you type any label matcher directly into the variable input at the top of the dashboard without editing the panel query.

Limitations

Parca template variable support has the following limitations:

No query variable support: You can’t use Parca as a data source for populating variable options. Define values manually with custom variables or use another data source.
Label selector only: Variables are interpolated in the label selector field. The profile type drop-down doesn’t support variables.
No free-form filters: Parca doesn’t support free-form filters.

Next steps

Build queries using your template variables.
Troubleshoot issues if queries aren’t returning expected data.

Troubleshoot Parca data source issues

Wed, 22 Apr 2026 07:04:01 +0000

Troubleshoot Parca data source issues

This page provides solutions to common issues you might encounter when configuring or using the Parca data source. For configuration instructions, refer to Configure the Parca data source.

Connection errors

These errors occur when Grafana can’t reach the Parca instance.

“Save & test” fails

Symptoms:

Data source test times out or returns an error.
Unable to connect to the Parca server.

Possible causes and solutions:

Cause	Solution
Incorrect URL	Verify the URL points to your Parca HTTP endpoint (for example, `http://localhost:7070`). Grafana connects using gRPC-Web.
Parca isn’t running	Verify that your Parca instance is running and accessible from the Grafana server.
Firewall blocking	Check that firewall rules allow outbound traffic from Grafana to the Parca server on the configured port.
TLS misconfiguration	If using HTTPS, verify that TLS certificates are correctly configured on both Grafana and Parca.

When the connection succeeds, the health check displays “Data source is working”. The health check queries the available profile types from the Parca server, so any connectivity or authentication issue causes it to fail.

Connection refused or timeout errors

Symptoms:

Queries fail with network errors.
Intermittent connection issues.

Solutions:

Verify network connectivity from the Grafana server to the Parca endpoint.
Check that the Parca server is healthy and responding to requests.
For Grafana Cloud, configure Private data source connect if accessing a private Parca instance.

Query errors

These errors occur when running queries against the Parca data source.

“Invalid report type” or “try updating Parca to v0.19+”

Symptoms:

Queries fail with an error containing “invalid report type.”
The error message suggests updating Parca to v0.19+.
Flame graph data doesn’t load.

Solutions:

Upgrade your Parca server to v0.19 or later. This error occurs because older versions of Parca don’t support the flame graph Arrow format that Grafana requires.

`Unknown report type returned from query. update parca`

Symptoms:

Profile queries fail with this exact error message.
Metric queries may still succeed.

Solutions:

Upgrade your Parca server. This error occurs when the Parca server returns a response format that Grafana doesn’t recognize. Updating to the latest Parca version resolves the issue.

“No data” or empty results

Symptoms:

Query runs without error but returns no data.
Flame graph or metrics panel shows “No data.”

Possible causes and solutions:

Cause	Solution
No profile type selected	Select a profile type from the drop-down menu. This field is required – queries silently return empty data without it.
Time range doesn’t contain data	Expand the dashboard time range or verify that profiling data exists for the selected period.
Label selector too restrictive	Remove or broaden label filters to verify that matching profiles exist.
Label selector syntax error	Verify the label selector uses valid syntax (for example, `{job="my-service"}`). Refer to the query editor documentation for supported operators.
Parca isn’t scraping targets	Check your Parca configuration to verify that targets are being scraped and profiles collected.

Query editor issues

These issues relate to the query editor interface.

Profile type drop-down is empty

Symptoms:

The profile type selector shows no options.
The button text reads Select a profile type with nothing to choose.

Possible causes and solutions:

Cause	Solution
Connection to Parca failed	Verify the data source connection using Save & test in the data source settings.
Parca has no scraped data	Verify that Parca is scraping targets and has collected profile data.
Network or auth error	Check the browser developer console for failed requests to the `profileTypes` resource endpoint.

“Both” query type is missing

Symptoms:

Only Metric and Profile appear in the query type options.
The Both option isn’t available.

Solution:

This is expected behavior. The Both query type is only available in Explore. Dashboard panels support only one visualization type, so Grafana limits the options to Metric or Profile. If a query set to Both in Explore is used in a dashboard, Grafana automatically changes it to Profile.

Autocomplete suggestions don’t appear

Symptoms:

No label name or value suggestions appear when typing in the label selector.
Autocomplete works for some labels but not others.

Possible causes and solutions:

Cause	Solution
Label names haven’t loaded	Wait a moment after opening the query editor. Autocomplete loads label names from Parca on initialization.
Connection to Parca failed	Verify the data source connection. Autocomplete queries the `labelNames` and `labelValues` resource endpoints.
Cursor position not recognized	Place your cursor inside curly braces `{}` and after an `=` sign for value suggestions. Autocomplete triggers on specific characters: `{`, `,`, `=`, `~`, `"`, space.

Template variable issues

These issues relate to using template variables with the Parca data source.

Variables don’t resolve in queries

Symptoms:

Variable syntax like $variable appears literally in query results instead of being replaced.
Queries return no data when using variables.

Possible causes and solutions:

Cause	Solution
Variable used in profile type	Template variables are only supported in the label selector field. The profile type drop-down doesn’t support variable interpolation.
Variable not defined	Verify the variable exists in Dashboard settings > Variables and has valid values.
Wrong variable syntax	Use `$variablename` or `${variablename}`. Verify there are no typos in the variable name.

Can’t use Parca to populate variable options

Symptoms:

When creating a query-type variable with the Parca data source, no values are returned.

Solution:

Parca doesn’t support query-type variables. You can’t use the Parca data source to dynamically populate variable drop-downs. Use Custom variables with manually defined values, Text box variables for free-form input, or a different data source for query-type variables. Refer to Parca template variables for supported variable types and examples.

Enable debug logging

To capture detailed error information for troubleshooting:

Set the Grafana log level to debug in the configuration file:
ini
```
[log]
level = debug
```
Review logs in /var/log/grafana/grafana.log (or your configured log location).
Look for Parca-specific entries that include request and response details. Common log messages include:
- "Failed to get profile types" – profile type loading failed.
- "Failed to get label names" – label autocomplete data failed to load.
- "Failed to process query" – a query to Parca returned an error.
- "Failed to unmarshall query" – the query JSON couldn’t be parsed.
Reset the log level to info after troubleshooting to avoid excessive log volume.

Get additional help

If you’ve tried the solutions on this page and still encounter issues:

Check the Grafana community forums for similar issues.
Review the Grafana GitHub issues for known bugs related to the Parca data source.
Consult the Parca documentation for service-specific guidance.
Contact Grafana Support if you’re an Enterprise, Cloud Pro, or Cloud Contracted user.
When reporting issues, include:
- Grafana version
- Parca server version
- Error messages (redact sensitive information)
- Steps to reproduce
- Relevant configuration (redact credentials)