Pyroscope on Grafana Labs

Configure the Grafana Pyroscope data source

Tue, 14 Apr 2026 09:48:24 +0000

Configure the Grafana Pyroscope data source

The Pyroscope data source sets how Grafana connects to your Pyroscope database.

You can configure the data source using either the data source interface in Grafana or using a configuration file. This page explains how to set up and enable the data source capabilities using Grafana.

If you make any changes, select Save & test to preserve those changes.

If you’re using your own installation of Grafana, you can provision the Pyroscope data source using a YAML configuration file. For more information about provisioning and available configuration options, refer to Provisioning Grafana.

Before you begin

To configure a Pyroscope data source, you need administrator rights to your Grafana instance and a Pyroscope instance configured to send data to Grafana.

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

Add or modify a data source

You can use these procedures to configure a new Pyroscope data source or to edit an existing one.

Create a new data source

To configure basic settings for the data source, complete the following steps:

Select Connections in the main menu.
Enter Grafana Pyroscope in the search bar.
Select Grafana Pyroscope.
Select Add new data source in the top-right corner of the page.
On the Settings tab, complete the Name, Connection, and Authentication sections.

Use the Name field to specify the name used for the data source in panels, queries, and Explore. Toggle the Default switch for the data source to be pre-selected for new panels.
Under Connection, enter the URL of the Pyroscope instance. For example, https://example.com:4100. Refer to Connection URL for more information.
Complete the Authentication section.

Optional: Use Additional settings to configure other options.
Select Save & test.

Update an existing data source

To modify an existing Pyroscope data source:

Select Connections in the main menu.
Select Data sources to view a list of configured data sources.
Select the Pyroscope data source you wish to modify.
Optional: Use Additional settings to configure or modify other options.
After completing your updates, select Save & test.

Connection URL

The data source connection URL should point to a location of a running Pyroscope backend.

Grafana Cloud Profiles

Your Grafana Cloud instance automatically includes a fully provisioned data source.

If you are running a self-managed Grafana instance or need to configure an additional Pyroscope data source pointing to Grafana Cloud Profiles, you can find the Pyroscope URL under the Manage your stack section for your organization.

Self-managed Pyroscope backend

The connection URL for a self-managed Pyroscope backend depends on how Pyroscope is deployed. Refer to the steps under Query profiles in Grafana for more information on how to configure the data source.

If you plan to use the Profiles Drilldown application and you are running a self-managed Pyroscope backend in microservices mode, the data source connection URL should point to a gateway or proxy that routes requests to the corresponding Pyroscope service. Refer to the Helm ingress configuration for specific routing requirements.

Authentication

Use this section to select an authentication method to access the data source.

Note
Use Transport Layer Security (TLS) for an additional layer of security when working with Pyroscope. For additional information on setting up TLS encryption with Pyroscope, refer to Pyroscope configuration.

To set up authentication:

Select an authentication method from the drop-down list:
- Basic authentication: Authenticates your data source using a username and password
- Forward OAuth identity: Forwards the OAuth access token and the OIDC ID token, if available, of the user querying to the data source
- No authentication: No authentication is required to access the data source
For Basic authentication only: Enter the User and Password.
Optional: Complete the TLS settings for additional security methods.

TLS Client Authentication

Toggle on to use client authentication. When enabled, it adds the Server name, Client cert, and Client key fields. The client provides a certificate that is validated by the server to establish the client’s trusted identity. The client key encrypts the data between client and server. These details are encrypted and stored in the Grafana database.

Add self-signed certificate

Activate this option to use a self-signed TLS certificate. You can add your own Certificate Authority (CA) certificate on top of one generated by the certificate authorities for additional security measure.

Skip TLS certification validation

When activated, it bypasses TLS certificate verification. Not recommended, unless absolutely necessary for testing.
Optional: Add HTTP Headers. You can pass along additional context and metadata data about the request and response. Select Add header to add Header and Value fields.
Select Save & test to preserve your changes.

