Safe Haskell | Safe-Infered |
---|
Allows for remote monitoring of a running process over HTTP.
This module can be used to run an HTTP server that replies to HTTP requests with either an HTML page or a JSON object. The former can be used by a human to get an overview of a program's GC stats and the latter can be used be automated tools.
Typical usage is to start the monitor server on program startup
main = do forkServer "localhost" 8000 ...
and then periodically check the stats using a web browser or a command line tool like curl
$ curl -H "Accept: application/json" http://localhost:8000/
- forkServer :: ByteString -> Int -> IO ThreadId
Required configuration
To use this module you must first enable GC stats collection for your program. To enable GC stats collection, either run your program with
+RTS -T
or compile it with
-with-rtsopts=-T
The runtime overhead of -T
is very small so it's safe to always
leave it enabled.
JSON API
The HTTP server replies to GET requests to the host and port passed
to forkServer
. To get a JSON formatted response, the client must
set the Accept header to "application/json". The server returns
a JSON object with the following members:
bytes_allocated
- Total number of bytes allocated
num_gcs
- Number of garbage collections performed
max_bytes_used
- Maximum number of live bytes seen so far
num_bytes_usage_samples
- Number of byte usage samples taken
cumulative_bytes_used
- Sum of all byte usage samples, can be
used with
numByteUsageSamples
to calculate averages with arbitrary weighting (if you are sampling this record multiple times). bytes_copied
- Number of bytes copied during GC
current_bytes_used
- Current number of live bytes
current_bytes_slop
- Current number of bytes lost to slop
max_bytes_slop
- Maximum number of bytes lost to slop at any one time so far
peak_megabytes_allocated
- Maximum number of megabytes allocated
mutator_cpu_seconds
- CPU time spent running mutator threads. This does not include any profiling overhead or initialization.
mutator_wall_seconds
- Wall clock time spent running mutator threads. This does not include initialization.
gc_cpu_seconds
- CPU time spent running GC
gc_wall_seconds
- Wall clock time spent running GC
cpu_seconds
- Total CPU time elapsed since program start
wall_seconds
- Total wall clock time elapsed since start
par_avg_bytes_copied
- Number of bytes copied during GC, minus
space held by mutable lists held by the capabilities. Can be used
with
parMaxBytesCopied
to determine how well parallel GC utilized all cores. par_max_bytes_copied
- Sum of number of bytes copied each GC by
the most active GC thread each GC. The ratio of
parAvgBytesCopied
divided byparMaxBytesCopied
approaches 1 for a maximally sequential run and approaches the number of threads (set by the RTS flag-N
) for a maximally parallel run.
:: ByteString | Host to listen on (e.g. "localhost") |
-> Int | Port to listen on (e.g. 8000) |
-> IO ThreadId |
Start an HTTP server in a new thread. The server replies to GET requests to the given host and port. The host argument can be either a numeric network address (dotted quad for IPv4, colon-separated hex for IPv6) or a hostname (e.g. "localhost"). The client can set the desired response format (i.e. Content-Type) by setting the Accept header. At the moment two response formats are available: "application/json" and "text/html".
You can kill the server by killing the thread (i.e. by throwing it an asynchronous exception.)