Pyroscope

Pyroscope is a horizontally scalable, highly available, multi-tenant continuous profiling platform for storing and querying profiling data at the same scale Prometheus handles metrics or Loki handles logs. Instead of taking a one-off CPU or memory snapshot when something is already on fire, Pyroscope continuously collects profiles from running applications so teams can go back in time and see exactly which function, line, or code path was burning resources at any point in the past.

The project recently shipped a v2 architecture that removes ingesters and local disk from the write path entirely: profiles are routed by service straight to object storage (S3, GCS, Azure Blob, or filesystem), compaction workers merge small segments into larger blocks in the background, and queries fan out across object storage to rebuild flame graphs on demand. This mirrors the same Cortex/Mimir/Loki-style separation of write path, storage, and read path that Grafana Labs has refined across its observability stack, and it substantially lowers the operational footprint compared to the original ingester-based v1 design (which is still supported for existing deployments).

Data reaches the server through several paths: native Pyroscope SDKs for Go, Java, Python, Ruby, Node.js, .NET, and Rust; Grafana Alloy for pull- or push-based collection, including eBPF-based profiling that requires zero code changes; or OTLP from any OpenTelemetry-compatible source. On the read side, Grafana Profiles Drilldown (formerly Explore Profiles) gives you a queryless UI for slicing flame graphs by service, label, or time range, correlating a spike in memory usage with a deploy or a spike in latency with a specific goroutine.

Pyroscope began life as an independent open-source project (pyroscope-io) before being acquired and folded into Grafana Labs, and it now anchors the profiling pillar of Grafana’s LGTM (Loki, Grafana, Tempo, Mimir) observability stack — the same pattern of pull one thread, correlate across signals that Grafana has built its whole platform around.

What You Get

• A multi-tenant, horizontally scalable server for storing and querying continuous CPU, memory, and I/O profiles across an entire fleet of services
• A v2 write path that streams profiles directly to object storage with no ingesters or local disk, plus background compaction workers that merge segments into queryable blocks
• Official SDKs for Go, Java, Python, Ruby, Node.js, .NET, and Rust, plus zero-instrumentation eBPF profiling via Grafana Alloy and OTLP ingestion from OpenTelemetry pipelines
• Grafana Profiles Drilldown, a queryless UI pre-wired into Grafana for browsing flame graphs, diffing profiles across time or labels, and correlating with logs, metrics, and traces
• A symbolizer with debuginfod support for resolving native/compiled stack traces back to real function names and source lines
• Ready-to-run distributions via Docker, Homebrew, prebuilt binaries, and Helm charts for Kubernetes deployment

Common Use Cases

• Proactively hunting for CPU and memory hot paths before they turn into an incident or a cloud bill spike
• Reactively debugging an active production incident by drilling into exactly which function was consuming resources during the affected window
• Comparing flame graphs before and after a deploy to catch a performance regression introduced by a specific release
• Running continuous eBPF profiling across a Kubernetes cluster without adding SDKs to every service, using Grafana Alloy
• Correlating a latency spike in traces with the exact code path shown in a matching profile, inside the same Grafana view

Under The Hood

Architecture

Pyroscope’s binary starts in cmd/pyroscope/main.go, which wires a modular target system built on pkg/pyroscope — a single binary can run as all (monolithic) or as any individual component depending on the -target flag, following the same operational pattern Grafana uses for Mimir and Loki. In the newer v2 write path, the Distributor (pkg/distributor) validates and routes incoming pushes to Segment Writers, which write block segments directly to object storage and record metadata in a Metastore, while Compaction Workers merge small segments into larger blocks in the background — eliminating the ingester-and-local-disk hop that the original v1 pipeline still relies on for existing deployments. On the read side, a Query Frontend builds a query plan and dispatches it to Query Backends, which fan out across object storage and merge results into flame-graph-ready responses; a dedicated Symbolizer with debuginfod support resolves native stack frames back to real source lines. Sharding and membership rely on a consistent-hashing ring and gossip protocol supplied by Grafana’s shared dskit library, and multi-tenancy is enforced end-to-end via a required tenant header. The React/TypeScript UI lives in a separate ui/ module and talks to the backend through the same connect/gRPC APIs, deliberately kept dependency-light rather than pulling in a full component framework.

Tech Stack

