# Grafana Pyroscope: continuous profiling down to a single line of code > Pyroscope is Grafana's continuous profiling platform, and version 2.0 rewrote its storage layer to write profiles straight to object storage. Here is what the repository documents, what it leaves out, and when it is the wrong tool. **grafana/pyroscope** — Continuous Profiling Platform. Debug performance issues down to a single line of code. - Repository: https://github.com/grafana/pyroscope - Website: https://grafana.com/oss/pyroscope/ - Stars: 11,673 · Forks: 812 - Language: Go - License: AGPL-3.0 - Published: 2026-08-04 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/grafana-pyroscope ## What Pyroscope is for, and who actually needs it Pyroscope answers a question that metrics and traces do not: which function, and which line inside it, is consuming CPU or allocating memory. The README frames two use cases. Proactively, it is for reducing resource consumption and preventing latency issues. Reactively, it is for resolving incidents with line-level detail while a CPU, memory or I/O bottleneck is active. That second case is the one that separates it from a metrics dashboard. A CPU graph can show a spike at 14:03; a flame graph can show that the spike lives in one serialization routine called from three services. The audience is therefore platform and backend engineers who already have observability in place and have hit the ceiling of what counters can explain. It is not a starting point for a team with no instrumentation at all. Pyroscope assumes you can deploy a server, point clients at it, and read a flame graph. If nobody on the team has done profiling before, the tool will produce data that nobody interprets. ## The v2 write path: profiles go straight to object storage The architectural change in 2.0 is the removal of in-memory ingesters and local disks. According to the README, profiles are written directly to object storage, which the project says simplifies operations and lowers resource usage at scale. The write path routes profiles by service and writes them straight out. A background stage, described in the README as compaction-workers, merges small segments into larger blocks. Queries then fan out across object storage to build flame graphs in Grafana Profiles Drilldown. That is a meaningful trade. Dropping ingesters removes a stateful component that operators had to size, replicate and recover, and it makes the storage layer someone else's durability problem. The cost is latency and dependency: every query now touches object storage, and every write depends on it being reachable. The README does not document rollback behavior for the v2 architecture, and it does not discuss what happens to in-flight profiles when object storage is unavailable. Existing v1 deployments can opt in via a flag and, per the announcement, migrate without data loss; the migration guide is linked from the README rather than reproduced in it. ## Installing Pyroscope and sending your first profile The README gives three quick-start paths for running the server locally. The Docker one is the shortest. It publishes the server on port 4040, which the README states is the port Pyroscope listens on. ```bash docker run -it -p 4040:4040 grafana/pyroscope ``` On macOS or Linux, Homebrew is the alternative. The formula comes from the pyroscope-io tap, and the service is started separately. ```bash brew install pyroscope-io/brew/pyroscope brew services start pyroscope ``` There is also a binary path: download the archive for your OS and architecture from the latest release, unpack it and run it. ```bash tar xvf pyroscope_*.tar.gz ./pyroscope ``` Once the server is up, data has to arrive from somewhere. The README lists three routes: the Pyroscope SDKs, which push; Grafana Alloy, which can pull or push; and OTLP from OpenTelemetry-compatible sources such as the OpenTelemetry eBPF profiler. The repository keeps worked examples under examples/language-sdk-instrumentation, with separate directories for Go, Java and Python, plus examples/golang-pgo and examples/otel-collector. Visualization is handled by Grafana Profiles Drilldown, which the README describes as pre-installed in Grafana Cloud and Grafana OSS, so the step after sending data is opening the profiles view rather than installing a separate UI. For Kubernetes and Helm, Linux packages and building from source, the README defers to the Get started guide and the server documentation. ## Where Pyroscope stops being the right tool Continuous profiling is a sampling discipline, and the README does not present it as a general observability store. If your question is why a single request was slow, distributed tracing answers it and Pyroscope does not. If your question is whether error rates rose after a deploy, metrics answer it. Pyroscope is at its weakest when the problem is not resource consumption at all, which is most incidents. The operational dependency is the sharper limitation. In v2, object storage is not an optimization, it is the storage layer. A deployment without durable object storage has no place to write profiles. The README does not document rollback, so a team that migrates from v1 to v2 via the flag has to read the migration guide before flipping it. There is also a version split to watch: the Makefile carries HELM_FLAGS_V1 with --set architecture.storage.v1=true and --set architecture.storage.v2=fa, which tells you the Helm chart exposes architecture selection as explicit values rather than inferring it. Getting that wrong is a deployment problem, not a query problem. Finally, the licence. Pyroscope is AGPL-3.0, and the repository carries a separate LICENSING.md alongside LICENSE. That is a different posture from a permissive library, and it is worth reading before embedding the server in a product. ## Pyroscope versus Parca, Tempo and Prometheus The comparison people reach for most often is Parca, another continuous profiler. Both collect profiles and both visualize flame graphs, but the repository here is explicit about its own shape: a server component, SDKs, Alloy for pull or push collection, and Grafana Profiles Drilldown as the interface. The practical difference for a team already standardized on Grafana is integration surface. Pyroscope is documented as the profiling backend that Grafana's own UI reads, and the README treats Profiles Drilldown as the primary, queryless way to explore data. Choosing Parca means assembling a comparable pipeline around a different UI. Prometheus and Tempo are not competitors so much as neighbours. Prometheus stores numeric time series; a profile is a stack sample with a value attached, which is a different data model. Tempo stores traces, where the unit is a request rather than a sampled stack. The README positions Pyroscope alongside these rather than replacing them, and the OTLP path means profile data can arrive through the same OpenTelemetry plumbing a team already runs. If you want one backend for all three signals, that consolidation is not what this repository documents. ## Maintenance, releases and the AGPL-3.0 question The last push to the default branch was on 2026-08-24, the same date as the v2.3.0 release. Two further releases, v2.2.1 and v2.1.2, landed on 2026-08-06. The repository is not archived. That release cadence, combined with a go.mod pinned to go 1.26.0 and a toolchain of go1.26.8, means building from source tracks a recent Go toolchain rather than an old one; anyone building in CI with an older Go will need to upgrade it first. The Makefile is the real upgrade surface. It defines GO_MOD_PATHS across api/, lidia/, and several example modules, so a change to shared code can require coordinated bumps in more than one module. The licence situation deserves its own look: AGPL-3.0 with a LICENSING.md in the repository root. This article does not give legal advice, but the practical implication is that AGPL-3.0 is a copyleft licence with network-use terms, which is a different conversation from running a permissively licensed agent inside your own binaries. Teams that distribute or host derivative services should have that conversation before adoption, not after. ## Conclusion Adopt Pyroscope if you already run Grafana and want flame graphs tied to service and line-level detail, and if you can run object storage and accept AGPL-3.0 terms. Do not adopt it if you only need request traces or metrics, or if you cannot operate object storage. Before deploying, verify the v1 to v2 migration guide against your existing deployment and confirm which storage backend your Helm values select. ## FAQ ### How does Pyroscope work? It has three parts: a server that stores and processes profiling data and serves queries, clients that send data through the language SDKs, Grafana Alloy, or OTLP, and Grafana Profiles Drilldown for visualization. In the v2 architecture, profiles are routed by service and written directly to object storage, with compaction-workers merging small segments into larger blocks. ### How do I install Pyroscope? The README gives three options: docker run -it -p 4040:4040 grafana/pyroscope, brew install pyroscope-io/brew/pyroscope followed by brew services start pyroscope, or downloading the release archive, unpacking it and running the binary. The server listens on port 4040. ### What is Pyroscope used for? It is a continuous profiling platform for surfacing performance insights from applications, covering CPU, memory and I/O. The README describes proactive use, such as reducing resource consumption and preventing latency issues, and reactive use, such as resolving incidents with line-level detail. ### How do I use Grafana Pyroscope? Run the server, send profiles to it with a language SDK, Grafana Alloy, or OTLP from an OpenTelemetry-compatible source, then explore the data in Grafana Profiles Drilldown. The README states Profiles Drilldown is pre-installed in Grafana Cloud and Grafana OSS, so the step after sending data is opening the profiles view. ### What is Pyroscope used to measure? The README describes it as surfacing performance insights from applications so you can optimize resource usage such as CPU, memory and I/O operations. It is aimed at performance bottlenecks, both proactively and while an incident is active. ## Sources - [Official documentation](https://grafana.com/oss/pyroscope/) - [Official README](https://github.com/grafana/pyroscope#readme) - [Project repository](https://github.com/grafana/pyroscope) - [Release notes](https://github.com/grafana/pyroscope/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/grafana-pyroscope