Skip to main content
skill CX Codex

pyroscope · julianobarbosa — Claude Code skill: what it does, how to install

Guides and configs for Grafana Pyroscope continuous profiling: Helm deployments, Go/Java/Python SDK setups, object storage, and trace correlation.

MIT 108 installs ★ 17 updated 2026-10-14

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add julianobarbosa/claude-code-skills --skill pyroscope -a claude-code
Open on GitHub

What pyroscope does

This skill equips coding agents with deployment blueprints and instrumentation patterns for Grafana Pyroscope. It includes Kubernetes Helm configurations for monolithic (-target=all) and microservices deployments, alongside SDK setup examples for Go, Java, and Python.

It outlines pull-based collection using Grafana Alloy pod annotations and eBPF, plus storage definitions for AWS S3, Azure Blob, and Google Cloud Storage. A running Pyroscope instance or ingestion pipeline is required to make use of the generated configurations.

What it helps with

  • deploy Grafana Pyroscope on Kubernetes via Helm
  • instrument Go, Java, or Python applications with profiling SDKs
  • configure profile scraping through Grafana Alloy pod annotations
  • link runtime profiles with OpenTelemetry distributed traces

Example prompts for the agent

  • Show how to initialize the Pyroscope Go SDK with CPU and memory profiling
  • Generate a Kubernetes deployment snippet with Grafana Alloy scraping annotations
  • Configure AWS S3 as the storage backend in Pyroscope Helm values

How to install pyroscope

1Skills CLI (Vercel)

npx skills add julianobarbosa/claude-code-skills --skill pyroscope -a claude-code

2Manually: put the files in place

~/.claude/skills/pyroscope/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/pyroscope/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about pyroscope

How to install pyroscope in Claude Code?

Run npx skills add julianobarbosa/claude-code-skills --skill pyroscope -a claude-code. You can also save the file directly to ~/.claude/skills/pyroscope/SKILL.md.

What does the pyroscope skill do?

It provides reference patterns and configuration guides for continuous profiling, Helm deployments, and client library instrumentation.

Which storage backends does Pyroscope support in this guide?

The guide contains ready-to-use configuration blocks for AWS S3, Azure Blob Storage, and Google Cloud Storage.

Source text

SKILL.md · MIT
---
name: pyroscope
description: >-
  Guide for Grafana Pyroscope continuous profiling. Use for Kubernetes Helm
  deployment, Go/Java/Python/.NET/Ruby/Node.js profiling, storage backends,
  trace-to-profile linking, and troubleshooting.
---

# Grafana Pyroscope Skill

Comprehensive guide for Grafana Pyroscope - the open-source continuous
profiling platform for analyzing application performance at the code level.

## What is Pyroscope?

Pyroscope is a **horizontally-scalable, highly-available, multi-tenant
continuous profiling system** that:

- **Collects profiling data continuously** with minimal overhead (~2-5% CPU)
- **Provides code-level visibility** with source-line granularity
- **Stores compressed profiles** in object storage (S3, GCS, Azure Blob)
- **Integrates with Grafana** for correlating profiles with metrics, logs, and traces
- **Supports multiple languages** - Go, Java, Python, .NET, Ruby, Node.js, Rust

## Architecture Overview

### Core Components

| Component | Purpose |
|-----------|---------|
| **Distributor** | Validates and routes incoming profiles to ingesters |
| **Ingester** | Buffers profiles in memory, compresses and writes to storage |
| **Querier** | Retrieves and processes profile data for analysis |
| **Query Frontend** | Handles query requests, caching, and scheduling |
| **Query Scheduler** | Manages per-tenant query queues |
| **Store Gateway** | Provides access to long-term profile storage |
| **Compactor** | Merges blocks, manages retention, handles deletion |

### Data Flow

**Write Path:**

```text
SDK/Alloy → Distributor → Ingester → Object Storage
                                   ↓
                             Blocks + Indexes
```

**Read Path:**

```text
Query → Query Frontend → Query Scheduler → Querier
                                             ↓
                                    Ingesters + Store Gateway
```

## Deployment Modes

### 1. Monolithic Mode (`-target=all`)

- All components in single process
- Best for: Development, small-scale deployments
- Query URL: `http://pyroscope:4040/`