The server is written in Go against a modern toolchain, using ConnectRPC and gRPC for internal and external APIs, Grafana’s dskit for distributed-systems primitives (hash ring, services lifecycle, limiter, tracing), HashiCorp’s Raft and raft-wal for metastore consensus, and MinIO’s Go client plus a Thanos-derived object-storage abstraction for talking to S3/GCS/Azure/filesystem backends; profiling data itself is stored in Parquet tables with a TSDB-style index and a custom symbol format inherited from the project’s pprof and Cortex/Mimir lineage. The frontend is a from-scratch rewrite on React 19, Vite, and TypeScript, managed with Yarn 4 (Berry) and deliberately avoiding heavyweight UI frameworks or state libraries in favor of small, dependency-light components. The project ships with extensive tooling around this stack: protobuf/OpenAPI code generation, a mockery-based mock generator, golangci-lint with a comprehensive rule set, and Make-driven build targets for cross-platform Docker images and Helm-based Kubernetes deployment.

Code Quality

The codebase shows a comprehensive testing culture, with test files sitting alongside implementation across nearly every package — distributor, compactor, ingester, querybackend, symbolizer, and more — using table-driven tests, the testify assert/require/mock libraries, and generated mocks for interfaces like object storage. Error handling follows an explicit, idiomatic Go style: errors are checked and wrapped with contextual messages, and structured logging via go-kit/log with leveled output is used throughout rather than ad hoc prints. Linting is enforced through a comprehensive golangci-lint configuration (revive, depguard, goconst, unconvert, unparam, misspell) and a documented import-ordering convention, backed by a broad CI workflow suite covering unit tests, fuzzing, Helm chart validation, and example verification on every change. Combined with an AGENTS.md that codifies conventions for both the Go backend and the separately-governed TypeScript frontend, this points to a mature, actively maintained engineering process rather than a project coasting on its size.

What Makes It Unique

What sets Pyroscope apart from most profiling tools is that it was rebuilt as a genuine distributed systems product rather than a profiler bolted onto a database: its newest architecture removes the ingester tier entirely and writes profiles straight to object storage, an operational simplification most competing profiling backends have not made. It also spans an unusually wide collection surface for a single tool — native SDKs, zero-instrumentation eBPF profiling via Grafana Alloy, and OTLP ingestion all land in the same store — and its tightest edge is being a first-class citizen inside Grafana’s broader LGTM stack, so a flame graph is one click away from the trace or log line that explains it, rather than living in a disconnected profiling silo.

Self-Hosting

Licensing Model

The project is licensed under AGPL-3.0-only by default (see LICENSE), as confirmed in the repository’s LICENSING.md. A small number of directories inherited from the original pre-Grafana Pyroscope project — lidia, og/pkg/agent/profiler, og/pkg/agent/ebpfspy, og/packages/pyroscope-flamegraph, and og/packages/pyroscope-models — are licensed under Apache-2.0 instead, and vendored third-party code retains its own upstream license. There is no dual-licensing or separate commercial license file in this repository.

Self-Hosting Restrictions

No ee/, enterprise/, or pro/ directory exists in this repository, and no license-check, feature-flag-gating, or “requires license” logic was found anywhere in the codebase. Everything needed to run the full server — both the v1 and v2 architectures, all query paths, and the symbolizer — appears to be available under the open AGPL license with no self-hosting caps that could be confirmed from the code or docs.

Enterprise Features

The README and documentation describe Grafana Cloud and Grafana Enterprise more broadly, but nothing in this specific repository gates individual Pyroscope features behind a separate enterprise tier; the codebase itself does not contain an enterprise feature set distinct from the open-source build.

Cloud vs Self-Hosted

Grafana Cloud ships Grafana Profiles Drilldown pre-installed, so cloud users can start sending profiles and exploring them immediately without standing up any infrastructure. Self-hosting requires running the Pyroscope server yourself (Docker, Homebrew, binary, or Helm) plus a Grafana instance with the Profiles Drilldown app installed to get the same visualization experience — the underlying profiling engine is the same open-source code in both cases, with Grafana Cloud primarily removing the operational burden rather than adding gated features.

License Key Required

No. No license key, activation step, or telemetry-gated feature was found in the self-hosted build; the project runs as a fully open AGPL-licensed binary out of the box.