Skip to content

Commit 9a1f857

Browse files
kakkoyunkakkoyun
authored
Merge branch 'main' into java-support-page
2 parents 8e0edfc + 07a9c5e commit 9a1f857

23 files changed

+489
-546
lines changed

‎docs/community.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22

33
## Office hours
44

5-
Parca Community Office Hours are bi-weekly public meetings focused on Parca and Parca Agent development and contributions and general community questions. Everyone is welcome to join!
5+
Parca Community Office Hours are public meetings that occur every two weeks focused on Parca and Parca Agent development and contributions, in addition to general community questions. Everyone is welcome to join!
66

7-
When? Thursdays 17:00 UTC (see [here](https://everytimezone.com/s/c0ffbf98) to see what that is in your timezone)
7+
Office Hours are held on Mondays alternating between 17:00 UTC and 10:00 UTC to account for attendees across different time zones (see [here](https://everytimezone.com/s/c0ffbf98) to see these times are in your timezone)
88

99
* [Meeting calendar](https://calendar.google.com/calendar/embed?src=c_gpsbv9i59r8ocrri0m6aktt618%40group.calendar.google.com) ([Import Calendar](https://calendar.google.com/calendar/u/0?cid=Y19ncHNidjlpNTlyOG9jcnJpMG02YWt0dDYxOEBncm91cC5jYWxlbmRhci5nb29nbGUuY29t))
1010
* [Meeting notes](https://docs.google.com/document/d/1h2Ni_Q14doE_kScJsLCQewKHRPZXsyWVQt7X0iRzAXo/edit)

‎docs/debuginfod.md‎

Lines changed: 16 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,28 @@
1-
# debuginfod client
1+
# debuginfod support
22

3-
In order to symbolize ingested profiles, Parca needs to have debug information
4-
for the binaries that are being profiled. Debug information, also
5-
referred to as _debuginfos_, can be ELF object files, DWARF debug data, and
6-
source code. However, sometimes, application packages distributed by various Linux
7-
distros [strip](https://man7.org/linux/man-pages/man1/strip.1.html) away debug
8-
information to minimize the size of the binaries. Thankfully, there are publicly accessible
9-
servers, distributing debug information for various Linux package managers and distributions.
3+
:::tip
104

11-
[debuginfod](https://www.mankier.com/8/debuginfod) is an HTTP file server that serves debug
12-
information to clients based on the build IDs of the binaries. You can find out the build ID
13-
of a binary using the `file` command on Linux.
5+
This page assumes familiarity with what debuginfos are. First read the [debuginfos](debuginfos) docs page if you are not already familiar with debuginfos.
146

15-
Here is an example to find out the build ID of a zsh shell:
7+
:::
8+
9+
Unfortunately, packages distributed by various Linux distros [strip](https://man7.org/linux/man-pages/man1/strip.1.html) away debuginfos to minimize the size of the binaries.
10+
11+
Thankfully, there are publicly accessible servers, distributing debuginfos for various Linux package managers and distributions.
12+
13+
[debuginfod](https://www.mankier.com/8/debuginfod) is an HTTP file server that serves debuginfos to clients based on the Build IDs of the binaries. You can find out the Build ID of a binary using the `file` command on Linux.
14+
15+
Here is an example to find out the Build ID of a zsh binary:
1616

1717
```
1818
$ file /bin/zsh
1919
2020
/bin/zsh: ELF 64-bit LSB pie executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, BuildID[sha1]=24fcd0179bb3aa797de6a570c2359e528f7638c0, for GNU/Linux 3.2.0, stripped
2121
```
22-
Parca integrates with debuginfod to query for upstream debuginfod files and then
23-
stores them for potential later use. The default debuginfod server used by Parca is
24-
at https://debuginfod.elfutils.org .
25-
26-
## Implementation
27-
28-
Primarily, Parca looks for the relevant debug information files in its default
29-
symbol store. However, if debug info files are not found in the symbol store,
30-
Parca will try to fetch corresponding debuginfo files from the upstream
31-
[debuginfod servers](https://sourceware.org/elfutils/Debuginfod.html), and store
32-
them in the Parca symbol store, associated with the unique build ID of the object files.
33-
34-
The symbol store is a wrapper around the [Parca object store](https://www.parca.dev/docs/storage#storing-debug-information)
35-
to hold debug information. By default, Parca is configured to use the `/tmp`
36-
directory on local disk. This can be reconfigured to use any other user-specified
37-
location by editing the Parca configuration file.
38-
39-
The debuginfod client is implemented as a read-through client storage cache.
40-
An HTTP client is implemented to send requests to the upstream debuginfod servers.
41-
The client queries the server addresses sequentially until it finds the suitable
42-
debuginfo files. The downloaded object files are then stored in a `parca/debuginfod`
43-
bucket with the build ID as the key.
44-
45-
Users can add private debuginfod servers to be queried through the
46-
` --debuginfod-upstream-servers` flag.
22+
23+
Parca integrates with debuginfod to query for upstream debuginfod files and then stores them for potential later use. The default debuginfod server used by Parca is: https://debuginfod.elfutils.org
24+
25+
To use a different set of debuginfod servers to attempt to retrieve debuginfos from use the `--debuginfod-upstream-servers` flag.
4726

4827
## Additional Resources
4928

‎docs/debuginfos.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Debuginfos
2+
3+
Profiling raw data is just memory addresses that represent a function call stack and how often we observed the same stack. For example a function call stack might look like this:
4+
5+
```
6+
0x0b
7+
0x2a
8+
0x43
9+
```
10+
11+
In order for humans to understand what these memory addresses represent, we need a mapping from memory address to function names. That mapping is what is commonly referred to as "debuginfos".
12+
13+
Debuginfos are in form of sections within an [ELF](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format) binary (ELF is the format of binaries used on Linux). ELF binaries have sections, and some of these sections contain the debuginfos. Most commonly debuginfos are in the [DWARF format](https://dwarfstd.org/doc/DWARF5.pdf).
14+
15+
Let's look at example DWARF of a tiny C program.
16+
17+
```c
18+
#include <stdio.h>
19+
int main() {
20+
printf("Hello, World!");
21+
return 0;
22+
}
23+
```
24+
25+
Compile it, enabling DWARF to be emitted (`-g`):
26+
27+
```bash
28+
zig cc -o mainc -g -target x86_64-linux main.c
29+
```
30+
31+
> Note: Any C compiler could have been used here but Zig's cross-compile support is very convenient, as it works well on any platform.
32+
33+
And let's use the `dwarfdump` tool to print everything.
34+
35+
```dwarfdump
36+
$ dwarfdump --show-form mainc
37+
mainc: file format elf64-x86-64
38+
39+
.debug_info contents:
40+
0x00000000: Compile Unit: length = 0x00000047, format = DWARF32, version = 0x0004, abbr_offset = 0x0000, addr_size = 0x08 (next unit at 0x0000004b)
41+
42+
0x0000000b: DW_TAG_compile_unit
43+
DW_AT_producer [DW_FORM_strp] ("Homebrew clang version 13.0.1")
44+
DW_AT_language [DW_FORM_data2] (DW_LANG_C99)
45+
DW_AT_name [DW_FORM_strp] ("main.c")
46+
DW_AT_stmt_list [DW_FORM_sec_offset] (0x00000000)
47+
DW_AT_comp_dir [DW_FORM_strp] ("/Users/brancz/src/github.com/polarsignals/polarsignals/pkg/debuginfo/objfile/testdata")
48+
DW_AT_low_pc [DW_FORM_addr] (0x0000000000201e20)
49+
DW_AT_high_pc [DW_FORM_data4] (0x00000016)
50+
51+
0x0000002a: DW_TAG_subprogram
52+
DW_AT_low_pc [DW_FORM_addr] (0x0000000000201e20)
53+
DW_AT_high_pc [DW_FORM_data4] (0x00000016)
54+
DW_AT_frame_base [DW_FORM_exprloc] (DW_OP_reg6 RBP)
55+
DW_AT_GNU_all_call_sites [DW_FORM_flag_present] (true)
56+
DW_AT_name [DW_FORM_strp] ("main")
57+
DW_AT_decl_file [DW_FORM_data1] ("/Users/brancz/src/github.com/polarsignals/polarsignals/pkg/debuginfo/objfile/testdata/main.c")
58+
DW_AT_decl_line [DW_FORM_data1] (2)
59+
DW_AT_type [DW_FORM_ref4] (0x00000043 "int")
60+
DW_AT_external [DW_FORM_flag_present] (true)
61+
62+
0x00000043: DW_TAG_base_type
63+
DW_AT_name [DW_FORM_strp] ("int")
64+
DW_AT_encoding [DW_FORM_data1] (DW_ATE_signed)
65+
DW_AT_byte_size [DW_FORM_data1] (0x04)
66+
67+
0x0000004a: NULL
68+
```
69+
70+
Looking at this output, we see the compilation unit, which is the top level unit, and right underneath it a `DW_TAG_subprogram`, which is our `main` function. It has an attribute called `DW_AT_low_pc` with the form `DW_FORM_addr` (which means it is a `uint64`), that describes the start of our function's memory range, as well as the `DW_AT_high_pc` with the form `DW_FORM_data4` (which is a `int32`), which is the offset from the `DW_AT_low_pc` representing the end of our function's memory range, so the memory range is `[0x201e20, 0x201e36)`. And lastly, important for symbolization is the `DW_AT_name` attribute with the form `DW_FORM_strp`, which is a string.
71+
72+
Essentially what this means for symbolization: Thanks to this entry, we know that if we encountered a memory address between `0x201e20` and `0x201e36`, then it would be the `main` function.

‎docs/graph-tooltip-details.mdx‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Graph Tooltip Details
2+
3+
import BrowserWindow from "@site/src/components/BrowserWindow";
4+
5+
Here are some detailed explanations of the information that is displayed in the graph tooltip.
6+
7+
<BrowserWindow>
8+
9+
![Graph Tooltip](../static/img/tutorial/graph-tooltip.png)
10+
11+
</BrowserWindow>
12+
13+
## Cumulative
14+
15+
This is the total number of times the function has been called. This is the sum of all the samples that have been collected for this function. Cumulative samples are displayed in the graph as a solid line.
16+
17+
## Diff
18+
19+
When in compare mode, the Diff value will display the difference between the number of samples for the function in the current graph and the number of samples for the function in the graph that is being compared to. If the number is positive, it means that the function was called more times in the current graph than in the graph that is being compared to. If the number is negative, it means that the function was called more times in the graph that is being compared to than in the current graph. If the function was called the same number of times in both graphs, then the Diff value will be skipped.
20+
21+
<BrowserWindow>
22+
23+
![Graph Tooltip in Compare mode](../static/img/tutorial/graph-tooltip-diff.png)
24+
25+
</BrowserWindow>
26+
27+
## File
28+
29+
The name of the file that the function is in. If the file is not in the project, it will be displayed as an absolute path. If the file is in the project, it will be displayed as a relative path.
30+
31+
## Address
32+
33+
The address of the function in memory. This is a pointer to the function in memory. The addresses are displayed in hexadecimal and are prefixed with `0x`.
34+
35+
## Binary
36+
37+
The name of the binary that the function is in. Using the [Binary-based Color Stack](./flamegraph-binary-based-colour-stack.mdx) feature, you can identify the most expensive binaries in the rendered flamegraph.
38+
39+
## Build ID
40+
41+
The build ID of the binary that the function is in. The build ID is a unique identifier for the binary. It is used to match the binary to the debug information that is stored in the symbol server.

‎docs/parca-agent-labelling.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,10 @@ The agent does its best to enrich profiles with labels coming from various syste
4747
* `kernel_release`: The Linux kernel release used by the node as in `uname --kernel-release`.
4848
* `agent_revision`: The Git commit SHA Parca Agent was built from.
4949

50+
### Java
51+
52+
* `java`: `true` if the pid belongs to a Java process
53+
5054
## Configuration
5155

5256
Parca Agent supports relabeling in the same fashion as Prometheus.

‎docs/quickstart.mdx‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Quick Start
2+
3+
The easiest way to start with Parca is to obtain the pre-built statically-linked binary or the container.
4+
You can download the latest release of the binary from the Parca GitHub release pages ([Server](https://github.com/parca-dev/parca/releases) and [Agent](https://github.com/parca-dev/parca-agent/releases)).
5+
Alternatively, you can use the Parca container image from [the GitHub Container Registry](https://github.com/orgs/parca-dev/packages).
6+
7+
Once you have the binary or the container, you can start profiling your applications with Parca.
8+
9+
:::info Please select your environment and use the following commands to quickly get started
10+
:::
11+
12+
import Tabs from "@theme/Tabs";
13+
import TabItem from "@theme/TabItem";
14+
import WithVersions from '@site/src/components/WithVersions';
15+
import CodeBlock from '@theme/CodeBlock';
16+
17+
18+
<Tabs groupId="environment" queryString>
19+
<TabItem value="binary" label="Binary" default>
20+
21+
**Server**
22+
23+
1. Download the binary specific to your OS and architecture
24+
<WithVersions language="bash">
25+
{ versions =>
26+
<CodeBlock className="language-bash">
27+
curl -sL https://github.com/parca-dev/parca/releases/download/{versions.server}/parca_{versions.server.substring(1)}_`uname -s`_`uname -m`.tar.gz | tar xvfz -
28+
</CodeBlock>
29+
}
30+
</WithVersions>
31+
32+
2. Run Parca and access the Web UI on port 7070
33+
```bash
34+
# Get basic configuration
35+
curl -sL https://raw.githubusercontent.com/parca-dev/parca/main/parca.yaml > parca.yaml
36+
# Run Parca and access the Web UI on port 7070
37+
./parca --config=parca.yaml
38+
```
39+
40+
**Agent**
41+
42+
1. Download the binary specific to your architecture (only works on Linux)
43+
<WithVersions language="bash">
44+
{ versions =>
45+
<CodeBlock className="language-bash">
46+
curl -sL https://github.com/parca-dev/parca-agent/releases/download/{versions.agent}/parca-agent_{versions.agent.substring(1)}_`uname -s`_`uname -m`.tar.gz | tar xvfz -
47+
</CodeBlock>
48+
}
49+
</WithVersions>
50+
51+
2. Run Parca Agent and access the Web UI on port 7071 (assumes Parca is running on localhost:7070)
52+
```bash
53+
./parca-agent --node=test --remote-store-address=localhost:7070 --remote-store-insecure
54+
```
55+
56+
<br />
57+
58+
:::danger [Parca from Binary - Tutorial 5min ⏱️](/docs/binary)
59+
:::
60+
</TabItem>
61+
<TabItem value="container" label="Container">
62+
63+
**Server**
64+
65+
Run Parca and access the Web UI on port 7070
66+
<WithVersions language="bash">
67+
{ versions =>
68+
<CodeBlock className="language-bash">
69+
docker run --rm -it ghcr.io/parca-dev/parca:{versions.server} /parca
70+
</CodeBlock>
71+
}
72+
</WithVersions>
73+
74+
**Agent**
75+
76+
Run Parca Agent (requires privileged more) and access the Web UI on port 7071 (assumes Parca is running on localhost:7070)
77+
<WithVersions language="bash">
78+
{ versions =>
79+
<CodeBlock className="language-bash">
80+
docker run --rm -it --privileged ghcr.io/parca-dev/parca-agent:{versions.agent} /bin/parca-agent --node=docker-test
81+
</CodeBlock>
82+
}
83+
</WithVersions>
84+
85+
<br />
86+
87+
:::danger [Parca from Binary - Tutorial 5min ⏱️](/docs/binary)
88+
:::
89+
90+
</TabItem>
91+
<TabItem value="kubernetes" label="Kubernetes">
92+
93+
:::tip
94+
95+
To quickly try out the Parca and Parca Agent with Kubernetes, you create a [minikube](https://minikube.sigs.k8s.io/docs/) cluster with an actual virtual machine, e.g. Virtualbox:
96+
97+
```shell
98+
minikube start --driver=virtualbox
99+
```
100+
:::
101+
102+
1. Create the namespace (not strictly necessary but prevents a race with the next commands)
103+
```
104+
kubectl create namespace parca
105+
```
106+
107+
**Server**
108+
109+
2. Use to deploy Parca Server (API and UI)
110+
<WithVersions language="bash">
111+
{ versions =>
112+
<CodeBlock className="language-bash">
113+
kubectl apply -f https://github.com/parca-dev/parca/releases/download/{versions.server}/kubernetes-manifest.yaml
114+
</CodeBlock>
115+
}
116+
</WithVersions>
117+
118+
**Agent**
119+
120+
3. Use to deploy Parca Agent for all nodes
121+
<WithVersions language="bash">
122+
{ versions =>
123+
<CodeBlock className="language-bash">
124+
kubectl apply -f https://github.com/parca-dev/parca-agent/releases/download/{versions.agent}/kubernetes-manifest.yaml
125+
</CodeBlock>
126+
}
127+
</WithVersions>
128+
<br />
129+
130+
:::danger [Parca in Kubernetes - Tutorial 5min ⏱️](/docs/kubernetes)
131+
:::
132+
</TabItem>
133+
</Tabs>

‎docs/talks.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Resources
2+
3+
Several talks and blog posts have been written for both Parca Server and Agent.
4+
5+
## Talks
6+
7+
1. [Developing eBPF profiler for polyglot cloud-native applications](https://youtu.be/Gr1rrSzvqfg)
8+
2. [Achieving Zero-Instrumentation Monitoring with eBPF](https://youtu.be/g6B9Vbr88HM)
9+
3. [Conprof - Profiling in the cloud-native era](https://youtu.be/ficc6_6RYQk)
10+
4. [Leveraging Prometheus' TSDB for Conprof](https://www.youtube.com/watch?v=GwQZSS8tQH0)
11+
5. [Hands-on Introduction to Parca | Rawkode Live](https://www.youtube.com/watch?v=z3cEYklFdyo)
12+
6. [eBPF? Safety First!](https://youtu.be/oWHQrlE2-G8)
13+
7. [Profiling in the cloud-native era](https://archive.fosdem.org/2022/schedule/event/cloud_native_profiling/)
14+
8. [Building a Go Profiler Using Go](https://www.youtube.com/watch?v=OlHQ6gkwqyA)
15+
16+
For more videos and up-to-date content could be found on [Polar Signals' Playlist](https://youtube.com/playlist?list=PLhTDiyZ1B3JnWqRWKyGX3GbBCgIyo_aHf).
17+
18+
## Blog Posts
19+
20+
1. [Introduction to Parca- Part 1](https://www.polarsignals.com/blog/posts/2022/07/12/introducing-parca-sequel/)
21+
2. [Introduction to Parca - Part 2](https://www.polarsignals.com/blog/posts/2023/01/19/introduction-to-parca-agent/)
22+
3. [Design Decisions of a Continuous Profiler](https://www.polarsignals.com/blog/posts/2022/12/14/design-of-continuous-profilers/)
23+
4. [DWARF-based Stack Walking Using eBPF](https://www.polarsignals.com/blog/posts/2022/11/29/profiling-without-frame-pointers/)
24+
5. [System-wide profiling in Parca Agent](https://www.polarsignals.com/blog/posts/2022/08/24/system-wide-profiling/)
25+
6. [Parca now also in Grafana](https://www.polarsignals.com/blog/posts/2022/11/02/grafana-parca-core-plugin/)
26+
7. [Improved pprof.me](https://www.polarsignals.com/blog/posts/2022/10/12/improved-profile-sharing-service-pprof.me)

‎docusaurus.config.js‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,9 @@ module.exports = {
1414
projectName: "docusaurus", // Usually your repo name.
1515
scripts: [
1616
{
17-
src: "https://plausible.io/js/plausible.js",
17+
src: "/_vercel/insights/script.js",
1818
async: true,
1919
defer: true,
20-
"data-domain": "parca.dev",
2120
},
2221
],
2322
plugins: [
@@ -46,9 +45,9 @@ module.exports = {
4645
items: [
4746
{
4847
type: "doc",
49-
docId: "binary",
48+
docId: "quickstart",
5049
position: "left",
51-
label: "Download",
50+
label: "Quick Start",
5251
},
5352
{
5453
type: "doc",
@@ -103,6 +102,10 @@ module.exports = {
103102
{
104103
title: "Quick Start",
105104
items: [
105+
{
106+
label: "How to get started",
107+
to: "/quickstart",
108+
},
106109
{
107110
label: "Parca from Binary",
108111
to: "/docs/binary",

0 commit comments

Comments
 (0)