Additional settings

Use the down arrow to expand the Additional settings section to view these options.

Advanced HTTP settings

The Grafana Proxy deletes forwarded cookies. Use the Allowed cookies field to specify cookies that should be forwarded to the data source by name.

The Timeout field sets the HTTP request timeout in seconds.

Querying

Minimum step is used for queries returning time-series data. The default value is 15 seconds.

Adjusting this option can help prevent gaps when you zoom in to profiling data.

Private data source connect

Note
This feature is only available in Grafana Cloud.

Use private data source connect (PDC) to connect to and query data within a secure network without opening that network to inbound traffic from Grafana Cloud.

Refer to Private data source connect for more information on how PDC works and Configure Grafana private data source connect (PDC) for steps on setting up a PDC connection.

Use the drop-down list to select a configured private data source. If you make changes, select Test & save to preserve your changes.

Use Manage private data source connect to configure and manage any private data sources you have configured.

How profiling and tracing work together

Tue, 14 Apr 2026 09:48:24 +0000

How profiling and tracing work together

Profiles, continuous profiling, and distributed traces are all tools that can be used to improve the performance and reliability of applications. However, each tool has its own strengths and weaknesses, and it is important to choose the right tool for the job as well as understand when to use both.

Profiling

Profiling offers a deep-dive into an application’s performance at the code level, highlighting resource usage and performance hotspots.

Usage	During development, major releases, or upon noticing performance quirks.
Benefits	Business: Boosts user experience through enhanced application performance. Technical: Gives clear insights into code performance and areas of refinement.
Example	A developer uses profiling upon noting slow app performance, identifies a CPU-heavy function, and optimizes it.

Continuous profiling

Continuous profiling provides ongoing performance insights, capturing long-term trends and intermittent issues.

Usage	Mainly in production, especially for high-priority applications.
Benefits	Business: Preemptively addresses inefficiencies, potentially saving costs. Technical: Highlights performance trends and issues like potential memory leaks over time.
Example	A month-long data from continuous profiling suggests increasing memory consumption, hinting at a memory leak.

Distributed tracing

Traces requests as they cross multiple services, revealing interactions and service dependencies.

Usage	Essential for systems like microservices where requests touch multiple services.
Benefits	Business: Faster issue resolution, reduced downtimes, and strengthened customer trust. Technical: A broad view of the system's structure, revealing bottlenecks and inter-service dependencies.
Example	In e-commerce, a user's checkout request might involve various services. Tracing depicts this route, pinpointing where time is most spent.

Combined power of tracing and profiling

When used together, tracing and profiling provide a powerful tool for understanding system and application performance.

Usage	For comprehensive system-to-code insights, especially when diagnosing complex issues spread across services and codebases.
Benefits	Business: Reduces downtime, optimizes user experience, and safeguards revenues. Technical: Holistic view: Tracing pinpoints bottle-necked services, while profiling delves into the responsible code segments. End-to-end insight: Visualizes a request's full journey and the performance of individual code parts. Efficient diagnosis: Tracing identifies service latency; profiling zeroes in on its cause, be it database queries, API calls, or specific code inefficiencies.
Example	Tracing reveals latency in a payment service. Combined with profiling, it's found that a particular function, making third-party validation calls, is the culprit. This insight guides optimization, refining system efficiency.

Configure traces to profiles

Tue, 14 Apr 2026 09:48:24 +0000

Configure Trace to profiles

Trace to profiles lets you navigate from a trace span directly to the profiling data for that span. You configure the integration in the Tempo data source, which connects your tracing data in Tempo with your profiling data in Pyroscope.

Note
Your application must be instrumented for profiles and traces. For more information, refer to Link traces to profiles.

Using Trace to profiles, you can use the ability to correlate different signals in Grafana by adding the functionality to link between traces and profiles.

