mirror of
https://github.com/ocaml-tracing/ocaml-trace.git
synced 2026-03-08 03:47:57 -04:00
23 lines
No EOL
11 KiB
HTML
23 lines
No EOL
11 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Trace (trace.Trace)</title><link rel="stylesheet" href="../../odoc.css"/><meta charset="utf-8"/><meta name="generator" content="odoc 2.2.0"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – <a href="../index.html">trace</a> » Trace</nav><header class="odoc-preamble"><h1>Module <code><span>Trace</span></code></h1><p>Trace.</p></header><nav class="odoc-toc"><ul><li><a href="#tracing">Tracing</a></li><li><a href="#collector">Collector</a></li></ul></nav><div class="odoc-content"><div class="odoc-spec"><div class="spec type anchored" id="type-span"><a href="#type-span" class="anchor"></a><code><span><span class="keyword">type</span> span</span><span> = int64</span></code></div><div class="spec-doc"><p>A span identifier.</p><p>The meaning of the identifier depends on the collector.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-user_data"><a href="#type-user_data" class="anchor"></a><code><span><span class="keyword">type</span> user_data</span><span> = </span><span>[ </span></code><ol><li id="type-user_data.Int" class="def constructor anchored"><a href="#type-user_data.Int" class="anchor"></a><code><span>| </span></code><code><span>`Int <span class="keyword">of</span> int</span></code></li><li id="type-user_data.String" class="def constructor anchored"><a href="#type-user_data.String" class="anchor"></a><code><span>| </span></code><code><span>`String <span class="keyword">of</span> string</span></code></li><li id="type-user_data.Bool" class="def constructor anchored"><a href="#type-user_data.Bool" class="anchor"></a><code><span>| </span></code><code><span>`Bool <span class="keyword">of</span> bool</span></code></li><li id="type-user_data.None" class="def constructor anchored"><a href="#type-user_data.None" class="anchor"></a><code><span>| </span></code><code><span>`None</span></code></li></ol><code><span> ]</span></code></div><div class="spec-doc"><p>User defined data, generally passed as key/value pairs to whatever collector is installed (if any).</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Collector"><a href="#module-Collector" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Collector/index.html">Collector</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>A global collector.</p></div></div><h3 id="tracing"><a href="#tracing" class="anchor"></a>Tracing</h3><div class="odoc-spec"><div class="spec value anchored" id="val-enabled"><a href="#val-enabled" class="anchor"></a><code><span><span class="keyword">val</span> enabled : <span>unit <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p>Is there a collector?</p><p>This is fast, so that the traced program can check it before creating any span or message</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-enter_span"><a href="#val-enter_span" class="anchor"></a><code><span><span class="keyword">val</span> enter_span :
|
||
<span>?__FUNCTION__:string <span class="arrow">-></span></span>
|
||
<span>__FILE__:string <span class="arrow">-></span></span>
|
||
<span>__LINE__:int <span class="arrow">-></span></span>
|
||
<span>?data:<span>(<span>unit <span class="arrow">-></span></span> <span><span>(string * <a href="#type-user_data">user_data</a>)</span> list</span>)</span> <span class="arrow">-></span></span>
|
||
<span>string <span class="arrow">-></span></span>
|
||
<a href="#type-span">span</a></span></code></div><div class="spec-doc"><p>Enter a span. A span is a delimited period of time with a start instant ("enter") and stop instant ("exit"), associated with some metadata about the code entering/exiting some piece of code.</p><p>In particular the entrypoint comes with the location of the code (you can use <code>__FILE__</code> and <code>__LINE__</code> directly in OCaml), a mandatory name, and some optional metadata in a JSON-like representation.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-exit_span"><a href="#val-exit_span" class="anchor"></a><code><span><span class="keyword">val</span> exit_span : <span><a href="#type-span">span</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Exit the span.</p><p>This should be called exactly once per span (even in case of exception). Once this is called, a timestamp might be recorded, and the span is considered finished and can't be used anymore</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-with_span"><a href="#val-with_span" class="anchor"></a><code><span><span class="keyword">val</span> with_span :
|
||
<span>?__FUNCTION__:string <span class="arrow">-></span></span>
|
||
<span>__FILE__:string <span class="arrow">-></span></span>
|
||
<span>__LINE__:int <span class="arrow">-></span></span>
|
||
<span>?data:<span>(<span>unit <span class="arrow">-></span></span> <span><span>(string * <a href="#type-user_data">user_data</a>)</span> list</span>)</span> <span class="arrow">-></span></span>
|
||
<span>string <span class="arrow">-></span></span>
|
||
<span><span>(<span><a href="#type-span">span</a> <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span>
|
||
<span class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>with_span ~__FILE__ ~__LINE__ name f</code> enters a new span <code>sp</code>, and calls <code>f sp</code>. <code>sp</code> might be a dummy span if no collector is installed. When <code>f sp</code> returns or raises, the span <code>sp</code> is exited.</p><p>This is the recommended way to instrument most code.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-message"><a href="#val-message" class="anchor"></a><code><span><span class="keyword">val</span> message :
|
||
<span>?span:<a href="#type-span">span</a> <span class="arrow">-></span></span>
|
||
<span>?data:<span>(<span>unit <span class="arrow">-></span></span> <span><span>(string * <a href="#type-user_data">user_data</a>)</span> list</span>)</span> <span class="arrow">-></span></span>
|
||
<span>string <span class="arrow">-></span></span>
|
||
unit</span></code></div><div class="spec-doc"><p><code>message msg</code> logs a message <code>msg</code> (if a collector is installed). Additional metadata can be provided.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">span</span> <p>the surrounding span, if any. This might be ignored by the collector.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-messagef"><a href="#val-messagef" class="anchor"></a><code><span><span class="keyword">val</span> messagef :
|
||
<span>?span:<a href="#type-span">span</a> <span class="arrow">-></span></span>
|
||
<span>?data:<span>(<span>unit <span class="arrow">-></span></span> <span><span>(string * <a href="#type-user_data">user_data</a>)</span> list</span>)</span> <span class="arrow">-></span></span>
|
||
<span><span>(<span><span>(<span><span><span>(<span class="type-var">'a</span>, <span class="xref-unresolved">Stdlib</span>.Format.formatter, unit, unit)</span> <span class="xref-unresolved">Stdlib</span>.format4</span> <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span>
|
||
unit</span></code></div><div class="spec-doc"><p><code>messagef (fun k->k"hello %s %d!" "world" 42)</code> is like <code>message "hello world 42!"</code> but only computes the string formatting if a collector is installed.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-set_thread_name"><a href="#val-set_thread_name" class="anchor"></a><code><span><span class="keyword">val</span> set_thread_name : <span>string <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Give a name to the current thread. This might be used by the collector to display traces in a more informative way.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-set_process_name"><a href="#val-set_process_name" class="anchor"></a><code><span><span class="keyword">val</span> set_process_name : <span>string <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Give a name to the current process. This might be used by the collector to display traces in a more informative way.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-counter_int"><a href="#val-counter_int" class="anchor"></a><code><span><span class="keyword">val</span> counter_int : <span>string <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Emit a counter of type <code>int</code>. Counters represent the evolution of some quantity over time.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-counter_float"><a href="#val-counter_float" class="anchor"></a><code><span><span class="keyword">val</span> counter_float : <span>string <span class="arrow">-></span></span> <span>float <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Emit a counter of type <code>float</code>. See <a href="#val-counter_int"><code>counter_int</code></a> for more details.</p></div></div><h3 id="collector"><a href="#collector" class="anchor"></a>Collector</h3><div class="odoc-spec"><div class="spec type anchored" id="type-collector"><a href="#type-collector" class="anchor"></a><code><span><span class="keyword">type</span> collector</span><span> = <span>(<span class="keyword">module</span> <a href="Collector/module-type-S/index.html">Collector.S</a>)</span></span></code></div><div class="spec-doc"><p>An event collector.</p><p>See <a href="Collector/index.html"><code>Collector</code></a> for more details.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-setup_collector"><a href="#val-setup_collector" class="anchor"></a><code><span><span class="keyword">val</span> setup_collector : <span><a href="#type-collector">collector</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>setup_collector c</code> installs <code>c</code> as the current collector.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <span class="value">Invalid_argument</span> <p>if there already is an established collector.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-shutdown"><a href="#val-shutdown" class="anchor"></a><code><span><span class="keyword">val</span> shutdown : <span>unit <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>shutdown ()</code> shutdowns the current collector, if one was installed, and waits for it to terminate before returning.</p></div></div></div></body></html> |