ocaml-probes v0.17.0 (latest)

type t

Mutable representation of OCaml probes in the traced program. Not thread safe. Use with only one tracer thread.

exception Error of string

module Pid_or_self : sig ... end

type pid = int

type probe_name = string

type probe_state = {

name : probe_name;
enabled : bool;

}

type pattern

val pattern : string -> pattern

Constructor for patterns from string using Str.regexp notation.

type probe_desc =

| Name of probe_name
| Pair of probe_name * probe_name
(*
start and end probes semantics
*)
| Regex of pattern
(*
all probe names that match the regexp pattern
*)
| Predicate of probe_name -> bool
(*
all probe names for which the predicate is true
*)

type action =

| Enable
| Disable

type actions =

| All of action
(*
does not require knowing the available probe names
*)
| Selected of (action * probe_desc) list

val create : 
  ?check_prog:bool ->
  ?allow_gigatext:bool ->
  prog:string ->
  unit ->
  t

Reads the entire elf binary prog and extracts probes descriptions from its stapstd .notes section. Memory and time are linear in the size of the binary, so can be slow for large binaries. Does not require the program to be running.

check_prog is false by default. If check_prog is true, any changes to a running process by pid will be guarded by a check that the program executed by pid is prog.

allow_gigatext is false by default. If allow_gigatext is true, probe operations will be allowed even if prog maps its .text segment onto a 1GB hugepage, resulting in a 1GB copy-on-write and corresponding additional memory usage upon the first update.

val get_probe_names : t -> probe_name array

Returns the names of probes available in the program associated with t. The array is sorted and containts no duplicates.

val get_probe_states : ?atomically:bool -> t -> pid:pid -> probe_state array

Check which probes are enabled in the process pid.

The check is based on reading the values of counters associated with each probe name (see trace_existing_process).

If instances of a probe with a certain name have different states (i.e., some are enabled in the code at the probe site and some are not, or the code at probe site is inconsistent with the counter), the corresponding entry in the result array is undefined.

atomically indicates whether the check should be performed atomically using ptrace's PEEK, or not atomically using process_vm_readv (default).

val trace_existing_process : 
  ?atomically:bool ->
  ?force:bool ->
  t ->
  pid:pid ->
  actions:actions ->
  unit

Enable and disable probes in a running process pid according to actions.

Uses a counter per probe name to track the number of times a probe was enabled/disabled.

If a probe is disabled, trying to disable it again is an error.

If force is true, sets the state of the probes and counters to be as specified by the actions, rather than updating it based on the counters. force should be false when trace_existing_process is called from a library, to allow clients of the library to update the same probes correctly.

atomically indicates whether the update of counters should be performed atomically using ptrace's PEEK and POKE, or not atomically using a combination of ptrace's POKE and faster process_vm_read (default).

val trace_new_process : t -> args:string list -> actions:actions -> pid

Execute the program with args and enable probes as specified in actions, before running any code that might hit a probe. By default, all probes start as disabled when the program executed directly (without tracing). Disable actions are ignored.

Always performed atomically using ptrace.

val get_exe : pid -> string

Utility to get the name of the binary executed by process pid. Read from /proc/pid/exe

val set_verbose : bool -> unit

Control debug printing.

val set_allow_gigatext : t -> bool -> unit

Control gigatext policy: see create.

module Self : sig ... end

Get and update the state of probes in the same process. Not atomic.

module With_ptrace : sig ... end

For expert use only. Use trace_existing_process ~atomically:true and trace_new_process if possible, they do With_ptrace under the hood.

module Raw_ptrace : sig ... end

These don't actually have anything to do with probes, they're just exposed versions of the C stubs used to start a process paused with ptrace and then detach from it.

package ocaml-probes