dtrace_proc (4)
Leading comments
Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org> All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the docum...
NAME
dtrace_proc - a DTrace provider for tracing events related to user processesSYNOPSIS
Fn proc:::create struct proc * struct proc * int Fn proc:::exec char * Fn proc:::exec-failure int Fn proc:::exec-success char * Fn proc:::exit int Fn proc:::signal-clear int ksiginfo_t * Fn proc:::signal-discard struct thread * struct proc * int Fn proc:::signal-send struct thread * struct proc * intDESCRIPTION
The DTrace proc provider provides insight into events related to user processes: process and thread creation and termination events, and process signalling.The Fn proc:::create probe fires when a user process is created via the fork(2), vfork(2), pdfork(2), or rfork(2) system calls. In particular, kernel processes created with the kproc(9) KPI will not trigger this probe. The Fn proc:::create probe's first two arguments are the new child process and its parent, respectively. The third argument is a mask of rfork(2) flags indicating which process resources are to be shared between the parent and child processes.
The Fn proc:::exec probe fires when a process attempts to execute a file. Its argument is the specified filename for the file. If the attempt fails because of an error, the Fn proc:::exec-failure probe will subsequently fire, providing the corresponding errno(2) value in its first argument. Otherwise, the Fn proc:::exec-success probe will fire.
The Fn proc:::exit probe fires when a process exits or is terminated. Its argument is the corresponding SIGCHLD signal code; valid values are documented in the siginfo(3) manual page and defined in signal.h For example, when a process exits normally, the value of args[0] will be CLD_EXITED
The Fn proc:::signal-send probe fires when a signal is about to be sent to a process. The Fn proc:::signal-discard probe fires when a signal is sent to a process that ignores it. This probe will fire after the Fn proc:::signal-send probe for the signal in question. The arguments to these probes are the thread and process to which the signal will be sent, and the signal number of the signal. Valid signal numbers are defined in the signal(3) manual page. The Fn proc:::signal-clear probe fires when a pending signal has been cleared by one of the sigwait(2), sigtimedwait(2), or sigwaitinfo(2) system calls. Its arguments are the signal number of the cleared signal, and a pointer to the corresponding signal information. The Vt siginfo_t for the signal can be obtained from args[1]->ksi_info
ARGUMENTS
Though the proc provider probes use native Fx arguments types, standard D types for processes and threads are available. These are Vt psinfo_t and Vt lwpsinfo_t respectively, and are defined in /usr/lib/dtrace/psinfo.d This file also defines two global variables, curpsinfo and curlwpsinfo which provide representations of the current process and thread using these types.The fields of Vt psinfo_t are:
- Vt int pr_nlwp
- Number of threads in the process.
- Vt pid_t pr_pid
- Process ID.
- Vt pid_t pr_ppid
- Process ID of the parent process, or 0 if the process does not have a parent.
- Vt pid_t pr_pgid
- Process ID of the process group leader.
- Vt pid_t pr_sid
- Session ID, or 0 if the process does not belong to a session.
- Vt pid_t pr_uid
- Real user ID.
- Vt pid_t pr_euid
- Effective user ID.
- Vt pid_t pr_gid
- Real group ID.
- Vt pid_t pr_egid
- Effective group ID.
- Vt uintptr_t pr_addr
- Pointer to the Vt struct proc for the process.
- Vt string pr_psargs
- Process arguments.
- Vt u_int pr_arglen
- Length of the process argument string.
- Vt u_int pr_jailid
- Jail ID of the process.
The fields of Vt lwpsinfo_t are:
- Vt id_t pr_lwpid
- Thread ID.
- Vt int pr_flag
- Thread flags.
- Vt int pr_pri
- Real scheduling priority of the thread.
- Vt char pr_state
- Currently always 0.
- Vt char pr_sname
- Currently always `?'
- Vt short pr_syscall
- Currently always 0.
- Vt uintptr_t pr_addr
- Pointer to the Vt struct thread for the thread.
- Vt uintptr_t pr_wchan
- Current wait address on which the thread is sleeping.
FILES
- /usr/lib/dtrace/psinfo.d
- DTrace type and translator definitions for the proc provider.
EXAMPLES
The following script logs process execution events as they occur:
#pragma D option quiet
proc:::exec-success
{
printf("%s", curpsinfo->pr_psargs);
}
Note that the pr_psargs field is subject to the limit defined by the kern.ps_arg_cache_limit sysctl. In particular, processes with an argument list longer than the value defined by this sysctl cannot be logged in this way.