From 83c8c96b31b58e9ca66ab430c22f09a0473eb1e9 Mon Sep 17 00:00:00 2001 From: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> Date: Mon, 12 Feb 2024 10:20:22 -0500 Subject: [PATCH] [v10.3.x] [DOC] Update Pyroscope data source (#82320) [DOC] Update Pyroscope data source (#82130) Co-authored-by: Jack Baldry (cherry picked from commit 815e61258c2cd755440a0d64a33feb005153d4d7) --- docs/sources/datasources/pyroscope/_index.md | 80 ++++++++++++++++++ .../configure-pyroscope-data-source.md} | 25 ++---- .../pyroscope/query-profile-data.md | 82 +++++++++++++++++++ .../datasources/tempo-traces-to-profiles.md | 8 +- 4 files changed, 176 insertions(+), 19 deletions(-) create mode 100644 docs/sources/datasources/pyroscope/_index.md rename docs/sources/datasources/{grafana-pyroscope.md => pyroscope/configure-pyroscope-data-source.md} (90%) create mode 100644 docs/sources/datasources/pyroscope/query-profile-data.md diff --git a/docs/sources/datasources/pyroscope/_index.md b/docs/sources/datasources/pyroscope/_index.md new file mode 100644 index 00000000000..88d5a1c88be --- /dev/null +++ b/docs/sources/datasources/pyroscope/_index.md @@ -0,0 +1,80 @@ +--- +aliases: + - ../features/datasources/phlare/ # /docs/grafana//features/datasources/phlare/ + - ../features/datasources/grafana-pyroscope/ # /docs/grafana//features/datasources/grafana-pyroscope/ + - ../datasources/grafana-pyroscope/ # /docs/grafana//datasources/grafana-pyroscope/ +description: Horizontally-scalable, highly-available, multi-tenant continuous profiling + aggregation system. OSS profiling solution from Grafana Labs. +keywords: + - grafana + - phlare + - guide + - profiling + - pyroscope +labels: + products: + - cloud + - enterprise + - oss +title: Grafana Pyroscope +weight: 1150 +--- + +# Grafana Pyroscope data source + +Grafana Pyroscope is a horizontally scalable, highly available, multi-tenant, OSS, continuous profiling aggregation system. Add it as a data source, and you are ready to query your profiles in [Explore][explore]. + +To learn more about profiling and Pyroscope, refer to the [Introduction to Pyroscope](/docs/pyroscope/introduction/). + +For information on configuring the Pyroscope data source, refer to [Configure the Grafana Pyroscope data source](./configure-pyroscope-data-source). + +## Integrate profiles into dashboards + +Using the Pyroscope data source, you can integrate profiles into your dashboards. +In this case, the screenshot shows memory profiles alongside panels for logs and metrics to be able to debug out of memory (OOM) errors alongside the associated logs and metrics. + +![dashboard](https://grafana.com/static/img/pyroscope/grafana-pyroscope-dashboard-2023-11-30.png) + +## Visualize traces and profiles data using Traces to profiles + +You can link profile and tracing data using your Pyroscope data source with the Tempo data source. + +Combined traces and profiles let you see granular line-level detail when available for a trace span. This allows you pinpoint the exact function that's causing a bottleneck in your application as well as a specific request. + +![trace-profiler-view](https://grafana.com/static/img/pyroscope/pyroscope-trace-profiler-view-2023-11-30.png) + +For more information, refer to the [Traces to profile section][configure-tempo-data-source] of the Tempo data source documentation. + +{{< youtube id="AG8VzfFMLxo" >}} + +## Provision the Grafana Pyroscope data source + +You can modify the Grafana configuration files to provision the Grafana Pyroscope data source. +To learn more, and to view the available provisioning settings, refer to [provisioning documentation][provisioning-data-sources]. + +Here is an example configuration: + +```yaml +apiVersion: 1 + +datasources: + - name: Grafana Pyroscope + type: grafana-pyroscope-datasource + url: http://localhost:4040 + jsonData: + minStep: '15s' +``` + +{{% docs/reference %}} +[explore]: "/docs/grafana/ -> /docs/grafana//explore" +[explore]: "/docs/grafana-cloud/ -> /docs/grafana//explore" + +[flame-graph]: "/docs/grafana/ -> /docs/grafana//panels-visualizations/visualizations/flame-graph" +[flame-graph]: "/docs/grafana-cloud/ -> /docs/grafana//panels-visualizations/visualizations/flame-graph" + +[provisioning-data-sources]: "/docs/grafana/ -> /docs/grafana//administration/provisioning#datasources" +[provisioning-data-sources]: "/docs/grafana-cloud/ -> /docs/grafana//administration/provisioning#datasources" + +[configure-tempo-data-source]: "/docs/grafana/ -> /docs/grafana//datasources/tempo/configure-tempo-data-source" +[configure-tempo-data-source]: "/docs/grafana-cloud/ -> docs/grafana-cloud/connect-externally-hosted/data-sources/tempo/configure-tempo-data-source" +{{% /docs/reference %}} diff --git a/docs/sources/datasources/grafana-pyroscope.md b/docs/sources/datasources/pyroscope/configure-pyroscope-data-source.md similarity index 90% rename from docs/sources/datasources/grafana-pyroscope.md rename to docs/sources/datasources/pyroscope/configure-pyroscope-data-source.md index f0b32c1c0aa..7d6f9b28262 100644 --- a/docs/sources/datasources/grafana-pyroscope.md +++ b/docs/sources/datasources/pyroscope/configure-pyroscope-data-source.md @@ -1,13 +1,7 @@ --- -aliases: - - ../features/datasources/phlare/ - - ../features/datasources/grafana-pyroscope/ -description: Horizontally-scalable, highly-available, multi-tenant continuous profiling - aggregation system. OSS profiling solution from Grafana Labs. +description: Configure your Pyroscope data source for Grafana. keywords: - - grafana - - phlare - - guide + - configure - profiling - pyroscope labels: @@ -15,17 +9,14 @@ labels: - cloud - enterprise - oss -title: Grafana Pyroscope -weight: 1150 +title: Configure the Grafana Pyroscope data source +menuTitle: Configure Pyroscope +weight: 200 --- -# Grafana Pyroscope data source +# Configure the Grafana Pyroscope data source -Formerly Phlare data source, now Grafana Pyroscope, a horizontally scalable, highly-available, multi-tenant, OSS, continuous profiling aggregation system. Add it as a data source, and you are ready to query your profiles in [Explore][explore]. - -## Configure the Grafana Pyroscope data source - -To configure basic settings for the data source, complete the following steps: +To configure basic settings for the Pyroscope data source, complete the following steps: 1. Click **Connections** in the left-side menu. 1. Under Your connections, click **Data sources**. @@ -48,7 +39,7 @@ To configure basic settings for the data source, complete the following steps: ## Querying -### Query Editor +### Query editor ![Query editor](/static/img/docs/phlare/query-editor.png 'Query editor') diff --git a/docs/sources/datasources/pyroscope/query-profile-data.md b/docs/sources/datasources/pyroscope/query-profile-data.md new file mode 100644 index 00000000000..8c68fb4275b --- /dev/null +++ b/docs/sources/datasources/pyroscope/query-profile-data.md @@ -0,0 +1,82 @@ +--- +description: Use the query editor to explore your Pyroscope data. +keywords: + - query + - profiling + - pyroscope +labels: + products: + - cloud + - enterprise + - oss +title: Query profile data +menuTitle: Query profile data +weight: 300 +--- + +# Query profile data + +The Pyroscope data source query editor gives you access to a profile type selector, a label selector, and collapsible options. + +![Query editor](/media/docs/pyroscope/query-editor/query-editor.png 'Query editor') + +To access the query editor: + +1. Sign into Grafana or Grafana Cloud. +1. Select your Pyroscope data source. +1. From the menu, choose **Explore**. + +1. Select a profile type from the drop-down menu. + + {{< figure src="/media/docs/pyroscope/query-editor/select-profile.png" class="docs-image--no-shadow" max-width="450px" caption="Profile selector" >}} + +1. Use the labels selector input to filter by labels. Pyroscope uses similar syntax to Prometheus to filter labels. + Refer to [Pyroscope documentation](https://grafana.com/docs/pyroscope/latest/) for available operators and syntax. + + While the label selector can be left empty to query all profiles without filtering by labels, 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. + + ![Labels selector](/media/docs/pyroscope/query-editor/labels-selector.png 'Labels selector') + +1. Expand the **Options** section to view **Query Type** and **Group by**. + ![Options section](/media/docs/pyroscope/query-editor/options-section.png 'Options section') + +1. Select a query type to return the profile data. Data is shown in the [Flame Graph][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. + +## Profiles query results + +Profiles can be visualized in a flame graph. +Refer to the [Flame Graph documentation][flame-graph] to learn about the visualization and its features. + +![Flame graph](/media/docs/pyroscope/query-editor/flame-graph.png 'Flame graph') + +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. + +![Metrics graph](/media/docs/pyroscope/query-editor/metric-graph.png 'Metrics graph') + +This allows you to quickly see any spikes in the value of the scraped profiles and zoom in to a particular time range. + +{{% docs/reference %}} +[explore]: "/docs/grafana/ -> /docs/grafana//explore" +[explore]: "/docs/grafana-cloud/ -> /docs/grafana//explore" + +[flame-graph]: "/docs/grafana/ -> /docs/grafana//panels-visualizations/visualizations/flame-graph" +[flame-graph]: "/docs/grafana-cloud/ -> /docs/grafana//panels-visualizations/visualizations/flame-graph" + +[provisioning-data-sources]: "/docs/grafana/ -> /docs/grafana//administration/provisioning#datasources" +[provisioning-data-sources]: "/docs/grafana-cloud/ -> /docs/grafana//administration/provisioning#datasources" + +[configure-tempo-data-source]: "/docs/grafana/ -> /docs/grafana//datasources/tempo/configure-tempo-data-source" +[configure-tempo-data-source]: "/docs/grafana-cloud/ -> docs/grafana-cloud/connect-externally-hosted/data-sources/tempo/configure-tempo-data-source" +{{% /docs/reference %}} diff --git a/docs/sources/shared/datasources/tempo-traces-to-profiles.md b/docs/sources/shared/datasources/tempo-traces-to-profiles.md index 2a2d9658158..541444798a3 100644 --- a/docs/sources/shared/datasources/tempo-traces-to-profiles.md +++ b/docs/sources/shared/datasources/tempo-traces-to-profiles.md @@ -25,9 +25,13 @@ When configured, this connection lets you run queries from a trace span into the There are two ways to configure the trace to profiles feature: -- Use a simplified configuration with default query, or +- 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. +{{< admonition type="note">}} +Traces to profile requires a Tempo data source with Traces to profiles configured and a Pyroscope data source. This integration supports profile data generated using Go, Ruby, and Java instrumentation SDKs. +{{< /admonition >}} + To use trace to profiles, navigate to **Explore** and query a trace. Each span now 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). ![Selecting a link in the span queries the profile data source](/static/img/docs/tempo/profiles/tempo-profiles-Span-link-profile-data-source.png) @@ -36,7 +40,7 @@ To use trace to profiles, you must have a configured Grafana Pyroscope data sour ## Use a simple configuration -To use a simple configuration, follow these steps: +To use a basic configuration, follow these steps: 1. Select a Pyroscope data source from the **Data source** drop-down. 1. Optional: Choose any tags to use in the query. If left blank, the default values of `service.name` and `service.namespace` are used.