[DOC] Add traces to profile content (#2980)

* Add traces to profile content * Rename folder to view and analyze * Fix links * Update docs/sources/view-and-analyze-profile-data/_index.md * Apply suggestions from code review * Fix links * Apply suggestions from code review * Update docs/sources/view-and-analyze-profile-data/_index.md * Add link to PR 2982 content * Apply suggestions from code review
grafana · Feb 8, 2024 · 2988c43 · 2988c43
1 parent f8e6d8b
commit 2988c43
Show file tree

Hide file tree

Showing 12 changed files with 118 additions and 59 deletions.
diff --git a/docs/sources/configure-server/about-server-api.md b/docs/sources/configure-server/about-server-api.md
@@ -1,17 +1,17 @@
 ---
 description: Learn about the Pyrocope server API
-menuTitle: Server API Overview
-title: Pyroscope Server HTTP API Reference
+menuTitle: Server HTTP API 
+title: Pyroscope server HTTP API
 weight: 20
 ---
 
-# Pyroscope Server HTTP API Reference
+# Pyroscope server HTTP API
 
 Pyroscope server exposes an HTTP API for querying profiling data and ingesting profiling data from other sources.
 
 ## Authentication
 
-Grafana Pyroscope does not include an authentication layer. Operators should use an authenticating reverse proxy for security.
+Grafana Pyroscope doesn't include an authentication layer. Operators should use an authenticating reverse proxy for security.
 
 In multi-tenant mode, Pyroscope requires the X-Scope-OrgID HTTP header set to a string identifying the tenant. This responsibility should be handled by the authenticating reverse proxy. For more information, refer to the [multi-tenancy documentation]({{< relref "./about-tenant-ids" >}}).
 
@@ -42,11 +42,11 @@ The request body contains profiling data, and the Content-Type header may be use
 
 Some of the query parameters depend on the format of profiling data. Pyroscope currently supports three major ingestion formats.
 
-### Text Formats
+### Text formats
 
 These formats handle simple ingestion of profiling data, such as `cpu` samples, and typically don't support metadata (e.g., labels) within the format. All necessary metadata is derived from query parameters, and the format is specified by the `format` query parameter.
 
-**Supported Formats:**
+**Supported formats:**
 
 - **Folded**: Also known as `collapsed`, this is the default format. Each line contains a stacktrace followed by the sample count for that stacktrace. For example:
 ```
@@ -62,7 +62,7 @@ foo;baz
 foo;bar
 ```
 
-### pprof format
+### The `pprof` format
 
 The `pprof` format is a widely used binary profiling data format, particularly prevalent in the Go ecosystem.
 
@@ -72,13 +72,13 @@ When using this format, certain query parameters have specific behaviors:
 - **name**: This parameter contains the _prefix_ of the application name. Since a single request might include multiple profile types, the complete application name is formed by concatenating this prefix with the profile type. For instance, if you send CPU profiling data and set `name` to `my-app{}`, it will be displayed in pyroscope as `my-app.cpu{}`.
 - **units**, **aggregationType**, and **sampleRate**: These parameters are ignored. The actual values are determined based on the profile types present in the data (refer to the "Sample Type Configuration" section for more details).
 
-#### Sample Type Configuration
+#### Sample type configuration
 
-Pyroscope server inherently supports standard Go profile types such as `cpu`, `inuse_objects`, `inuse_space`, `alloc_objects`, and `alloc_space`. When dealing with software that generates data in pprof format, you may need to supply a custom sample type configuration for Pyroscope to interpret the data correctly.
+Pyroscope server inherently supports standard Go profile types such as `cpu`, `inuse_objects`, `inuse_space`, `alloc_objects`, and `alloc_space`. When dealing with software that generates data in `pprof` format, you may need to supply a custom sample type configuration for Pyroscope to interpret the data correctly.
 
-For an example Python script to ingest a pprof file with a custom sample type configuration, see **[this Python script](https://github.com/grafana/pyroscope/tree/main/examples/api/ingest_pprof.py).**
+For an example Python script to ingest a `pprof` file with a custom sample type configuration, see **[this Python script](https://github.com/grafana/pyroscope/tree/main/examples/api/ingest_pprof.py).**
 
-To ingest pprof data with custom sample type configuration, modify your requests as follows:
+To ingest `pprof` data with custom sample type configuration, modify your requests as follows:
 * Set Content-Type to `multipart/form-data`.
 * Upload the profile data in a form file field named `profile`.
 * Include the sample type configuration in a form file field named `sample_type_config`.
@@ -249,7 +249,7 @@ In a Kubernetes environment, a query could also look like:
 `process_cpu:cpu:nanoseconds:cpu:nanoseconds{namespace="dev", container="my_application_name"}`
 
 {{% admonition type="note" %}}
-Refer to the [profiling types documentation]({{< relref "../ingest-and-analyze-profile-data/profiling-types" >}}) for more information and [profile-metrics.json](https://github.com/grafana/pyroscope/blob/main/public/app/constants/profile-metrics.json) for a list of valid profile types.
+Refer to the [profiling types documentation]({{< relref "../view-and-analyze-profile-data/profiling-types" >}}) for more information and [profile-metrics.json](https://github.com/grafana/pyroscope/blob/main/public/app/constants/profile-metrics.json) for a list of valid profile types.
 {{% /admonition %}}
 
 #### `from` and `until`
@@ -264,9 +264,9 @@ This table details the options for passing absolute values.
 | Option                 | Example               | Notes              |
 |:-----------------------|:----------------------|:-------------------|
 | Date                   | `20231223`            | Format: `YYYYMMDD` |
-| Unix Time seconds      | `1577836800`          |                    | 
-| Unix Time milliseconds | `1577836800000`       |                    | 
-| Unix Time microseconds | `1577836800000000`    |                    | 
+| Unix Time seconds      | `1577836800`          |                    |
+| Unix Time milliseconds | `1577836800000`       |                    |
+| Unix Time microseconds | `1577836800000000`    |                    |
 | Unix Time nanoseconds  | `1577836800000000000` |                    |
 
 **Relative time**
@@ -301,7 +301,7 @@ See the [Query output](#query-output) section for more information on the respon
 
 #### `maxNodes`
 
-The `maxNodes` parameter truncates the number of elements in the profile response, to allow tools (for example, a frontend) to render large profiles efficiently. 
+The `maxNodes` parameter truncates the number of elements in the profile response, to allow tools (for example, a frontend) to render large profiles efficiently.
 This is typically used for profiles that are known to have large stack traces.
 
 When no value is provided, the default is taken from the `max_flamegraph_nodes_default` configuration parameter.
@@ -377,7 +377,7 @@ This example groups by a cluster:
 }
 ```
 
-### Alternative Query Output
+### Alternative query output
 
 When the `format` query parameter is `dot`, the endpoint responds with a [DOT format](https://en.wikipedia.org/wiki/DOT_(graph_description_language)) data representing the queried profile.
 This can be used to create an alternative visualization of the profile.
@@ -419,4 +419,4 @@ See [this Python script](https://github.com/grafana/pyroscope/tree/main/examples
 
 The `profilecli` tool can also be used to interact with the Pyroscope server API.
 The tool supports operations such as ingesting profiles, querying for existing profiles, and more.
-Refer to the [Profile CLI]({{< relref "../ingest-and-analyze-profile-data/profile-cli" >}}) page for more information.
+Refer to the [Profile CLI]({{< relref "../view-and-analyze-profile-data/profile-cli" >}}) page for more information.
diff --git a/docs/sources/ingest-and-analyze-profile-data/_index.md b/docs/sources/ingest-and-analyze-profile-data/_index.md
diff --git a/docs/sources/introduction/continuous-profiling/_index.md b/docs/sources/introduction/continuous-profiling/_index.md
@@ -21,7 +21,7 @@ This is great for debugging but not so great for production.
 ![example flamegraph](https://grafana.com/static/img/pyroscope/pyroscope-ui-single-2023-11-30.png)
 
 {{% admonition type="note" %}}
-To learn more about flamegraphs, refer to [Flamegraphs: Visualizing performance data]({{< relref "../flamegraphs" >}}).
+To learn more about flamegraphs, refer to [Flamegraphs: Visualizing performance data]({{< relref "../../view-and-analyze-profile-data/flamegraphs" >}}).
 {{% /admonition %}}
 
 Continuous profiling is a modern approach which is safer and more scalable for production environments.
@@ -54,7 +54,7 @@ Pyroscope's low-overhead profiling enables precise optimization of resource usag
 By providing in-depth insights into application performance, Pyroscope allows teams to identify and eliminate inefficiencies, leading to significant savings in areas like observability, incident management, messaging/queuing, deployment tools, and infrastructure.
 
 By using sampling profilers, Pyroscope is able to collect data with minimal overhead (~2-5% depending on a few factors).
-The [custom storage engine](https://pyroscope.io/docs/storage-design/) compresses and stores the data efficiently.
+The [custom storage engine]({{< relref "../../reference-pyroscope-architecture/about-grafana-pyroscope-architecture" >}}) compresses and stores the data efficiently.
 Some advantages of this are:
 
 - Low CPU overhead thanks to sampling profiler technology

diff --git a/docs/sources/view-and-analyze-profile-data/_index.md b/docs/sources/view-and-analyze-profile-data/_index.md
@@ -0,0 +1,42 @@
+---
+title: View and analyze profile data
+menuTitle: View and analyze profile data
+description: How to use Pyroscope to view and analyze profile data.
+aliases:
+  - ../ingest-and-analyze-profile-data/
+weight: 50
+keywords:
+  - pyroscope
+  - UI
+  - performance analysis
+  - flamegraphs
+  - CLI
+---
+
+# View and analyze profile data
+
+Profiling data can be presented in a variety of formats presents such as:
+- **Flamegraphs**: Visualize call relationships and identify hotspots.
+- **Tables**: View detailed statistics for specific functions or time periods.
+- **Charts and graphs**: Analyze trends and compare performance across different metrics.
+
+## Viewing profiles
+
+Pyroscope offers both a Command Line Interface (CLI) and an Application Programming Interface (API) to interact with and retrieve profiling data. These tools provide flexibility in how you access and manage your profiling information.
+
+You can export profiling data from Pyroscope in various formats:
+- **pprof**: Support for pprof, gzip compressed pprof, for example, `foo.pprof.gz`
+- **JSON**: JSON object easy to integrate with other tools and scripts
+
+Integrating Pyroscope with Grafana is a common and recommended approach for visualizing profiling data. Grafana, being a powerful tool for data visualization, can effectively display profiling data in an accessible and insightful manner.
+
+Options for Visualizing Data in Grafana:
+- **Pyroscope App Plugin**: This plugin is specifically designed for Pyroscope data. It allows for easy browsing, analysis, and comparison of multiple profiles across different labels or time periods. This is particularly useful for a comprehensive overview of your application's performance.
+- **Explore Tab**: In Grafana, the Explore tab is suited for making targeted queries on your profiling data. This is useful for in-depth analysis of specific aspects of your application's performance.
+- **Dashboard**: Grafana dashboards are excellent for integrating profiling data with other metrics. You can display Pyroscope data alongside other dashboard items, creating a unified view of your application’s overall health and performance.
+
+For more information on using profiles in Grafana, refer to [Pyroscope and profiles in Grafana]({{< relref "../introduction/pyroscope-in-grafana#pyroscope-and-profiling-in-grafana" >}}).
+
+The Pyroscope app plugin works for Grafana Cloud. 
+
+For more information on configuring these data sources, refer to the Pyroscope data source documentation in [Grafana Cloud](/docs/grafana-cloud/connect-externally-hosted/data-sources/grafana-pyroscope/) and [Grafana](/docs/grafana/latest/datasources/grafana-pyroscope/).
diff --git a/...e-profile-data/analyze-profiles/_index.md → ...e-profile-data/analyze-profiles/_index.md b/...e-profile-data/analyze-profiles/_index.md → ...e-profile-data/analyze-profiles/_index.md
@@ -3,6 +3,8 @@ title: Analyze app performance using Pyroscope
 menuTitle: Analyze app performance
 description: How to use the Pyroscope UI to analyze performance of your applications.
 weight: 40
+aliases:
+  - ../ingest-and-analyze-profile-data/analyze-profiles/
 draft: true
 keywords:
   - pyroscope

diff --git a/docs/sources/introduction/flamegraphs.md → ...w-and-analyze-profile-data/flamegraphs.md b/docs/sources/introduction/flamegraphs.md → ...w-and-analyze-profile-data/flamegraphs.md
@@ -2,7 +2,9 @@
 title: "Flamegraphs: Visualizing performance data"
 menuTitle: Flamegraphs
 description: Learn about flamegraphs to help visualize performance data.
-weight: 100
+weight: 33
+aliases:
+  - ../introduction/flamegraphs/
 keywords:
   - Pyroscope
   - Profiling

diff --git a/...t-and-analyze-profile-data/profile-cli.md → ...w-and-analyze-profile-data/profile-cli.md b/...t-and-analyze-profile-data/profile-cli.md → ...w-and-analyze-profile-data/profile-cli.md
@@ -3,10 +3,11 @@ aliases:
   - /docs/phlare/latest/operators-guide/configuring/profile-cli/
   - /docs/phlare/latest/profile-cli/
   - /docs/pyroscope/latest/configure-server/profile-cli/
+  - ../ingest-and-analyze-profile-data/profile-cli/
 description: Getting started with the profile CLI tool.
 menuTitle: Profile CLI
 title: Profile CLI
-weight: 50
+weight: 60
 ---
 
 # Profile CLI

diff --git a/...sources/introduction/profiling-tracing.md → ...ze-profile-data/profile-tracing/_index.md b/...sources/introduction/profiling-tracing.md → ...ze-profile-data/profile-tracing/_index.md
@@ -3,6 +3,9 @@ title: Profiling and tracing integration
 menuTitle: Profiling and tracing
 description: Learning about how profiling and tracing work together.
 weight: 50
+aliases:
+  - ../introduction/traces-to-profiles/
+  - ../introduction/profile-tracing/
 keywords:
   - pyroscope
   - continuous profiling

diff --git a/docs/sources/view-and-analyze-profile-data/profile-tracing/traces-to-profiles.md b/docs/sources/view-and-analyze-profile-data/profile-tracing/traces-to-profiles.md
@@ -0,0 +1,22 @@
+---
+title: Traces to profiles
+menuTitle: Traces to profiles
+description: Learning about traces to profiles integration in Grafana and Grafana Cloud.
+weight: 150
+keywords:
+  - pyroscope
+  - continuous profiling
+  - tracing
+---
+
+# Traces to profiles
+
+{{< admonition type="note" >}}
+
+Your application must be instrumented for profiles and traces. For more information, refer to [Span profiles for Traces to profiles]({{< relref "../../configure-client/go-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="<GRAFANA VERSION>" >}}
diff --git a/...ze-profile-data/profiling-types/_index.md → ...ze-profile-data/profiling-types/_index.md b/...ze-profile-data/profiling-types/_index.md → ...ze-profile-data/profiling-types/_index.md
@@ -3,6 +3,8 @@ title: Understand profiling types and their uses in Pyroscope
 menuTitle: Understand profiling types
 description: Learn about the different profiling types available in Pyroscope and how to effectively use them in your application performance analysis.
 weight: 30
+aliases:
+  - ../ingest-and-analyze-profile-data/profiling-types/
 keywords:
   - pyroscope
   - profiling types

diff --git a/...-and-analyze-profile-data/pyroscope-ui.md → ...-and-analyze-profile-data/pyroscope-ui.md b/...-and-analyze-profile-data/pyroscope-ui.md → ...-and-analyze-profile-data/pyroscope-ui.md
@@ -3,6 +3,8 @@ title: Use the Pyroscope UI to explore profiling data
 menuTitle: Use the Pyroscope UI
 description: How to use the Pyroscope UI to explore profile data.
 weight: 40
+aliases:
+  - ../ingest-and-analyze-profile-data/profile-ui/
 keywords:
   - pyroscope
   - performance analysis

diff --git a/...and-analyze-profile-data/self-vs-total.md → ...and-analyze-profile-data/self-vs-total.md b/...and-analyze-profile-data/self-vs-total.md → ...and-analyze-profile-data/self-vs-total.md
@@ -1,8 +1,10 @@
 ---
 title: Understand 'self' vs. 'total' metrics in profiling with Pyroscope
 menuTitle: Understand 'self' vs. 'total' metrics
-description: Learn the differences between 'self' and 'total' metrics in profiling and their specific applications in CPU and Memory profiling with Pyroscope
-weight: 35
+description: Learn the differences between 'self' and 'total' metrics in profiling and their specific applications in CPU and Memory profiling with Pyroscope.
+weight: 42
+aliases:
+  - ../ingest-and-analyze-profile-data/self-vs-total/
 keywords:
   - pyroscope
   - cpu profiling
@@ -17,28 +19,29 @@ Profiling in Pyroscope provideds many different ways of analyzing your profiling
 
 ![Self vs total annotated](https://grafana.com/media/docs/pyroscope/self_vs_total_annotated.png)
 
-## General Concepts of 'Self' and 'Total'
+## Self
+
+'Self' refers to the resource usage (CPU time, memory allocation, etc.) directly attributed to a specific function or a code segment, excluding the resources used by its sub-functions or calls
+
+This metric helps isolate the direct impact of a specific code block, making it crucial for pinpointing primary resource consumers
 
 ![Self vs total diagram](https://grafana.com/media/docs/pyroscope/self_vs_total_explainer_diagram.png)
 
-### What is 'Self'?
 
-- **Definition**: 'Self' refers to the resource usage (CPU time, memory allocation, etc.) directly attributed to a specific function or a code segment, excluding the resources used by its sub-functions or calls
-- **Importance**: This metric helps isolate the direct impact of a specific code block, making it crucial for pinpointing primary resource consumers
+## Total
 
-### What is 'Total'?
+'Total' encompasses the combined resource usage of a function along with all the functions it calls
 
-- **Definition**: 'Total' encompasses the combined resource usage of a function along with all the functions it calls
-- **Importance**: It provides a holistic view of a function's overall resource consumption, essential for understanding cumulative impacts
+It provides a holistic view of a function's overall resource consumption, essential for understanding cumulative impacts
 
-## 'Self' and 'Total' in CPU Profiling
+## 'Self' and 'Total' in CPU profiling
 
-### CPU Profiling Specifics
+In CPU profiling, 'self' indicates the CPU time consumed directly by the function, crucial for identifying functions with high CPU demand.
 
-- **Self in CPU**: In CPU profiling, 'self' indicates the CPU time consumed directly by the function, crucial for identifying functions with high CPU demand.
-- **Total in CPU**: The 'total' CPU time includes time spent in the function itself plus time in all called functions, highlighting comprehensive CPU usage
+The 'total' CPU time includes time spent in the function itself plus time in all called functions, highlighting comprehensive CPU usage
 
-In the example below, we demonstrate a simplified pseudocode representation of a CPU-intensive process. This illustrates how 'self' and 'total' time would be calculated for different functions in a typical application. The following diagram provides a visual representation of these concepts.
+The example below demonstrates a simplified pseudocode representation of a CPU-intensive process.
+This illustrates how 'self' and 'total' time would be calculated for different functions in a typical application. The following diagram provides a visual representation of these concepts.
 
 ![Self vs total diagram](https://grafana.com/media/docs/pyroscope/self_vs_total_explainer_diagram.png)
 
@@ -68,14 +71,12 @@ def apply():
 handle_request()
 ```
 
-## 'Self' and 'Total' in Memory Profiling
-
-### Memory Profiling Specifics
+## 'Self' and 'Total' in memory profiling
 
 - **Self in Memory**: For memory profiling, 'self' measures the memory allocated by the function itself, vital for detecting direct memory allocation issues.
-- **Total in Memory**: 'Total' memory includes allocations by the function and its callee functions, essential for assessing overall memory footprint.
+- **Total in Memory**: 'Total' memory includes allocations by the function and its called functions, essential for assessing overall memory footprint.
 
-The same example from the CPU profiling section can be used to illustrate the concepts of 'self' and 'total' in memory profiling, just with memory units instead of cpu. 
+The same example from the CPU profiling section can be used to illustrate the concepts of 'self' and 'total' in memory profiling, just with memory units instead of CPU.
 
 ## Conclusion