Trace to profiles lets you link your Grafana Pyroscope data source to tracing data. When configured, this connection lets you run queries from a trace span into the profile data using Explore. Each span links to your queries. Clicking a link runs the query in a split panel. If tags are configured, Grafana dynamically inserts the span attribute values into the query. The query runs over the time range of the (span start time - 60) to (span end time + 60 seconds).

Embedded flame graphs are also inserted into each span details section that has a linked profile. This lets you see resource consumption in a flame graph visualization for each span without having to navigate away from the current view.

There are two ways to configure the trace to profiles feature:

Use a basic configuration with default query, or
Configure a custom query where you can use a template language to interpolate variables from the trace or span.

Before you begin

To use Trace to profiles, you need:

A Grafana Pyroscope data source connected to your Pyroscope instance.
A Tempo data source configured with the Trace to profiles settings described on this page.
Your application instrumented with all three of the following:
1. Profiling: A Pyroscope SDK or Grafana Alloy sending profiling data to Pyroscope. Refer to Configure the client to send profiles for setup instructions.
2. Tracing: An OpenTelemetry SDK sending trace data to Tempo. Refer to the OpenTelemetry getting started documentation for setup instructions.
3. Span profiling bridge: A language-specific OpenTelemetry integration package that links profiling data with trace spans. Without this package, traces and profiles are independent signals with no connection between them. Refer to Link tracing and profiling with span profiles for per-language setup instructions.

Use a basic configuration

To use a basic configuration, follow these steps:

In the left menu, select Connections > Data sources.
Select your configured Tempo data source from the Data source list.
Scroll down to the Traces to profiles section.
Select a Pyroscope data source in the Data source drop-down.
Optional: Add one or more tags to use in the query. If left blank, the default values of service.name and service.namespace are used.

The tags you configure must be present in the spans attributes or resources for a trace-to-profiles span link to appear.

You can optionally configure a new name for the tag. This is useful if the tag has dots in the name and the target data source doesn’t allow dots in labels. In that case, you can remap service.name to service_name.
Select one or more profile types to use in the query. Select the drop-down and choose options from the menu.

The profile type or app must be selected for the query to be valid. Grafana doesn’t show any data if the profile type or app isn’t selected when a query runs.
Select Save and Test.

If you have configured a Pyroscope data source and no profile data is available or the Profiles for this span button and the embedded flame graph isn’t visible, verify that the pyroscope.profile.id key-value pair exists in your span tags.

Configure a custom query

To use a custom query with the configuration, follow these steps:

In the left menu, select Connections > Data sources.
Select a configured Tempo data source from the Data source list.
Scroll down to the Traces to profiles section.
Select a Pyroscope data source in the Data source drop-down.
Optional: Choose any tags to use in the query. If left blank, the default values of service.name and service.namespace are used.

These tags can be used in the custom query with ${__tags} variable. This variable interpolates the mapped tags as list in an appropriate syntax for the data source. Only tags present in the span are included. Tags that aren’t present are omitted.

You can also configure a name for the tag. Tag names are useful where the tag has dots in the name and the target data source doesn’t allow using dots in labels. For example, you can remap service.name to service_name. If you don’t map any tags here, you can still use any tag in the query, for example: method="${__span.tags.method}". Learn more about custom query variables.
Select one or more profile types to use in the query. Select the drop-down and choose options from the menu.
Switch on Use custom query to enter a custom query.
Specify a custom query to be used to query profile data. You can use various variables to make that query relevant for current span. The link shows only if all the variables are interpolated with non-empty values to prevent creating an invalid query. You can interpolate the configured tags using the $__tags keyword.
Select Save and Test.

Configuration options

The following table describes options for configuring your Trace to profiles settings:

Setting name	Description
Data source	Defines the target data source. You can select a Pyroscope [profiling] data source.
Tags	Defines the tags to use in the profile query. Default: `cluster`, `hostname`, `namespace`, `pod`, `service.name`, `service.namespace`. You can change the tag name for example to remove dots from the name if they’re not allowed in the target data source. For example, map `http.status` to `http_status`.
Profile type	Defines the profile type to use in the query.
Use custom query	Toggles use of custom query with interpolation.
Query	Input to write custom query. Use variable interpolation to customize it with variables from span.

