Skip to content
1337skills 1337skills

Parca Commands

Parca is an open-source continuous profiling platform that uses eBPF to collect profiling data across your infrastructure with near-zero overhead. It consists of Parca Agent (eBPF-based collector) and Parca Server (storage and query engine).

Installation

Linux/Ubuntu

# Install Parca Server (binary)
curl -sL https://github.com/parca-dev/parca/releases/latest/download/parca_Linux_x86_64.tar.gz | tar xz
sudo mv parca /usr/local/bin/

# Install Parca Agent (binary)
curl -sL https://github.com/parca-dev/parca-agent/releases/latest/download/parca-agent_Linux_x86_64.tar.gz | tar xz
sudo mv parca-agent /usr/local/bin/

# Verify installation
parca --version
parca-agent --version

Docker

# Run Parca Server
docker run -d --name parca \
  -p 7070:7070 \
  ghcr.io/parca-dev/parca:latest \
  /parca --config-path=/parca.yaml

# Run Parca Agent
docker run -d --name parca-agent \
  --privileged \
  --pid=host \
  -v /sys:/sys:ro \
  -v /lib/modules:/lib/modules:ro \
  ghcr.io/parca-dev/parca-agent:latest \
  /parca-agent --node=my-host \
  --store-address=parca-server:7070 \
  --insecure

Parca Server Configuration

# parca.yaml — Parca Server config
object_storage:
  bucket:
    type: "FILESYSTEM"
    config:
      directory: "/var/lib/parca/data"

# Start server with config
# parca --config-path=parca.yaml --cors-allowed-origins="*"
# Start Parca Server with defaults (in-memory storage)
parca --config-path=parca.yaml

# Custom listen address
parca --config-path=parca.yaml --http-address=:7070

# Enable CORS for web UI access
parca --config-path=parca.yaml --cors-allowed-origins="*"

# With debug logging
parca --config-path=parca.yaml --log-level=debug

# Access the web UI
# http://localhost:7070

Parca Agent

# Start agent with eBPF profiling (requires root/privileged)
sudo parca-agent \
  --node=my-hostname \
  --store-address=localhost:7070 \
  --insecure

# Profile at custom frequency (default 19 Hz)
sudo parca-agent \
  --node=my-hostname \
  --store-address=localhost:7070 \
  --insecure \
  --profiling-cpu-sampling-frequency=49

# Profile specific cgroups only
sudo parca-agent \
  --node=my-hostname \
  --store-address=localhost:7070 \
  --insecure \
  --profiling-cgroup-path=/sys/fs/cgroup/system.slice/my-service.service

# Disable kernel stack unwinding
sudo parca-agent \
  --node=my-hostname \
  --store-address=localhost:7070 \
  --insecure \
  --profiling-disable-kernel

# Enable debug info extraction
sudo parca-agent \
  --node=my-hostname \
  --store-address=localhost:7070 \
  --insecure \
  --debuginfo-upload-disable=false

Kubernetes Deployment

# parca-server.yaml — Deploy Parca Server to Kubernetes
# Apply with: kubectl apply -f parca-server.yaml
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: parca
  namespace: parca
spec:
  replicas: 1
  selector:
    matchLabels:
      app: parca
  template:
    metadata:
      labels:
        app: parca
    spec:
      containers:
      - name: parca
        image: ghcr.io/parca-dev/parca:latest
        args:
        - /parca
        - --config-path=/etc/parca/parca.yaml
        - --cors-allowed-origins=*
        ports:
        - containerPort: 7070
---
apiVersion: v1
kind: Service
metadata:
  name: parca
  namespace: parca
spec:
  selector:
    app: parca
  ports:
  - port: 7070
    targetPort: 7070
# parca-agent-daemonset.yaml — Deploy Parca Agent as DaemonSet
# Apply with: kubectl apply -f parca-agent-daemonset.yaml
---
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: parca-agent
  namespace: parca