### 2. Microservices Mode (Production)

- Each component runs independently
- Horizontally scalable
- Query URL: `http://pyroscope-querier:4040/`

```yaml
# Microservices deployment
architecture:
  microservices:
    enabled: true

querier:
  replicas: 3
distributor:
  replicas: 2
ingester:
  replicas: 3
compactor:
  replicas: 3
storeGateway:
  replicas: 3
```

## Quick Start - Kubernetes Helm

### Add Repository

```bash
helm repo add grafana https://grafana.github.io/helm-charts
helm repo update
```

### Install Single Binary

```bash
kubectl create namespace pyroscope
helm install pyroscope grafana/pyroscope -n pyroscope
```

### Install Microservices Mode

```bash
curl -Lo values-micro-services.yaml \
  https://raw.githubusercontent.com/grafana/pyroscope/main/operations/pyroscope/helm/pyroscope/values-micro-services.yaml

helm install pyroscope grafana/pyroscope \
  -n pyroscope \
  --values values-micro-services.yaml
```

## Profile Types

| Type | Description | Languages |
|------|-------------|-----------|
| **CPU** | Wall/CPU time consumption | All |
| **Memory** | Allocation objects/space, heap | Go, Java, .NET |
| **Goroutine** | Concurrent goroutines | Go |
| **Mutex** | Lock contention (count/duration) | Go, Java, .NET |
| **Block** | Thread blocking/delays | Go |
| **Exceptions** | Exception tracking | Python |

## Client Configuration Methods

### Method 1: SDK Instrumentation (Push Mode)

**Go SDK:**

```go
import "github.com/grafana/pyroscope-go"

pyroscope.Start(pyroscope.Config{
    ApplicationName: "my-app",
    ServerAddress:   "http://pyroscope:4040",
    ProfileTypes: []pyroscope.ProfileType{
        pyroscope.ProfileCPU,
        pyroscope.ProfileAllocObjects,
        pyroscope.ProfileAllocSpace,
        pyroscope.ProfileInuseObjects,
        pyroscope.ProfileInuseSpace,
        pyroscope.ProfileGoroutines,
        pyroscope.ProfileMutexCount,
        pyroscope.ProfileMutexDuration,
        pyroscope.ProfileBlockCount,
        pyroscope.ProfileBlockDuration,
    },
    Tags: map[string]string{
        "env": "production",
    },
})
```

**Java SDK:**

```java
PyroscopeAgent.start(
    new Config.Builder()
        .setApplicationName("my-app")
        .setServerAddress("http://pyroscope:4040")
        .setProfilingEvent(EventType.ITIMER)
        .setFormat(Format.JFR)
        .build()
);
```

**Python SDK:**

```python
import pyroscope

pyroscope.configure(
    application_name="my-app",
    server_address="http://pyroscope:4040",
    tags={"env": "production"},
)
```

### Method 2: Grafana Alloy (Pull Mode)

**Auto-instrumentation via Annotations:**

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    metadata:
      annotations:
        profiles.grafana.com/cpu.scrape: "true"
        profiles.grafana.com/cpu.port: "8080"
        profiles.grafana.com/memory.scrape: "true"
        profiles.grafana.com/memory.port: "8080"
        profiles.grafana.com/goroutine.scrape: "true"
        profiles.grafana.com/goroutine.port: "8080"
```

**Alloy Configuration:**

```river
pyroscope.scrape "default" {
  targets = discovery.kubernetes.pods.targets
  forward_to = [pyroscope.write.default.receiver]

  profiling_config {
    profile.process_cpu { enabled = true }
    profile.memory { enabled = true }
    profile.goroutine { enabled = true }
  }
}

pyroscope.write "default" {
  endpoint {
    url = "http://pyroscope:4040"
  }
}
```

### Method 3: eBPF Profiling (Linux)

**For compiled languages (C/C++, Go, Rust):**

```river
pyroscope.ebpf "default" {
  forward_to = [pyroscope.write.default.receiver]
  targets = discovery.kubernetes.pods.targets
}
```

## Storage Configuration

### Azure Blob Storage

```yaml
pyroscope:
  config:
    storage:
      backend: azure
      azure:
        container_name: pyroscope-data
        account_name: mystorageaccount
        account_key: ${AZURE_ACCOUNT_KEY}
