A profiler handle, which can be used to stop the profiler with stopProfiler.

Since: 0.5.0.0

Run an action with a Profiler and the default Options.

Warning: This function spawns a Manager thread. Having multiple concurrent Manager threads is unsupported and unsafe.

Since: 0.5.0.0

Variant of withProfiler that accepts Options.

Since: 0.5.0.0

Variant of withProfiler that reads Options from the environment.

If GHC_STACK_PROFILER is unset or empty, no Profiler is started.

Since: 0.5.0.0

Start a Profiler with the default Options.

This function returns a Profiler handle, which can be used to stop the profiler with stopProfiler.

Warning: This function spawns a Manager thread. Having multiple concurrent Manager threads is unsupported and unsafe.

Warning: If the Profiler is not stopped before the program exits, some messages may not be written to the eventlog.

Since: 0.5.0.0

Variant of startProfiler that accepts Options.

Since: 0.5.0.0

Variant of startProfiler that accepts Options.

If GHC_STACK_PROFILER is unset or empty, no Profiler is started.

Since: 0.5.0.0

Stop a Profiler.

Since: 0.5.0.0

The options for withProfilerWith and startProfilerWith.

To construct options, modify defaultOptions using the fields:

wait :: Bool

Determines if sampler threads are started on creation or wait for a "start profiling" command on the eventlog socket. If you are using ghc-stack-profiler with eventlog-socket's control commands, this should be set to True. Otherwise, this should be False. The default is False.

shouldSample :: ThreadId -> Maybe ThreadLabel -> ShouldSample

Determines if the thread idenfied by the ThreadId should be sampled. The current ThreadLabel, returned by threadLabel, is passed as the second argument. If this function returns Never, the thread will never be sampled, even if its ThreadLabel changes. The default predicate always returns Yes. This function is not used for RTS threads or threads spawned by ghc-stack-profiler.

sampleRtsThreads :: Bool

Determines if builtin RTS threads should be sampled. The builtin RTS threads are the TimerManager and IOManager threads, and do not usually have an interesting call-stack profile. The default is False.

sampleProfilerThreads :: Bool

Determines if the threads spawned by ghc-stack-profiler should be sampled. The default is False.

sampleInterval :: Interval

Determines the sampling interval. The default is 10 milliseconds.

Since: 0.5.0.0

The default Options. See Options for the default values.

Since: 0.5.0.0

The sampling interval.

Since: 0.5.0.0

A thread filter, used to determine which threads should be sampled.

Used in the shouldSample field of Options.

Since: 0.5.0.0

A thread label, as set by labelThread.

Since: 0.5.0.0

The result type of a ThreadFilter.

Since: 0.5.0.0

A glob pattern.

Use fromString to construct glob patterns from strings.

A * matches any string, including the empty string.

One can remove the special meaning of * by preceding it with a backslash.

Since: 0.5.0.0

Test if the given Glob pattern matches the given String.

Since: 0.5.0.0

Construct a thread filter from an include Glob pattern.

If the thread label matches the given pattern, the thread filter returns Yes. Otherwise, the thread filter returns No. The thread filter never returns Never.

Since: 0.5.0.0

Construct a thread filter from an exclude Glob pattern.

If the thread label matches the given pattern, the thread filter returns No. Otherwise, the thread filter returns Yes. The thread filter never returns Never.

Since: 0.5.0.0

Construct a thread filter from include and exclude Glob patterns.

If the thread label matches the given include pattern and does not match the given exclude pattern, the thread filter returns Yes. Otherwise, the thread filter returns No. The thread filter never returns Never.

Since: 0.5.0.0

Read the Options from the environment.

GHC_STACK_PROFILER

If set to any non-empty value, read and return the options. Otherwise, return Nothing, which indicates the Profiler should not be started.

GHC_STACK_PROFILER_WAIT

If set to any non-empty value, wait is set to True.

GHC_STACK_PROFILER_SAMPLE_INCLUDE

If set, shouldSample is set to the ThreadFilter constructed using sampleInclude using the value as a Glob pattern. If GHC_STACK_PROFILER_SAMPLE_EXCLUDE is also set, sampleIncludeExclude is used.

GHC_STACK_PROFILER_SAMPLE_EXCLUDE

If set, shouldSample is set to the ThreadFilter constructed using sampleExclude using the value as a Glob pattern. If GHC_STACK_PROFILER_SAMPLE_INCLUDE is also set, sampleIncludeExclude is used.

GHC_STACK_PROFILER_SAMPLE_RTS_THREADS

If set to any non-empty value, sampleRtsThreads is set to True.

GHC_STACK_PROFILER_SAMPLE_PROFILER_THREADS

If set to any non-empty value, sampleProfilerThreads is set to True.

GHC_STACK_PROFILER_SAMPLE_INTERVAL

If set to any numeric value, sampleInterval is set to the Interval constructed using the value as milliseconds. If set to any non-numeric value, a warning is printed to stderr and the default sampleInterval is used.

Warning: This function reads environment variables, which is not thread-safe. See getenv.

Since: 0.5.0.0

A Manager handle, which can be used to stop the manager with stopManager.

Since: 0.5.0.0

Run an action with a new Manager.

The first argument indicates if sampler threads should wait for a call to startProfiling or a "start profiling" command on the eventlog socket. If you are using ghc-stack-profiler with eventlog-socket's control commands, this should be set to True.

The Manager is stopped when the action finishes.

Warning: This function spawns a Manager thread. Having multiple concurrent Manager threads is unsupported and unsafe.

Since: 0.5.0.0

Start a Manager.

The first argument indicates if sampler threads should wait for a call to startProfiling or a "start profiling" command on the eventlog socket. If you are using ghc-stack-profiler with eventlog-socket's control commands, this should be set to True.

Warning: This function spawns a Manager thread. Having multiple concurrent Manager threads is unsupported and unsafe.

Warning: The manager should be stopped with stopManager.

Since: 0.5.0.0

Stop a Manager.

This also stops every Sampler started by this manager.

Warning: If the Manager is not stopped before the program exits, some messages may not be written to the eventlog.

Since: 0.5.0.0

Start all Sampler threads.

This blocks until all Sampler threads have started.

Warning: This function deadlocks when used with a stopped Manager.

Since: 0.5.0.0

Start all Sampler threads.

This blocks until all Sampler threads have stopped.

Warning: This function deadlocks when used with a stopped Manager.

Since: 0.5.0.0

A Sampler handle, which can be used to stop the sampler with stopSampler.

Since: 0.5.0.0

Run an action with a Sampler for the current thread.

The Sampler is stopped when the action finishes.

Warning: If the action creates a new thread, it will not be sampled.

Since: 0.5.0.0

Start a sampler for the given ThreadId.

Warning: The sampler should be stopped using stopSampler or stopManager.

Since: 0.5.0.0

Start a sampler with the given Options.

This function ignores the wait field and uses the value that was passed to the Manager on creation.

Warning: The sampler should be stopped using stopSampler or stopManager.

Since: 0.5.0.0

Stop a Sampler thread.

Since: 0.5.0.0