docs: update/add snap docs (#335)

* docs: add snap install for agent/server in quickstart * docs: update parca snap docs * docs: add parca-agent snap docs * docs: add docs for snap services for both agent/server * docs: update wordlist
parca-dev · Dec 12, 2023 · 38dfc1a · 38dfc1a · vercel · Dec 12, 2023
1 parent 7a17177
commit 38dfc1a
Show file tree

Hide file tree

Showing 7 changed files with 220 additions and 15 deletions.
diff --git a/docs/agent-server-snap-services.mdx b/docs/agent-server-snap-services.mdx
@@ -0,0 +1,53 @@
+# Parca and Parca Agent as snap services
+
+import BrowserWindow from "@site/src/components/BrowserWindow"
+
+:::tip
+
+You can configure both services quickly with a simple [cloud-init](https://cloudinit.readthedocs.io/en/latest/index.html) file:
+
+```yaml
+#cloud-config
+snap:
+  commands:
+    - [install, parca]
+    - [install, parca-agent, --classic]
+    - [set, parca-agent, remote-store-insecure=true]
+    - [set, parca-agent, remote-store-address=localhost:7070]
+    - [start, parca]
+    - [start, parca-agent]
+```
+
+:::
+
+## Setting up Parca
+
+You can install Parca using the [snap](https://snapcraft.io/about) package.
+
+```shell
+sudo snap install parca
+sudo snap start parca
+```
+
+This will start the Parca server on port `7070` and configure it to retrieve profiles from itself every 1 second automatically.
+
+Once Parca is running, you can navigate to the web interface on the browser.
+
+<BrowserWindow>
+
+![image](https://user-images.githubusercontent.com/8681572/133893063-8cc9fc8a-4d55-431d-80fc-6a2fe8de7019.png)
+
+</BrowserWindow>
+
+## Setting up Parca Agent
+
+You can install Parca Agent using the [snap](https://snapcraft.io/about) package.
+
+```shell
+sudo snap install --classic parca-agent
+sudo snap set parca-agent remote-store-insecure=true
+sudo snap set parca-agent remote-store-address=localhost:7070
+sudo snap start parca-agent
+```
+
+The `systemd` service will be collecting profiles from `docker.service`, `parca.service` and `parca-agent.service` that have been running on your system.
diff --git a/docs/parca-agent-snap.mdx b/docs/parca-agent-snap.mdx
@@ -0,0 +1,119 @@
+# Parca Agent from Snapcraft
+
+import BrowserWindow from "@site/src/components/BrowserWindow"
+
+You can install Parca Agent using the [snap](https://snapcraft.io/about) package.
+
+```shell
+sudo snap install --classic parca-agent
+```
+
+The snap has two primary modes of operation, one-shot or service.
+
+## Invoking `parca-agent` manually
+
+```shell
+parca-agent --help
+Usage: parca-agent
+
+Flags:
+  -h, --help                           Show context-sensitive help.
+      --log-level="info"               Log level.
+      --log-format="logfmt"            Configure if structured logging as JSON or as logfmt
+      --http-address="127.0.0.1:7071"  Address to bind HTTP server to.
+      --version                        Show application version.
+#...
+```
+
+You can find more information about invoking `parca-agent` manually in the [binary installation](https://www.parca.dev/docs/agent-binary) docs.
+
+## Using the `parca-agent` service
+
+The snap package also ships with a minimally configurable service that is managed by `snapd`.
+
+To get started without any customisation, once the snap is installed, invoke:
+
+```shell
+sudo snap start parca-agent
+```
+
+This will start `parca-agent` on http://localhost:7071.
+
+There are a few config options available for the snap service:
+
+```shell
+sudo snap get parca-agent
+Key                        Value
+http-address               :7071
+log-level                  info
+node                       test
+remote-store-address       grpc.polarsignals.com:443
+remote-store-bearer-token
+remote-store-insecure      false
+```
+
+Each can be customised individually. If a config value is changed, the service must be restarted for the changes to take effect. For example:
+
+```shell
+# Change the bind port
+sudo snap set parca-agent http-address=:8081
+
+# Restart the service
+sudo snap restart parca-agent
+```
+
+You can view the `parca-agent` service logs using the `snap logs` command:
+
+```shell
+sudo snap logs parca-agent
+2023-12-12T08:51:38Z systemd[1]: Started Service for snap application parca-agent.parca-agent-svc.
+2023-12-12T08:51:38Z parca-agent.parca-agent-svc[1405]: ooooooooo.                                                  .o.                                            .
+2023-12-12T08:51:38Z parca-agent.parca-agent-svc[1405]: `888   `Y88.                                               .888.                                         .o8
+2023-12-12T08:51:38Z parca-agent.parca-agent-svc[1405]:  888   .d88'  .oooo.   oooo d8b  .ooooo.   .oooo.         .8"888.      .oooooooo  .ooooo.  ooo. .oo.   .o888oo
+2023-12-12T08:51:38Z parca-agent.parca-agent-svc[1405]:  888ooo88P'  `P  )88b  `888""8P d88' `"Y8 `P  )88b       .8' `888.    888' `88b  d88' `88b `888P"Y88b    888
+2023-12-12T08:51:38Z parca-agent.parca-agent-svc[1405]:  888          .oP"888   888     888        .oP"888      .88ooo8888.   888   888  888ooo888  888   888    888
+2023-12-12T08:51:38Z parca-agent.parca-agent-svc[1405]:  888         d8(  888   888     888   .o8 d8(  888     .8'     `888.  `88bod8P'  888    .o  888   888    888 .
+2023-12-12T08:51:38Z parca-agent.parca-agent-svc[1405]: o888o        `Y888""8o d888b    `Y8bod8P' `Y888""8o   o88o     o8888o `8oooooo.  `Y8bod8P' o888o o888o   "888"
+2023-12-12T08:51:38Z parca-agent.parca-agent-svc[1405]:                                                                       d"     YD
+2023-12-12T08:51:38Z parca-agent.parca-agent-svc[1405]:                                                                       "Y88888P'
+2023-12-12T08:51:38Z parca-agent.parca-agent-svc[1405]:
+2023-12-12T08:51:38Z parca-agent.parca-agent-svc[1328]: level=info name=parca-agent ts=2023-12-12T08:51:38.368315839Z caller=main.go:502 msg="maxprocs: Leaving GOMAXPROCS=1: CPU quota undefined"
+2023-12-12T08:51:38Z parca-agent.parca-agent-svc[1328]: name=parca-agent ts=2023-12-12T08:51:38.447448683Z caller=main.go:724 msg=starting... node=test store=grpc.polarsignals.com:443
+```
+
+Now we can view the active profilers by visiting `http://localhost:7071`:
+<BrowserWindow>
+
+![image](../static/img/tutorial/active_profilers.png)
+
+</BrowserWindow>
+
+<br/>
+
+And all the discovered processes:
+<BrowserWindow>
+
+![image](../static/img/tutorial/processes.png)
+
+</BrowserWindow>
+
+<br/>
+
+Once Parca and Parca Agent are both running, you can navigate to the web interface on the browser.
+You should shortly see the `Select profile...` dropdown menu populate with the profiles that Parca is retrieving from itself and receiving from the Agent.
+
+<BrowserWindow>
+
+![image](../static/img/tutorial/cpu_sample_count.png)
+
+</BrowserWindow>
+
+<br/>
+
+Selecting `parca_agent_cpu_sample_count` as profile types and clicking the `Search` button will retrieve the profiles from Parca Agent for the time selection (default Last Hour).
+
+<BrowserWindow>
+
+![image](../static/img/tutorial/cpu_sample_count_select.png)
+
+</BrowserWindow>
diff --git a/docs/snap.mdx → docs/parca-snap.mdx b/docs/snap.mdx → docs/parca-snap.mdx
@@ -5,24 +5,23 @@ import BrowserWindow from "@site/src/components/BrowserWindow"
 You can install Parca using the [snap](https://snapcraft.io/about) package.
 
 ```shell
-sudo snap install parca --channel edge
+sudo snap install parca
 ```
 
 The snap has two primary modes of operation, one-shot or service.
 
 ## Invoking `parca` manually
 
 ```shell
-parca --help
 Usage: parca
 
 Flags:
-  -h, --help                                             Show context-sensitive help.
-      --config-path="parca.yaml"                         Path to config file.
-      --mode="all"                                       Scraper only runs a scraper that sends to a remote gRPC endpoint. All runs all components.
-      --log-level="info"                                 log level.
-      --port=":7070"                                     Port string for server
-      --cors-allowed-origins=CORS-ALLOWED-ORIGINS,...    Allowed CORS origins.
+  -h, --help                        Show context-sensitive help.
+      --config-path="parca.yaml"    Path to config file.
+      --mode="all"                  Scraper only runs a scraper that sends to a remote gRPC endpoint. All runs all components.
+      --http-address=":7070"        Address to bind HTTP server to.
+      --http-read-timeout=5s        Timeout duration for HTTP server to read request body.
+      --http-write-timeout=1m       Timeout duration for HTTP server to write response body.
 # ...
 ```
 
@@ -45,17 +44,20 @@ There are a few config options available for the snap service:
 ```shell
 sudo snap get parca
 Key                    Value
-enable-persistence     false
-log-level              info
-port                   7070
-storage-active-memory  536870912
+enable-persistence         false
+http-address               :7070
+log-level                  info
+remote-store-address       grpc.polarsignals.com:443
+remote-store-bearer-token
+remote-store-insecure      false
+storage-active-memory      536870912
 ```
 
 Each can be customised individually. If a config value is changed, the service must be restarted for the changes to take effect. For example:
 
 ```shell
 # Change the bind port
-sudo snap set parca port=8080
+sudo snap set parca http-address=:8080
 
 # Restart the service
 sudo snap restart parca

diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
@@ -129,5 +129,26 @@ minikube start --driver=virtualbox
 
 :::danger [Parca in Kubernetes - Tutorial 5min ⏱️](/docs/kubernetes)
 :::
+</TabItem>
+<TabItem value="snaps" label="Snaps">
+
+**Server**
+
+1. Use to deploy Parca Server (API and UI), listening on `0.0.0.0:7070`.
+
+    ```
+    sudo snap install parca
+    sudo snap start parca
+    ```
+
+**Agent**
+
+2. Use to install Parca Agent on a node with `snapd`.
+
+    ```
+    sudo snap install --classic parca-agent
+    sudo snap start parca
+    ```
+
 </TabItem>
 </Tabs>
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -122,7 +122,7 @@ module.exports = {
             },
             {
               label: "Parca from Snapcraft",
-              to: "/docs/snap",
+              to: "/docs/parca-snap",
             },
             {
               label: "Parca in Kubernetes",

diff --git a/sidebars.js b/sidebars.js
@@ -121,7 +121,14 @@ module.exports = {
         {
           type: "category",
           label: "Running Parca",
-          items: ["binary", "snap", "agent-binary", "systemd"],
+          items: [
+            "binary",
+            "parca-snap",
+            "agent-binary",
+            "parca-agent-snap",
+            "systemd",
+            "agent-server-snap-services"
+          ],
         },
         {
           type: "category",

diff --git a/wordlist.txt b/wordlist.txt
@@ -139,6 +139,7 @@ HUP
 iciclegraph
 infod
 IngressRoute
+init
 inlined
 integrations
 interactable
@@ -151,6 +152,7 @@ jit
 jitdump
 js
 justtrustme
+JSON
 JVM
 KASLR
 Katacoda
@@ -177,6 +179,7 @@ LLVM
 localhost
 LocalStoreDirectory
 LockPersonality
+logfmt
 LogLevel
 Loibl
 LSB