```

### AWS S3

```yaml
pyroscope:
  config:
    storage:
      backend: s3
      s3:
        bucket_name: pyroscope-data
        region: us-east-1
        endpoint: s3.us-east-1.amazonaws.com
        access_key_id: ${AWS_ACCESS_KEY_ID}
        secret_access_key: ${AWS_SECRET_ACCESS_KEY}
```

### Google Cloud Storage

```yaml
pyroscope:
  config:
    storage:
      backend: gcs
      gcs:
        bucket_name: pyroscope-data
        # Uses GOOGLE_APPLICATION_CREDENTIALS
```

## Grafana Integration

### Data Source Configuration

```yaml
apiVersion: 1
datasources:
  - name: Pyroscope
    type: grafana-pyroscope-datasource
    access: proxy
    url: http://pyroscope-querier:4040
    isDefault: false
    editable: true
```

### Trace-to-Profile Linking

Enable span profiles to correlate traces with profiles:

**Go with OpenTelemetry:**

```go
import (
    "github.com/grafana/pyroscope-go"
    otelpyroscope "github.com/grafana/otel-profiling-go"
)

tp := trace.NewTracerProvider(
    trace.WithSpanProcessor(otelpyroscope.NewSpanProcessor()),
)
```

**Requirements:**

- Minimum span duration: 20ms
- Supported: Go, Java, .NET, Python, Ruby

## Resource Requirements

### Single Binary (Development)

```yaml
resources:
  requests:
    cpu: 500m
    memory: 512Mi
  limits:
    cpu: 1
    memory: 2Gi
```

### Microservices (Production)

| Component | CPU Request | Memory Request | Memory Limit |
|-----------|-------------|----------------|--------------|
| Distributor | 500m | 256Mi | 1Gi |
| Ingester | 1 | 8Gi | 16Gi |
| Querier | 100m | 256Mi | 1Gi |
| Query Frontend | 100m | 256Mi | 1Gi |
| Compactor | 1 | 8Gi | 16Gi |
| Store Gateway | 1 | 8Gi | 16Gi |

## Common Helm Values

```yaml
# Production values
architecture:
  microservices:
    enabled: true

pyroscope:
  persistence:
    enabled: true
    size: 50Gi

  config:
    storage:
      backend: s3
      s3:
        bucket_name: pyroscope-prod
        region: us-east-1

# High availability
ingester:
  replicas: 3
  terminationGracePeriodSeconds: 600

querier:
  replicas: 3

distributor:
  replicas: 2

compactor:
  replicas: 3
  terminationGracePeriodSeconds: 1200

storeGateway:
  replicas: 3

# Pod disruption budget
podDisruptionBudget:
  enabled: true
  maxUnavailable: 1

# Topology spread
topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: kubernetes.io/hostname
    whenUnsatisfiable: DoNotSchedule

# Monitoring
serviceMonitor:
  enabled: true

# Alloy for profile collection
alloy:
  enabled: true
```

## API Endpoints

### Ingestion

```bash
# Push profiles (Connect API)
POST /push.v1.PusherService/Push

# Legacy HTTP (pprof, JFR formats)
POST /ingest
```

### Query

```bash
# Merged profile
POST /querier.v1.QuerierService/SelectMergeProfile

# Flame graph data
POST /querier.v1.QuerierService/SelectMergeStacktraces

# Available labels
POST /querier.v1.QuerierService/LabelNames

# Profile types
POST /querier.v1.QuerierService/ProfileTypes

# Legacy render
GET /pyroscope/render?query={}&from=now-1h&until=now
```

### System

```bash
# Readiness
GET /ready

# Configuration
GET /config

# Metrics
GET /metrics
```

## Troubleshooting

### Diagnostic Commands

```bash
# Check pod status
kubectl get pods -n pyroscope -l app.kubernetes.io/name=pyroscope

# View ingester logs
kubectl logs -n pyroscope -l app.kubernetes.io/component=ingester --tail=100

# Check ring status
kubectl exec -it pyroscope-0 -n pyroscope -- \
  curl http://localhost:4040/ingester/ring

# Verify readiness
kubectl exec -it pyroscope-0 -n pyroscope -- \
  curl http://localhost:4040/ready

