package profiler

Import Path
	cloud.google.com/go/profiler (on go.dev)

Dependency Relation
	imports 25 packages, and imported by 2 packages

Involved Source Files

	      heap.go
	      mutex.go
	   d➜ profiler.go
		Package profiler is a client for the Cloud Profiler service.

		Usage example:

		  import "cloud.google.com/go/profiler"
		  ...
		  if err := profiler.Start(profiler.Config{Service: "my-service"}); err != nil {
		      // TODO: Handle error.
		  }

		Calling Start will start a goroutine to collect profiles and upload to
		the profiler server, at the rhythm specified by the server.

		The caller must provide the service string in the config, and may provide
		other information as well. See Config for details.

		Profiler has CPU, heap and goroutine profiling enabled by default. Mutex
		profiling can be enabled in the config. Note that goroutine and mutex
		profiles are shown as "threads" and "contention" profiles in the profiler
		UI.
Package-Level Type Names (total 4, in which 1 are exported)

	/* sort exporteds by: alphabet | popularity */
	 type Config (struct)
		Config is the profiler configuration.

		Fields (total 15, in which 14 are exported)
			APIAddr string
				APIAddr is the HTTP endpoint to use to connect to the profiler
				agent API. Defaults to the production environment, overridable
				for testing.

			AllocForceGC bool
				AllocForceGC forces garbage collection before the collection of each heap
				profile collected to produce the allocation profile. This increases the
				accuracy of allocation profiling. It defaults to false.

			DebugLogging bool
				DebugLogging enables detailed debug logging from profiler. It
				defaults to false.

			EnableOCTelemetry bool
				When true, the agent sends all telemetries via OpenCensus exporter, which
				can be viewed in Cloud Trace and Cloud Monitoring.
				Default is false.

			Instance string
				Instance is the name of Compute Engine instance the profiler agent runs
				on. This is normally determined from the Compute Engine metadata server
				and doesn't need to be initialized. It needs to be set in rare cases where
				the metadata server is present but is flaky or otherwise misbehave.

			MutexProfiling bool
				MutexProfiling enables mutex profiling. It defaults to false.
				Note that mutex profiling is not supported by Go versions older
				than Go 1.8.

			NoAllocProfiling bool
				When true, collecting the allocation profiles is disabled.

			NoCPUProfiling bool
				When true, collecting the CPU profiles is disabled.

			NoGoroutineProfiling bool
				When true, collecting the goroutine profiles is disabled.

			NoHeapProfiling bool
				When true, collecting the heap profiles is disabled.

			ProjectID string
				ProjectID is the Cloud Console project ID to use instead of the one set by
				GOOGLE_CLOUD_PROJECT environment variable or read from the VM metadata
				server.

				Set this if you are running the agent in your local environment
				or anywhere else outside of Google Cloud Platform.

			Service string
				Service must be provided to start the profiler. It specifies the name of
				the service under which the profiled data will be recorded and exposed at
				the Profiler UI for the project. You can specify an arbitrary string, but
				see Deployment.target at
				https://github.com/googleapis/googleapis/blob/master/google/devtools/cloudprofiler/v2/profiler.proto
				for restrictions. If the parameter is not set, the agent will probe
				GAE_SERVICE environment variable which is present in Google App Engine
				environment.
				NOTE: The string should be the same across different replicas of
				your service so that the globally constant profiling rate is
				maintained. Do not put things like PID or unique pod ID in the name.

			ServiceVersion string
				ServiceVersion is an optional field specifying the version of the
				service. It can be an arbitrary string. Profiler profiles
				once per minute for each version of each service in each zone.
				ServiceVersion defaults to GAE_VERSION environment variable if that is
				set, or to empty string otherwise.

			Zone string
				Zone is the zone of Compute Engine instance the profiler agent runs
				on. This is normally determined from the Compute Engine metadata server
				and doesn't need to be initialized. It needs to be set in rare cases where
				the metadata server is present but is flaky or otherwise misbehave.

			/* one unexported ... *//* one unexported: */
			numProfiles int
				numProfiles is the number of profiles which should be collected before
				the profile collection loop exits.When numProfiles is 0, profiles will
				be collected for the duration of the program. For testing only.

		As Inputs Of (at least 3, in which 1 are exported)
			func Start(cfg Config, options ...option.ClientOption) error
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			func initializeConfig(cfg Config) error
			func start(cfg Config, options ...option.ClientOption) error
		As Types Of (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			  var config

	/* 3 unexporteds ... *//* 3 unexporteds: */
	 type agent (struct)
		agent polls the profiler server for instructions on behalf of a task,
		and collects and uploads profiles as requested.

		Fields (total 4, none are exported)
			/* 4 unexporteds ... *//* 4 unexporteds: */
			client pb.ProfilerServiceClient
			deployment *pb.Deployment
			profileLabels map[string]string
			profileTypes []pb.ProfileType
		Methods (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			(*T) createProfile(ctx context.Context) *pb.Profile
				createProfile talks to the profiler server to create profile. In
				case of error, the goroutine will sleep and retry. Sleep duration may
				be specified by the server. Otherwise it will be an exponentially
				increasing value, bounded by maxBackoff.

			(*T) profileAndUpload(ctx context.Context, p *pb.Profile)
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func initializeAgent(c pb.ProfilerServiceClient) (*agent, error)
		As Inputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func pollProfilerService(ctx context.Context, a *agent)

	 type allowUntilSuccess (struct)
		allowUntilSuccess is an object that will perform action till
		it succeeds once.
		This is a modified form of Go's sync.Once

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			done uint32
			m sync.Mutex
		Methods (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			(*T) do(f func() error) (err error)
				do calls function f only if it hasnt returned nil previously.
				Once f returns nil, do will not call function f any more.
				This is a modified form of Go's sync.Once.Do

		As Types Of (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			  var startOnce

	 type retryer (struct)

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			backoff gax.Backoff
			md grpcmd.MD
		Methods (only one, which is exported)
			(*T) Retry(err error) (time.Duration, bool)
		Implements (at least one exported)
			*T : github.com/googleapis/gax-go/v2.Retryer


Package-Level Functions (total 15, in which 1 are exported)

	 func Start(cfg Config, options ...option.ClientOption) error
		Start starts a goroutine to collect and upload profiles. The
		caller must provide the service string in the config. See
		Config for details. Start should only be called once. Any
		additional calls will be ignored.

	/* 14 unexporteds ... *//* 14 unexporteds: */
	 func abortedBackoffDuration(md grpcmd.MD) (time.Duration, error)
		abortedBackoffDuration retrieves the retry duration from gRPC trailing
		metadata, which is set by the profiler server.

	 func allocProfile(forceGC bool) (*profile.Profile, error)
		allocProfile collects a single heap profile, and removes all metrics but
		allocation metrics.

	 func debugLog(format string, e ...interface{})
	 func deltaAllocProfile(ctx context.Context, duration time.Duration, forceGC bool, prof *bytes.Buffer) error
		deltaAllocProfile collects an allocation profile by gathering a heap profile,
		sleeping for the specified duration, gathering another heap profile and
		subtracting the initial one from that. It then drops the in-use metrics from
		the profile. If requested, it forces the GC before taking each of the heap
		profiles, which improves the profile accuracy (see docs in
		https://golang.org/src/runtime/mprof.go on why).

	 func deltaMutexProfile(ctx context.Context, duration time.Duration, prof *bytes.Buffer) error
		deltaMutexProfile writes mutex profile changes over a time period specified
		with 'duration' to 'prof'.

	 func enableMutexProfiling() bool
	 func goHeapProfile() (*profile.Profile, error)
		goHeapProfile collects a heap profile. It returns an error if the metrics
		in the collected heap profile do not match the expected metrics.

	 func heapProfile(prof *bytes.Buffer) error
		heapProfile collects an in-use heap profile. The heap profiles returned by
		the runtime also include the heap allocation metrics. We zero those out
		since all allocations since program start are recorded, so these make the
		profile large and there is a separate alloc profile type which shows
		allocations from a set duration.

	 func initializeAgent(c pb.ProfilerServiceClient) (*agent, error)
		initializeAgent initializes the profiling agent. It returns an error if
		profile collection should not be started because collection is disabled
		for all profile types.

	 func initializeConfig(cfg Config) error
	 func mutexProfile() (*profile.Profile, error)
	 func pollProfilerService(ctx context.Context, a *agent)
		pollProfilerService starts an endless loop to poll the profiler
		server for instructions, and collects and uploads profiles as
		requested.

	 func start(cfg Config, options ...option.ClientOption) error
	 func withXGoogHeader(ctx context.Context, keyval ...string) context.Context
		withXGoogHeader sets the name and version of the application in
		the `x-goog-api-client` header passed on each request. Intended for
		use by Google-written clients.


Package-Level Variables (total 14, none are exported)

	/* 14 unexporteds ... *//* 14 unexporteds: */
	  var config Config
	  var dialGRPC func(ctx context.Context, opts ...option.ClientOption) (internal.ConnPool, error)
	  var getInstanceName func() (string, error)
	  var getProjectID func() (string, error)
		The functions below are stubbed to be overrideable for testing.

	  var getZone func() (string, error)
	  var mutexEnabled bool
	  var onGCE func() bool
	  var profilingDone chan bool
		For testing only.
		When the profiling loop has exited without error and this channel is
		non-nil, "true" will be sent to this channel.

	  var serviceRegexp *regexp.Regexp
	  var sleep func(ctx context.Context, d time.Duration) error
	  var startCPUProfile func(w io.Writer) error
	  var startOnce allowUntilSuccess
	  var stopCPUProfile func()
	  var writeHeapProfile func(w io.Writer) error
Package-Level Constants (total 11, none are exported)

	/* 11 unexporteds ... *//* 11 unexporteds: */
	const apiAddress = "cloudprofiler.googleapis.com:443"
	const backoffMultiplier = 1.3 // Backoff envelope increases by this factor on each retry.
	const initialBackoff time.Duration = 60000000000
	const instanceLabel = "instance"
	const languageLabel = "language"
	const maxBackoff time.Duration = 3600000000000
		Ensure the agent will recover within 1 hour.

	const retryInfoMetadata = "google.rpc.retryinfo-bin"
	const scope = "https://www.googleapis.com/auth/monitoring.write"
	const versionLabel = "version"
	const xGoogAPIMetadata = "x-goog-api-client"
	const zoneNameLabel = "zone"

The pages are generated with Golds v0.3.2-preview. (GOOS=darwin GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.