spec:
  selector:
    matchLabels:
      app: parca-agent
  template:
    metadata:
      labels:
        app: parca-agent
    spec:
      hostPID: true
      containers:
      - name: parca-agent
        image: ghcr.io/parca-dev/parca-agent:latest
        args:
        - /parca-agent
        - --store-address=parca.parca.svc:7070
        - --insecure
        - --node=$(NODE_NAME)
        env:
        - name: NODE_NAME
          valueFrom:
            fieldRef:
              fieldPath: spec.nodeName
        securityContext:
          privileged: true
        volumeMounts:
        - name: sys
          mountPath: /sys
          readOnly: true
      volumes:
      - name: sys
        hostPath:
          path: /sys
# Deploy using Helm
helm repo add parca https://parca-dev.github.io/helm-charts
helm repo update
helm install parca parca/parca -n parca --create-namespace
helm install parca-agent parca/parca-agent -n parca

pprof Integration

# Parca Agent can scrape pprof endpoints from Go applications
# Your Go app exposes /debug/pprof/ by default with net/http/pprof

# Configure scrape targets via Kubernetes annotations
# Add to your pod spec:
# metadata:
#   annotations:
#     parca.dev/port: "6060"

# Or configure static scrape targets in parca.yaml
# parca.yaml with scrape config
object_storage:
  bucket:
    type: "FILESYSTEM"
    config:
      directory: "/var/lib/parca/data"

scrape_configs:
- job_name: "my-go-service"
  scrape_interval: "15s"
  static_configs:
  - targets: ["my-service:6060"]
  profiling_config:
    pprof_config:
      process_cpu:
        enabled: true
        path: "/debug/pprof/profile"
        delta: true
      memory:
        enabled: true
        path: "/debug/pprof/heap"
        delta: true
      goroutine:
        enabled: true
        path: "/debug/pprof/goroutine"

Querying Profiles

# Access the Parca web UI at http://localhost:7070
# Use the query builder or write PromQL-like queries

# The Parca query language supports:
# - Selecting profiles by label matchers
# - Time range selection
# - Profile type selection (cpu, memory, goroutine, etc.)

# Example queries in the UI:
# process_cpu:cpu:nanoseconds:cpu:nanoseconds{node="my-host"}
# memory:alloc_objects:count:space:bytes{job="my-service"}

Comparing Profiles

# In the Parca web UI:
# 1. Select a profile from the timeline
# 2. Click "Compare" to enable comparison mode
# 3. Select a second profile from a different time range
# 4. View the differential flame graph

# Differential flame graphs show:
# - Red frames: increased resource usage
# - Green frames: decreased resource usage
# - Gray frames: unchanged

API Usage

# Query profiles via gRPC API
# Parca exposes a gRPC API on the same port as HTTP

# Install grpcurl for API exploration
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

# List available services
grpcurl -plaintext localhost:7070 list

# Query profile types
grpcurl -plaintext localhost:7070 parca.query.v1alpha1.QueryService/ProfileTypes

# Query profiles
grpcurl -plaintext -d '{
  "mode": "QUERY_MODE_MERGE",
  "report_type": "REPORT_TYPE_FLAMEGRAPH_ARROW",
  "query": "process_cpu:cpu:nanoseconds:cpu:nanoseconds{}"
}' localhost:7070 parca.query.v1alpha1.QueryService/Query

Troubleshooting

# Check if eBPF is supported
sudo bpftool prog list 2>/dev/null || echo "bpftool not available"

# Verify kernel version (4.18+ required for eBPF)
uname -r

# Check agent logs
journalctl -u parca-agent -f

# Check BTF support (required for CO-RE)
ls /sys/kernel/btf/vmlinux

# Test connectivity between agent and server
curl -s http://localhost:7070/api/v1/status

# Agent health check
curl -s http://localhost:7071/healthz

Quick Reference

ComponentDefault PortPurpose
Parca Server7070Storage, query, web UI
Parca Agent7071eBPF profiling agent
pprof endpoints6060Application profile scraping
FeatureDescription
eBPF profilingZero-instrumentation whole-system profiling
pprof scrapingPull profiles from Go/language endpoints
Differential viewCompare profiles across time
Label filteringQuery by node, pod, container, job
Debug infoAutomatic symbol resolution