# Check configuration
kubectl exec -it pyroscope-0 -n pyroscope -- \
  curl http://localhost:4040/config
```

### Common Issues

**1. Ingester OOM:**

```yaml
ingester:
  resources:
    limits:
      memory: 16Gi
```

**2. Storage Authentication Failed:**

```bash
# Azure - verify RBAC
az role assignment create \
  --role "Storage Blob Data Contributor" \
  --assignee-object-id <principal-id> \
  --scope <storage-scope>
```

**3. High Cardinality Labels:**

```yaml
# Limit label cardinality
pyroscope:
  config:
    validation:
      max_label_names_per_series: 25
```

**4. Query Timeout:**

```yaml
pyroscope:
  config:
    querier:
      query_timeout: 5m
      max_concurrent: 8
```

## Reference Documentation

For detailed configuration by topic:

- **[Helm Deployment](references/helm-deployment.md)**: Complete Helm values reference
- **[Architecture](references/architecture.md)**: Component details and scaling
- **[SDK Instrumentation](references/sdk-instrumentation.md)**: Language SDK guides
- **[Troubleshooting](references/troubleshooting.md)**: Common issues and diagnostics

## External Resources

- [Official Pyroscope Documentation](https://grafana.com/docs/pyroscope/latest/)
- [Pyroscope Helm Chart](https://github.com/grafana/pyroscope/tree/main/operations/pyroscope/helm/pyroscope)
- [Pyroscope GitHub Repository](https://github.com/grafana/pyroscope)
- [Grafana Profiles Drilldown](https://grafana.com/docs/grafana/latest/explore/simplified-exploration/profiles/)

---

## Gotchas

- **Profile sampling rate per-application**: 100Hz on a busy service adds non-trivial overhead — profile in canary first.
- **Storage compaction blocks new writes during merge** — large compactions cause write stalls; chunk size and compaction window need tuning.
- **Tag cardinality explosion**: per-request tags balloon storage; cap tag values explicitly or storage doubles weekly.
- **Trace integration**: span → profile linking requires matching `traceparent` header propagation end-to-end; one un-instrumented hop loses linkage silently.
- **eBPF profiler vs SDK profiler**: different attribution, sometimes conflicting. Don't run both for the same service.
- **gRPC vs HTTP push**: same data, different rate limits at the ingester; HTTP push is throttled harder under load.

© julianobarbosa · MIT · julianobarbosa/claude-code-skills

Similar skills

All skills for DevOps and infrastructure →

pyroscope by other authors comes first.

pyroscope grafana pyroscope is a Claude Code skill for profiling apps with Grafana Pyroscope and inspecting flame graphs. It activates for CPU or memory hotspot investigations and profile comparisons. CX Codex +1 5,100installs opentelemetry grafana opentelemetry is a Claude Code skill that instruments services to route metrics, logs, and traces into Grafana Cloud or self-hosted Tempo, Mimir, and Loki. Triggers on OTLP setup and pipeline debugging. CX Codex +1 6,900installs beyla grafana Auto-instruments HTTP, gRPC, and database traffic using Grafana Beyla eBPF without application code changes. Useful when you need traces and RED metrics from prebuilt binaries. CX Codex +1 5,200installs otel-profiles ollygarden The otel-profiles Claude Code skill covers continuous profiling with OpenTelemetry. It comes into play when deploying the eBPF profiler, wiring a profiles pipeline, or investigating profiler errors. CX Codex +1 ★ 126repo stars loki-logging devops-skills loki-logging — a skill that walks your agent through Grafana Loki, Promtail and LogQL setup without leaving the editor. CX Codex +1 365installs copilot-otel-metrics microsoft copilot-otel-metrics configures GitHub Copilot OpenTelemetry export in VS Code, setting up local Grafana stacks or Azure collector infrastructure. CX Codex +1 ★ 1,627repo stars monitoring-observability OrchestKit monitoring-observability — a skill for Claude Code that configures Prometheus metrics, Grafana dashboards, and Langfuse v4 tracing. Activates when adding logging, distributed tracing, or LLM cost tracking. CX Codex +1 270installs

From the same set37

The whole set →

Project sponsors

Companies that keep this analytics open