Project: Grafana Pyroscope (Observability and Analysis / Observability)
File: profile-cli.md

aliases: /docs/phlare/latest/operators-guide/configuring/profile-cli/ /docs/phlare/latest/profile-cli/ /docs/pyroscope/latest/configure-server/profile-cli/ ../ingest-and-analyze-profile-data/profile-cli/ description: Getting started with the profile CLI tool. menuTitle: Profile CLI title: Profile CLI weight: 60 `profilecli` is a command-line utility that enables various productivity flows such as: Interacting with a running Pyroscope server to upload profiles, query data, and more Inspecting files Hint: Use the `help` command (`profilecli help`) to get a full list of capabilities as well as additional help information. You can install Profile CLI using a package or by compiling the code. On macOS, you can install Profile CLI using : ```bash brew install pyroscope-io/brew/profilecli ``` For other platforms, you can manually for your operating system and architecture and make it executable. For example, for Linux with the AMD64 architecture: Download and extract the package (archive). ```bash curl -fL https://github.com/grafana/pyroscope/releases/download/v1.1.5/profilecli1.1.5linux_amd64.tar.gz | tar xvz ``` Make `profilecli` executable: ```bash chmod +x profilecli ``` Optional: Make `profilecli` reachable from anywhere: ```bash sudo mv profilecli /usr/local/bin ``` To build from source code, you must have: Go installed (> 1.19). Either `$GOPATH` or `$GOBIN` configured and added to your `PATH` environment variable. To build the source code: Clone the repository. ```bash git clone git@github.com:grafana/pyroscope.git ``` Run the Go install command to build and install the package. ```bash cd pyroscope go install ./cmd/profilecli ``` The command places the `profilecli` executable in `$GOPATH/bin/` (or `$GOBIN/`) and make it available to use. The `profilecli` commands that interact with a Pyroscope server require a server URL and optionally authentication details. These can be provided as command-line flags or environment variables. Server URL `default: http://localhost:4040` The `--url` flag specifies the server against which the command will run. If using Grafana Cloud, an example URL could be `https://profiles-prod-001.grafana.net`. For local instances, the URL could look like `http://localhost:4040`. Authentication details. `default: <empty>` If using Grafana Cloud or authentication is enabled on your Pyroscope server, you will need to provide a username and password using the `--username` and `--password` flags respectively. For Grafana Cloud, the username will be the Stack ID and the password the generated API token. You can use environment variables to avoid passing flags to the command every time you use it, or to protect sensitive information. Environment variables have a `PROFILECLI_` prefix. Here is an example of providing the server URL and credentials for the `profilecli` tool: ```bash export PROFILECLIURL=<pyroscopeserver_url> export PROFILECLI_USERNAME=<username> export PROFILECLI_PASSWORD=<password> profilecli <command> ``` Using `profilecli` streamlines the process of uploading profiles to Pyroscope, making it a convenient alternative to manual HTTP requests. Ensure you have `profilecli` installed on your system by following the steps above. Have a profile file ready for upload. Note that you can only upload pprof files at this time. Identify the pprof file. Path to your pprof file: `path/to/your/pprof-file.pprof` Optional: Specify any extra labels. You can add additional labels to your uploaded profile using the `--extra-labels` flag. You can provide the name of the application that the profile was captured from via the `service_name` label (defaults to `profilecli-upload`). This will be useful when querying the data via `profilecli` or the

