Skip to main content

Setup collection using Docker

Prerequisites:​

  • Linux 5.4 or newer.
  • Docker or Podman.

Get a Service Account Token and Project ID​

To send data to Polar Signals Cloud, you'll need:

  1. A service account token for authentication
  2. Your project ID to specify where the data should be sent

Please refer to the Generating Tokens documentation for detailed instructions.

Run the container​

Running the Polar Signals Agent using docker can be done easily with this command:

docker run --rm -it \
  -p 7071:7071 \
  --privileged \
  --pid host \
  -v /sys/fs/bpf:/sys/fs/bpf \
  -v /run:/run \
  -v /boot:/boot \
  -v /lib/modules:/lib/modules \
  -v /sys/kernel/debug:/sys/kernel/debug \
  -v /sys/fs/cgroup:/sys/fs/cgroup \
  -v /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket \
  ghcr.io/parca-dev/parca-agent:v0.45.0 \
  --remote-store-address=grpc.polarsignals.com:443 \
  --remote-store-bearer-token=<your-service-account-token> \
  --remote-store-grpc-headers=projectID=<your-project-id>

Let's go one by one what each of these flags are for:

  • --privileged The Polar Signals Agent needs to be privileged in order for the Linux Kernel to allow it to load the eBPF-based profiler into the host.
  • --pid host The Polar Signals Agent needs to be in the host PID namespace to allow it to discover metadata about processes. Without this all you would see is process IDs as metadata which is very hard to reason with.
  • Volumes:
    • /sys/fs/bpf This is required to be able to load the eBPF program which is essential for the whole agent to work.
    • /run This volume is used for discovering metadata from docker, crio, or other CRI compatible container runtimes. Optional but strongly recommended.
    • /boot This volume is used for discovering whether the Kernel is supported. Optional but strongly recommended.
    • /lib/modules This volume is used for symbolizing VDSO calls. Optional but strongly recommended.
    • /sys/kernel/debug This not strictly necessary but this is required for logging to work with eBPF. Optional but strongly recommended.
    • /sys/fs/cgroup This is required to discover metadata about processes running in containers/cgroups. Optional but strongly recommended.
    • /var/run/dbus/system_bus_socket This is required to be able to discover systemd unit metadata. Optional but strongly recommended.
  • ghcr.io/parca-dev/parca-agent:... The container image.
  • /bin/parca-agent The binary to run.
  • --remote-store-address=grpc.polarsignals.com:443 Configuring the agent to send the profiling data to Polar Signals Cloud.
  • --remote-store-bearer-token=<your-service-account-token> Authentication with Polar Signals Cloud using your service account token.
  • --remote-store-grpc-headers=projectID=<your-project-id> Specifies which project to send the profiling data to.