github.com/pyroscope-io/pyroscope@v0.37.3-0.20230725203016-5f6947968bd0/cmd/pyroscope/command/adhoc.go (about)

     1  package command
     2  
     3  import (
     4  	"github.com/spf13/cobra"
     5  
     6  	"github.com/pyroscope-io/pyroscope/pkg/adhoc"
     7  	"github.com/pyroscope-io/pyroscope/pkg/cli"
     8  	"github.com/pyroscope-io/pyroscope/pkg/config"
     9  )
    10  
    11  func newAdhocCmd(cfg *config.Adhoc) *cobra.Command {
    12  	vpr := newViper()
    13  
    14  	cmd := &cobra.Command{
    15  		Use:   "adhoc [flags] [<args>]",
    16  		Short: "Profile a process and save the results to be used in adhoc mode",
    17  		Long: `adhoc command is a complete toolset to profile a process and save the profiling
    18  results.
    19  
    20  These results are generated in two different ways:
    21  - Pyroscope stores the profiling data in its native format and data directory
    22  by default. These profiles are then available for analysis using pyroscope UI
    23  (the 'Adhoc Profiling' section), which requires a running pyroscope server.
    24  This output can be disabled with '--no-json-output'.
    25  - Pyroscope also generates profiling data in an external format.
    26  Depending on the number of generated profiles, pyroscope will generate either
    27  a file or a directory, in the directory where pyroscope is run from.
    28  The currently supported formats are standalone HTML (which can then be
    29  shared or directly open in a browser to analyze), pprof or collapsed
    30  (these last two can then be shared and used with either pyroscope UI or other
    31  tooling). The flag '--output-format' is used to specify this format.
    32  
    33  There are multiple ways to gather the profiling data, and not all of them are
    34  available for all the languages.
    35  Which way is better depends on several factors: what the language supports,
    36  how the profiled process is launched, and how the profiled process provides
    37  the profiled data.
    38  
    39  The different supported ways are:
    40  - exec. In this case, pyroscope creates a different process for the profiled
    41  program and uses a spy to directly gather profiling data. It's a useful way
    42  to profile a whole execution of some program that has no other pyroscope
    43  integration or way of exposing profiling data.
    44  It's the default mode for languages with a supported spy when either the spy
    45  name is specified (through '--spy-name' flag) or when the spyname is
    46  autodetected.
    47  - connect. Similar to exec, pyroscope uses a spy to gather profiling data,
    48  but instead of creating a new profiled process, it spies an already running
    49  process, indicated through '--pid' flag.
    50  - push. In this case, pyroscope creates a different process for the profiled
    51  program and launches an HTTP server with an ingestion endpoint. It's useful
    52  to profile programs already integrated with Pyroscope using its HTTP API.
    53  Push mode is used by default when no spy is detected and no '--url' flag is
    54  provided. It can also be override the default exec mode with the '--push' flag.
    55  - pull. In this case, pyroscope periodically connects to the URL specified
    56  thorugh '--url' where it tries to retrieve profiling data in any of the
    57  supported formats. In this case arguments are optional, and if provided,
    58  they are used to launch a new process before polling the URL.`,
    59  		DisableFlagParsing: true,
    60  		RunE: cli.CreateCmdRunFn(cfg, vpr, func(_ *cobra.Command, args []string) error {
    61  			return adhoc.Cli(cfg, args)
    62  		}),
    63  	}
    64  
    65  	cli.PopulateFlagSet(cfg, cmd.Flags(), vpr)
    66  	return cmd
    67  }