Verify the integration

After you configure the Tempo data source and instrument your application, verify that the integration works.

Open a trace in Explore using your Tempo data source.
Expand a span to view its details.
Confirm that the Profiles for this span button appears in the span details.
Confirm that an embedded flame graph appears in the span details section.

If the span attribute pyroscope.profile.id isn’t present on the span, the OpenTelemetry bridge package isn’t configured correctly. Refer to Link tracing and profiling with span profiles for per-language setup instructions.

Troubleshoot trace to profiles

Use the following checklist to diagnose common issues with the Trace to profiles integration.

No “Profiles for this span” button appears

Verify that you installed and configured the OTel bridge package for your language. This is a separate package from the Pyroscope SDK and OpenTelemetry SDK. Refer to Link tracing and profiling with span profiles for per-language instructions.
Check that the pyroscope.profile.id attribute exists on the span in Tempo. If it’s missing, the bridge package isn’t tagging spans correctly.
Check that the span_name label exists on the profiling data in Pyroscope. If it’s missing, the bridge package isn’t labeling profiling samples correctly.
Verify that the tags you configured in the Tempo data source are present in the span’s attributes or resources. If the tags don’t match, the span link doesn’t appear.

Button appears but no profile data is shown

The span might be shorter than the sampling interval of the profiler. Span profiling is most effective on spans longer than 20ms.
CPU profiling only captures time spent actively executing on the CPU. If the span is mostly waiting on I/O, network calls, or database queries, the CPU profile for that span may be sparse or empty.
Verify that the profile type selected in the Tempo data source configuration matches the profile type your application sends.

Tags don’t match

Tags you configure in the Tempo data source must be present in the span’s attributes or resources. If a tag has dots in its name, for example, service.name, and the Pyroscope data source doesn’t allow dots in labels, remap it to a name without dots, for example, service_name.

Query profile data

Tue, 14 Apr 2026 09:48:24 +0000

Query profile data

You can query your profile data using the open source Grafana Profiles Drilldown app or the built-in Grafana Pyroscope data source query editor.

Profiles Drilldown provides a queryless experience for inspecting your profiling data with opinionated workflows to assist your investigation.
Data source query editor provides complete control over your data exploration and is recommended for experienced users.

In addition, you can embed flame graph panels in Grafana dashboards. Refer to the Flame graph panel documentation for details.

Profiles Drilldown

Grafana Profiles Drilldown is a native Grafana application designed to integrate seamlessly with Pyroscope, the open source continuous profiling platform, providing a smooth, queryless experience for browsing and analyzing profiling data.

You can use Profiles Drilldown in Grafana Cloud or in your own Grafana instance. For more information, refer to Access or install Profiles Drilldown.

Use cases

There are several different modes for viewing, analyzing, and comparing profiling data.

The main use cases are the following:

Proactive: Cutting costs, addressing latency issues, or optimizing memory usage for applications
Reactive: Resolving incidents with line-level accuracy or debugging active latency/memory issues

Profiles Drilldown provides an intuitive interface to specifically support proactivee and reactive use cases. You get a holistic view of all of your services and how they’re functioning, but also the ability to drill down for more targeted root cause analysis.

Profiles Drilldown offers a convenient platform to analyze profiles and get insights that are impossible to get from using other traditional signals like logs, metrics, or tracing.

Give it a try using Grafana Play

With Grafana Play, you can explore and see how it works, learning from practical examples to accelerate your development. This feature can be seen on the Grafana Play site.

Try it

Pyroscope query editor

The Pyroscope data source query editor gives you access to a profile type selector, a label selector, and collapsible options.

Like Profiles Drilldown, the query editor also provides a flame graph to visualize data.

To access the query editor:

Sign into Grafana or Grafana Cloud.
Select your Pyroscope data source.
From the menu, choose Explore.
Select a profile type from the drop-down menu.

Profile selector
Use the labels selector input to filter by labels. Pyroscope uses similar syntax to Prometheus to filter labels. Refer to Pyroscope documentation for available operators and syntax.

While the label selector can be left empty to query all profiles without filtering by labels, you must select a profile type or app for the query to be valid.

Grafana doesn’t show any data if the profile type or app isn’t selected when a query runs.
Expand the Options section to view Query Type and Group by.
Select a query type to return the profile data. Data is shown in the Flame Graph, metric data visualized in a graph, or both. You can only select both options in Explore. The panels used on dashboards allow only one visualization.

Using Group by, you can group metric data by a specified label. Without any Group by label, metric data aggregates over all the labels into single time series. You can use multiple labels to group by. Group by only effects the metric data and doesn’t change the profile data results.

In conjunction with Group by, you can set a positive number in the Limit input to limit the maximum number of time series returned by the data source. The series returned are always ordered by descending value for the total aggregated data over the time period.

Profiles query results

Profiles can be visualized in a flame graph. Refer to the Flame Graph documentation to learn about the visualization and its features.

Pyroscope returns profiles aggregated over a 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 up to the point of a single scrape interval.

Metrics query results

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

This allows you to quickly see any spikes in the value of the scraped profiles and zoom in to a particular time range.

Troubleshoot Pyroscope data source issues

Mon, 20 Apr 2026 09:57:34 +0000

Troubleshoot Pyroscope data source issues

This document provides solutions to common issues you may encounter when configuring or using the Pyroscope data source. For configuration instructions, refer to Configure the Grafana Pyroscope data source.

Connection and configuration errors

These errors occur when setting up the data source or when connecting to the Pyroscope backend.

“Data source is not working” or connection fails

Symptoms:

Save & test fails with a connection error
Error message indicates the Pyroscope backend is unreachable
Timeout errors when testing the data source

Possible causes and solutions:

Cause	Solution
Incorrect URL	Verify the URL points to your Pyroscope instance. For self-managed deployments, the default port is `4040` (for example, `http://localhost:4040`).
Pyroscope service not running	Check that the Pyroscope backend is running and accessible. Use `curl` or a browser to test connectivity to the Pyroscope URL.
Network connectivity issues	Verify network connectivity from the Grafana server to the Pyroscope endpoint. Check firewall rules allow outbound connections on the required port.
Microservices mode routing	If running Pyroscope in microservices mode, ensure the URL points to a gateway or proxy that routes requests correctly. Refer to the Helm ingress configuration for routing requirements.
TLS/SSL certificate issues	If using HTTPS, verify the certificate is valid and trusted by the Grafana server. Configure TLS settings in the data source if using self-signed certificates.

URL format issues

Symptoms:

Data source test fails immediately
Error indicates invalid URL

Solutions:

Ensure the URL includes the protocol (http:// or https://).
Remove any trailing slashes from the URL.
For Grafana Cloud Profiles, find the correct URL under Manage your stack in your organization settings.
Verify the port number is correct for your deployment.

Authentication errors

These errors occur when the data source cannot authenticate with the Pyroscope backend.

“Authentication failed” or “Unauthorized”

Symptoms:

Save & test fails with authentication errors
Queries return 401 or 403 status codes
Profile types don’t load

Possible causes and solutions:

Cause	Solution
Invalid credentials	Verify the username and password or API key are correct.
Expired credentials	Generate new credentials and update the data source configuration.
Incorrect authentication type	Ensure you’ve selected the correct authentication method for your Pyroscope deployment (Basic auth, API key, or no authentication for local setups).
Missing authentication headers	For custom authentication, verify the required headers are configured correctly in the data source settings.

Basic authentication not working

Symptoms:

Basic auth credentials are rejected
Works in browser but fails in Grafana

Solutions:

Verify Basic authentication is enabled in the data source settings.
Ensure the username and password are entered correctly (no extra spaces).
Check that the Pyroscope backend is configured to accept Basic authentication.
For Grafana Cloud Profiles, use the API key authentication method instead.

API key authentication issues

Symptoms:

API key is rejected
Error indicates invalid token

Solutions:

Verify you’re using the correct API key format for your Pyroscope deployment.
For Grafana Cloud, generate a new API key from the Grafana Cloud portal.
Ensure the API key has the required permissions to read profiling data.
Check if the API key has expired and generate a new one if necessary.

Query errors

These errors occur when executing queries against the Pyroscope data source.

“No data” or empty results

Symptoms:

Query executes without error but returns no data
Flame graph shows “No data” message
Metrics graph is empty

Possible causes and solutions:

Cause	Solution
Time range doesn’t contain data	Expand the dashboard time range. Profiling data may not exist for the selected period.
Application not sending profiles	Verify your application is configured to send profiles to Pyroscope. Check the Pyroscope agent or SDK configuration.
Incorrect profile type selected	Select a different profile type from the drop-down menu. Not all profile types are available for all applications.
Label selector too restrictive	Remove or modify label filters to broaden the query. Start without filters to verify data exists.
Wrong service or application selected	Verify the `service_name` label matches your application’s configuration.
Profile type or app not selected	Ensure you’ve selected a profile type or app in the query editor. The query returns no data if neither is selected.

“Profile type not found” or empty profile type selector

Symptoms:

Profile type drop-down is empty
Error indicates profile type doesn’t exist

Solutions:

Verify the Pyroscope backend is receiving profiles from your applications.
Check that the time range includes periods when profiles were collected.
Test the data source connection to ensure it’s working correctly.
For new deployments, wait a few minutes for initial profile data to be ingested.

Label names or values not loading

Symptoms:

Label selector doesn’t populate
No labels appear in the drop-down menus
Autocomplete doesn’t work

Solutions:

Verify the data source connection is working by testing it in the settings.
Select a profile type first, as labels are loaded based on the selected profile type.
Expand the time range to ensure label data is available.
Check the browser console for JavaScript errors that might indicate issues.

Query syntax errors

Symptoms:

Error message indicates invalid query syntax
Label selector is rejected

Solutions:

Use the correct label selector syntax. Pyroscope uses a syntax similar to Prometheus.
Enclose label values in double quotes: {service_name="my-service"}.
Use valid operators: =, !=, =~, !~.
Escape special characters in regular expression patterns when using =~ or !~.

Example valid queries:

{service_name="my-app"}
{service_name="my-app", env="production"}
{service_name=~"my-app.*"}

Flame graph issues

These errors are specific to the flame graph visualization.

Flame graph not rendering

Symptoms:

Query returns data but flame graph doesn’t display
Flame graph area is blank
Loading indicator never completes

Solutions:

Check that the Query Type is set to include profile data (not metrics only).
Verify the response contains valid profile data using the Query Inspector.
Try refreshing the page or re-running the query.
For large profiles, increase the browser memory limits or reduce the time range.

Flame graph shows aggregated data without detail

Symptoms:

Flame graph lacks expected granularity
Function names are missing or truncated
Stack traces appear incomplete

Solutions:

Zoom in to a smaller time range to get more detailed profiles.
Verify your application is instrumented to capture full stack traces.
Check if the profiling agent is configured with sufficient sampling rate.
For compiled languages, ensure debug symbols are available.

Unable to interact with flame graph

Symptoms:

Clicking on flame graph elements doesn’t work
Tooltip doesn’t appear
Zoom and filter controls are unresponsive

Solutions:

Verify JavaScript is enabled in your browser.
Check the browser console for JavaScript errors.
Try using a different browser or clearing the browser cache.
Update Grafana to the latest version.

Profiles Drilldown issues

These errors are specific to the Profiles Drilldown application.

Profiles Drilldown not available

Symptoms:

Profiles Drilldown option doesn’t appear in the menu
Error when trying to access Profiles Drilldown

Solutions:

Verify the Profiles Drilldown plugin is installed and enabled.
For self-managed Grafana, install the plugin from the Grafana plugin catalog.
Restart Grafana after installing the plugin.
Check that you have the required permissions to access the application.

Services or profiles not appearing in Profiles Drilldown

Symptoms:

Profiles Drilldown shows no services
Expected applications are missing

Solutions:

Verify the Pyroscope data source is configured and working.
Check that profiles are being ingested with the correct service_name label.
Ensure the time range includes periods when profiles were collected.
For microservices mode, verify the data source URL points to the correct gateway.

Traces to profiles issues

These errors occur when linking tracing and profiling data.

Span profiles not appearing

Symptoms:

Trace spans don’t show profile links
“Profiles for this span” option is missing

Solutions:

Verify the Tempo data source is configured with Traces to profiles enabled.
Ensure your application is instrumented to emit span profiles.
Check that the Pyroscope data source is selected in the Tempo data source configuration.
Verify profile data exists for the time range of the trace.

For more information, refer to Configure Traces to profiles.

Profile doesn’t match the trace span

Symptoms:

Profile data doesn’t correlate with the trace
Wrong time range in profile

Solutions:

Verify the trace and profile timestamps are synchronized.
Check that the application’s clock is accurate.
Ensure the span_id and trace_id labels are correctly propagated to profiles.

Performance issues

These issues relate to slow queries or high resource usage.

Slow queries or timeouts

Symptoms:

Queries take a long time to complete
Requests time out before returning results
Dashboard panels fail to load

Solutions:

Reduce the time range to decrease the amount of data processed.
Add label filters to narrow the query scope.
Increase the Timeout setting in the data source’s Additional settings.
Adjust the Minimum step setting to reduce the number of data points.
For large deployments, ensure the Pyroscope backend has sufficient resources.

High memory usage in browser

Symptoms:

Browser becomes unresponsive when viewing profiles
Memory warnings appear
Page crashes when loading flame graphs

Solutions:

Reduce the time range to load smaller profiles.
Close unnecessary browser tabs to free up memory.
Use a smaller aggregation window for very large profiles.
Consider using Profiles Drilldown for large-scale analysis.

Network and connectivity errors

These errors indicate problems with network connectivity between Grafana and Pyroscope.

“Connection refused” or timeout errors

Symptoms:

Data source test fails with network errors
Queries fail with connection errors
Intermittent connectivity issues

Solutions:

Verify network connectivity from the Grafana server to the Pyroscope endpoint.
Check firewall rules allow outbound connections on the required port (default: 4040).
For Kubernetes deployments, verify the service is exposed correctly.
For Grafana Cloud connecting to private resources, configure Private data source connect.
Check if a proxy is required and configure it in the data source settings.

SSL/TLS certificate errors

Symptoms:

Certificate validation failures
SSL handshake errors
“Certificate not trusted” messages

Solutions:

Ensure the system time is correct on the Grafana server.
Verify the certificate is valid and not expired.
For self-signed certificates, enable Skip TLS Verify in the data source settings (not recommended for production).
Add the CA certificate to the Grafana server’s trusted certificates.
Check that intermediate certificates are included in the certificate chain.

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 Pyroscope-specific entries that include request and response details.
Reset the log level to info after troubleshooting to avoid excessive log volume.

Get additional help

If you’ve tried the solutions in this guide and still encounter issues:

Check the Grafana community forums for similar issues.
Review the Pyroscope GitHub issues for known bugs.
Refer to Pyroscope documentation for additional guidance.
Contact Grafana Support if you’re an Enterprise, Cloud Pro, or Cloud Contracted user.
When reporting issues, include:
- Grafana version
- Pyroscope version (if self-managed)
- Error messages (redact sensitive information)
- Steps to reproduce
- Data source configuration (redact credentials)