From 1d551a86dc5179ac2cf3628beea3bb1c1bb3b592 Mon Sep 17 00:00:00 2001 From: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> Date: Tue, 7 Jan 2025 11:43:24 -0500 Subject: [PATCH] [DOC] Updates for profile doc restructure (#98301) * Updates for profile doc restructure * Updates from prettier --- docs/sources/datasources/pyroscope/_index.md | 36 ++++++++++++- .../pyroscope/configure-traces-to-profiles.md | 21 ++++++++ .../pyroscope/query-profile-data.md | 50 ++++++++----------- 3 files changed, 75 insertions(+), 32 deletions(-) create mode 100644 docs/sources/datasources/pyroscope/configure-traces-to-profiles.md diff --git a/docs/sources/datasources/pyroscope/_index.md b/docs/sources/datasources/pyroscope/_index.md index 87aad99701b..069902bfc0a 100644 --- a/docs/sources/datasources/pyroscope/_index.md +++ b/docs/sources/datasources/pyroscope/_index.md @@ -6,7 +6,6 @@ aliases: description: Horizontally-scalable, highly-available, multi-tenant continuous profiling aggregation system. OSS profiling solution from Grafana Labs. keywords: - - grafana - phlare - guide - profiling @@ -39,11 +38,17 @@ refs: destination: https://grafana.com/docs/grafana//administration/provisioning/#datasources - pattern: /docs/grafana-cloud/ destination: https://grafana.com/docs/grafana//administration/provisioning/#datasources + flame-graph-panel: + - pattern: /docs/grafana/ + destination: https://grafana.com/docs/grafana//panels-visualizations/visualizations/flame-graph/ + - pattern: /docs/grafana-cloud/ + destination: https://grafana.com/docs/grafana-cloud/visualizations/panels-visualizations/visualizations/flame-graph/ --- # 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](ref:explore). +Grafana Pyroscope is a horizontally scalable, highly available, multi-tenant, OSS, continuous profiling aggregation system. +Add a Pyroscope data source to query your profiles in [Explore](ref:explore). Refer to [Introduction to Pyroscope](https://grafana.com/docs/pyroscope//introduction/) to understand profiling and Pyroscope. @@ -53,9 +58,36 @@ To use profiling data, you should: - [Configure the Grafana Pyroscope data source](./configure-pyroscope-data-source/). - [View and query profiling data using Explore Profiles or the query editor ](./query-profile-data/) +## Continuous profiling + +While code profiling has been a long-standing practice, continuous profiling represents a modern and more advanced approach to performance monitoring. + +This technique adds two critical dimensions to traditional profiles: + +Time +: Profiling data is collected _continuously_, providing a time-centric view that allows querying performance data from any point in the past. + +Metadata +: Profiles are enriched with metadata, adding contextual depth to the performance data. + +These dimensions, coupled with the detailed nature of performance profiles, make continuous profiling a uniquely valuable tool. + +### Flame graphs + + + +Flame graphs help you visualize resource allocation and performance bottlenecks, and you even get suggested recommendations and performance fixes via AI-driven flame graph analysis, as well as line-level insights from our GitHub integration. + + + +On views with a flame graph, you can use **Explain flame graph** to provide an AI flame graph analysis that explains the performance bottleneck, root cause, and recommended fix. +For more information, refer to [Flame graph AI](https://grafana.com/docs/grafana-cloud/monitor-applications/profiles/flamegraph-ai/). + ## Integrate profiles into dashboards Using the Pyroscope data source, you can integrate profiles into your dashboards. +For example, you can embed flame graphs using the [flame graph panel](ref:flame-graph-panel). + 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) diff --git a/docs/sources/datasources/pyroscope/configure-traces-to-profiles.md b/docs/sources/datasources/pyroscope/configure-traces-to-profiles.md new file mode 100644 index 00000000000..c3b4cb16ae6 --- /dev/null +++ b/docs/sources/datasources/pyroscope/configure-traces-to-profiles.md @@ -0,0 +1,21 @@ +--- +title: Configure traces to profiles +menuTitle: Configure traces to profiles +description: Learn how to configure the traces to profiles integration in Grafana and Grafana Cloud. +weight: 300 +keywords: + - continuous profiling + - tracing +--- + +# Configure traces to profiles + +{{< admonition type="note" >}} + +Your application must be instrumented for profiles and traces. For more information, refer to [Link traces to profiles](https://grafana.com/docs/pyroscope//configure-client/trace-span-profiles/). + +{{< /admonition >}} + +[//]: # 'Shared content for Trace to profiles in the Tempo data source' + +{{< docs/shared source="grafana" lookup="datasources/tempo-traces-to-profiles.md" version="" >}} diff --git a/docs/sources/datasources/pyroscope/query-profile-data.md b/docs/sources/datasources/pyroscope/query-profile-data.md index bdc2624ffed..d56a629d42d 100644 --- a/docs/sources/datasources/pyroscope/query-profile-data.md +++ b/docs/sources/datasources/pyroscope/query-profile-data.md @@ -11,7 +11,7 @@ labels: - oss title: Query profile data menuTitle: Query profile data -weight: 300 +weight: 400 refs: configure-tempo-data-source: - pattern: /docs/grafana/ @@ -43,11 +43,24 @@ refs: destination: /docs/grafana//administration/provisioning/#datasources - pattern: /docs/grafana-cloud/ destination: /docs/grafana//administration/provisioning/#datasources + flame-graph-panel: + - pattern: /docs/grafana/ + destination: /docs/grafana//panels-visualizations/visualizations/flame-graph/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/flame-graph/ --- +https://grafana.com/docs/grafana-cloud/visualizations/panels-visualizations/visualizations/flame-graph/ + # Query profile data -You can query your profile data using the built-in data source query editor or you can use the open source Grafana Explore Profiles app. +You can query your profile data using the open source Grafana Explore Profiles app or the built-in Grafana Pyroscope data source query editor. + +- Explore Profiles 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](ref:flame-graph-panel) documentation for details. ## Explore Profiles @@ -56,6 +69,8 @@ You can query your profile data using the built-in data source query editor or y You can use Explore Profiles in Grafana Cloud or in your own Grafana instance. For more information, refer to [Access or install Explore Profiles](ref:explore-profiles-install). +![Explore Profiles home screen](/media/docs/explore-profiles/explore-profiles-homescreen-v0.1.17.png) + ### Use cases There are several different modes for viewing, analyzing, and comparing profiling data. @@ -65,7 +80,7 @@ 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 -Explore Profiles provides an intuitive interface to specifically support these use cases. +Explore Profiles 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. Explore Profiles 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. @@ -74,31 +89,6 @@ Explore Profiles offers a convenient platform to analyze profiles and get insigh {{< docs/play title="the Grafana Play site" url="https://play.grafana.org/a/grafana-pyroscope-app/profiles-explorer" >}} -### Continuous profiling - -While code profiling has been a long-standing practice, continuous profiling represents a modern and more advanced approach to performance monitoring. - -This technique adds two critical dimensions to traditional profiles: - -Time -: Profiling data is collected _continuously_, providing a time-centric view that allows querying performance data from any point in the past. - -Metadata -: Profiles are enriched with metadata, adding contextual depth to the performance data. - -These dimensions, coupled with the detailed nature of performance profiles, make continuous profiling a uniquely valuable tool. - -### Flame graphs - - - -Flame graphs help you visualize resource allocation and performance bottlenecks, and you even get suggested recommendations and performance fixes via AI-driven flame graph analysis, as well as line-level insights from our GitHub integration. - - - -On views with a flame graph, you can use **Explain flame graph** to provide an AI flame graph analysis that explains the performance bottleneck, root cause, and recommended fix. -For more information, refer to [Flame graph AI](https://grafana.com/docs/grafana-cloud/monitor-applications/profiles/flamegraph-ai/). - ## Pyroscope query editor The Pyroscope data source query editor gives you access to a profile type selector, a label selector, and collapsible options. @@ -137,7 +127,7 @@ You can use multiple labels to group by. Group by only effects the metric data a 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 query results Profiles can be visualized in a flame graph. Refer to the [Flame Graph documentation](ref:flame-graph) to learn about the visualization and its features. @@ -148,7 +138,7 @@ 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 query results Metrics results represent the aggregated sum value over time of the selected profile type.