| Copyright | (C) 2026 Edward Kmett |
|---|---|
| License | UPL-1.0 AND BSD-3-Clause |
| Maintainer | Edward Kmett <ekmett@gmail.com> |
| Stability | experimental |
| Portability | GHC FFI; THC runtime services or native fallback implementation |
| Safe Haskell | Trustworthy |
| Language | Haskell2010 |
THC.Trace
Description
Context-local structured diagnostics. Selecting JFR never starts a JVM recording; an enabled sink is not evidence that a recording is consuming it.
Synopsis
- data Available a
- = Available a
- | Unsupported
- | Disabled
- | Denied
- | Unavailable
- data TraceSink
- getTraceSink :: IO (Available TraceSink)
- supportedTraceSinks :: IO (Available [TraceSink])
- setTraceSink :: TraceSink -> IO (Available ())
- traceEvent :: String -> IO (Available ())
- withSpan :: String -> IO a -> IO a
Documentation
An absent metric is not zero. Queries never enable JVM-wide monitoring.
fmap transforms a genuine value and preserves every non-value status:
>>>fmap (+ 1) (Available (41 :: Int))Available 42>>>fmap (+ 1) (Disabled :: Available Int)Disabled>>>map (fmap (+ 1)) [Unsupported, Disabled, Denied, Unavailable :: Available Int][Unsupported,Disabled,Denied,Unavailable]
Constructors
| Available a | A genuine value; its scope is specified by the query. |
| Unsupported | The runtime or provider does not implement this service. |
| Disabled | Supported, but its instrumentation or sink is switched off. |
| Denied | The current context or host security policy forbids access. |
| Unavailable | Normally supported, but no value is currently available. |
Instances
| Functor Available # | |
| Eq a => Eq (Available a) # | |
| Ord a => Ord (Available a) # | |
Defined in THC.Runtime.Types | |
| Show a => Show (Available a) # | |
Destination for context-local trace events. JFR selection does not start a recording; the host controls recording independently. In THC this sink also selects the original GHC event, marker and binary trace primops.
Constructors
| TraceOff | |
| TraceStderr | |
| TraceJFR | |
| TraceStderrAndJFR |
Instances
| Eq TraceSink # | |
| Ord TraceSink # | |
| Show TraceSink # | |
getTraceSink :: IO (Available TraceSink) Source #
Read the current context's sink selection without changing it.
supportedTraceSinks :: IO (Available [TraceSink]) Source #
List sink choices supported by the provider, not active recordings.
setTraceSink :: TraceSink -> IO (Available ()) Source #
Select the context's sink. The returned status distinguishes an accepted
change from an unsupported or unavailable control. The initial sink is
TraceOff; changing it also applies to GHC's original event primops, including
already compiled guest code.
traceEvent :: String -> IO (Available ()) Source #
Emit a UTF-8 label, preserving embedded NUL. Limited to 1 MiB encoded;
invalid Unicode surrogate characters become U+FFFD. Data is never evaluated
as code. Disabled emits nothing; native GHC reports Unsupported.
withSpan :: String -> IO a -> IO a Source #
Bracket the IO action with a context-owned span when tracing is enabled. Begin/end run masked; the action runs with the caller's original mask. Unsupported/disabled tracing still executes the action. Cleanup never replaces the action's exception, and synchronous cleanup failures do not replace a successful result. Asynchronous exceptions on successful cleanup still propagate. The span covers the IO action, not later evaluation of its returned lazy value. A sink change during the action applies to its end.