You can use the flag multiple times to add several labels. Construct and execute the Upload command. Here's a basic command template: ```bash export PROFILECLIURL=<pyroscopeserver_url> export PROFILECLI_USERNAME=<username> export PROFILECLI_PASSWORD=<password> profilecli upload --extra-labels=<labelname>=<labelvalue> <pproffilepath> ``` Example command: ```bash export PROFILECLI_URL=https://profiles-prod-001.grafana.net export PROFILECLIUSERNAME=myusername export PROFILECLIPASSWORD=mypassword profilecli upload path/to/your/pprof-file.pprof ``` Example command with extra labels: ```bash export PROFILECLI_URL=https://profiles-prod-001.grafana.net export PROFILECLIUSERNAME=myusername export PROFILECLIPASSWORD=mypassword profilecli upload \ --extra-labels=servicename=myapplication_name \ --extra-labels=cluster=us-east \ path/to/your/pprof-file.pprof ``` Check for successful upload. After running the command, you should see a confirmation message indicating a successful upload. If there are any issues, `profilecli` provides error messages to help you troubleshoot. You can use the `profilecli query` command to look up the available profiles on a Pyroscope server and read actual profile data. This can be useful for debugging purposes or for integrating profiling in CI pipelines (for example to facilitate ). You can use the `profilecli query series` command to look up the available profiles on a Pyroscope server. By default, it queries the last hour of data, though this can be controlled with the `--from` and `--to` flags. You can narrow the results down with the `--query` flag. See `profilecli help query series` for more information. Optional: Specify a Query and a Time Range. You can provide a label selector using the `--query` flag, for example: `--query='{servicename="myapplication_name"}'`. You can provide a custom time range using the `--from` and `--to` flags, for example, `--from="now-3h" --to="now"`. Construct and execute the Query Series command. Here's a basic command template: ```bash export PROFILECLIURL=<pyroscopeserver_url> export PROFILECLI_USERNAME=<username> export PROFILECLI_PASSWORD=<password> profilecli query series --query='{<labelname>="<labelvalue>"}' ``` Example command: ```bash export PROFILECLI_URL=https://profiles-prod-001.grafana.net export PROFILECLIUSERNAME=myusername export PROFILECLIPASSWORD=mypassword profilecli query series --query='{servicename="myapplication_name"}' ``` Example output: ```json { "name":"memory", "period_type":"space", "period_unit":"bytes", "profile_type":"memory:inuse_objects:count:space:bytes", "service_name":"myapplicationname", "type":"inuse_objects", "unit":"count", "cluster":"eu-west-1", "servicename":"myapplication_name" } ``` You can use the `profilecli query merge` command to retrieve a merged (aggregated) profile from a Pyroscope server. The command merges all samples found in the profile store for the specified query and time range. By default it looks for samples within the last hour, though this can be controlled with the `--from` and `--to` flags. The source data can be narrowed down with the `--query` flag in the same way as with the `series` command. Specify optional flags. You can provide a label selector using the `--query` flag, for example, `--query='{servicename="myapplication_name"}'`. You can provide a custom time range using the `--from` and `--to` flags, for example, `--from="now-3h" --to="now"`. You can specify the profile type via the `--profile-type` flag. The available profile types are listed in the output of the `profilecli query series` command. Construct and execute the Query Merge command. Here's a basic command template: ```bash export PROFILECLIURL=<pyroscopeserver_url> export PROFILECLI_USERNAME=<username> export PROFILECLI_PASSWORD=<password> profilecli query merge \ --profile-type=<profile_type> \ --query='{<labelname>="<labelvalue>"' \ --from="<from>" --to="<to>" ``` Example command: ```bash export PROFILECLI_URL=https://profiles-prod-001.grafana.net export PROFILECLIUSERNAME=myusername export PROFILECLIPASSWORD=mypassword profilecli query merge \ --profile-type=memory:inuse_space:bytes:space:bytes \ --query='{servicename="myapplication_name"}' \ --from="now-1h" --to="now" ``` Example output: ```bash level=info msg="query aggregated profile from profile store" url=http://localhost:4040 from=2023-12-11T13:38:33.115683-04:00 to=2023-12-11T14:38:33.115684-04:00 query={} type=memory:inuse_space:bytes:space:bytes PeriodType: space bytes Period: 524288 Time: 2023-12-11 13:59:59.999 -0400 AST Duration: 59m5 Samples: inuse_space/bytes[dflt] 115366240: 107 13 14 15 16 17 1 2 3 ... ```