From owner-svn-src-head@FreeBSD.ORG Sat Apr 18 20:31:59 2015 Return-Path: Delivered-To: svn-src-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id EF56EFA1; Sat, 18 Apr 2015 20:31:59 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id C3771DFB; Sat, 18 Apr 2015 20:31:59 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.9/8.14.9) with ESMTP id t3IKVxLA037876; Sat, 18 Apr 2015 20:31:59 GMT (envelope-from markj@FreeBSD.org) Received: (from markj@localhost) by svn.freebsd.org (8.14.9/8.14.9/Submit) id t3IKVxtC037875; Sat, 18 Apr 2015 20:31:59 GMT (envelope-from markj@FreeBSD.org) Message-Id: <201504182031.t3IKVxtC037875@svn.freebsd.org> X-Authentication-Warning: svn.freebsd.org: markj set sender to markj@FreeBSD.org using -f From: Mark Johnston Date: Sat, 18 Apr 2015 20:31:59 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r281701 - head/share/man/man9 X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 18 Apr 2015 20:32:00 -0000 Author: markj Date: Sat Apr 18 20:31:59 2015 New Revision: 281701 URL: https://svnweb.freebsd.org/changeset/base/281701 Log: SDT(9): add a section on SDT providers, mentioning the "sdt" provider. Add examples demonstrating how one can list available providers and the DTrace probes provided by a provider. Differential Revision: https://reviews.freebsd.org/D2166 Reviewed by: rpaulo MFC after: 2 weeks Modified: head/share/man/man9/SDT.9 Modified: head/share/man/man9/SDT.9 ============================================================================== --- head/share/man/man9/SDT.9 Sat Apr 18 20:10:19 2015 (r281700) +++ head/share/man/man9/SDT.9 Sat Apr 18 20:31:59 2015 (r281701) @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd March 8, 2015 +.Dd April 18, 2015 .Dt SDT 9 .Os .Sh NAME @@ -194,7 +194,37 @@ macros are used to create trace points. They are meant to be added to executable code and can be used to instrument the code in which they are called. +.Sh PROVIDERS +A number of kernel DTrace providers are available. +In general, these providers define stable interfaces and should be treated as +such: existing D scripts may be broken if a probe is renamed or its arguments +are modified. +However, it is often useful to define ad-hoc +.Nm +probes for debugging a subsystem or driver. +Similarly, a developer may wish to provide a group of +.Nm +probes without committing to their future stability. +Such probes should be added to the +.Ql sdt +provider instead of defining a new provider. .Sh EXAMPLES +The DTrace providers available on the current system can be listed with +.Bd -literal -offset indent +dtrace -l | sed 1d | awk '{print $2}' | sort -u +.Ed +.Pp +A detailed list of the probes offered by a given provider can be obtained by +specifying the provider using the +.Fl P +flag. +For example, to view the probes and argument types for the +.Ql sched +provider, run +.Bd -literal -offset indent +dtrace -lv -P sched +.Ed +.Pp The following probe definition will create a DTrace probe called .Ql icmp:::receive-unreachable , which would hypothetically be triggered when the kernel receives an ICMP packet