Permalink
Browse files

Add DTRACE and SYSTEMTAP howtos as User Guide

  • Loading branch information...
1 parent 0948779 commit 88c8bfd614477085bfc9f878d3812a47d16f25d4 @garazdawi garazdawi committed Jul 18, 2012
View
@@ -86,6 +86,8 @@ lib/os_mon/priv/obj/win32/
lib/runtime_tools/c_src/win32/
lib/runtime_tools/priv/lib/
lib/runtime_tools/priv/obj/
+lib/runtime_tools/doc/src/DTRACE.xml
+lib/runtime_tools/doc/src/SYSTEMTAP.xml
lib/tools/bin/win32/
lib/tools/c_src/win32/
lib/tools/obj/win32/
View
@@ -16,13 +16,13 @@ e.g. `foo_module:dtrace_probe("message goes here!")`.
Goals
-----
-1. Annotate as much of the Erlang VM as is practical.
+* Annotate as much of the Erlang VM as is practical.
* The initial goal is to trace file I/O operations.
-2. Support all platforms that implement DTrace: OS X, Solaris,
- and (I hope) FreeBSD and NetBSD.
-3. To the extent that it's practical, support SystemTap on Linux
- via DTrace provider compatibility.
-4. Allow Erlang code to supply annotations.
+* Support all platforms that implement DTrace: OS X, Solaris,
+ and (I hope) FreeBSD and NetBSD.
+* To the extent that it's practical, support SystemTap on Linux
+ via DTrace provider compatibility.
+* Allow Erlang code to supply annotations.
Supported platforms
-------------------
@@ -43,10 +43,10 @@ is `--with-dynamic-trace=systemtap`
Status
------
-As of R15B01, the dynamic trace code is included in the main OTP distribution,
+As of R15B01, the dynamic trace code is included in the OTP source distribution,
although it's considered experimental. The main development of the dtrace code
still happens outside of Ericsson, but there is no need to fetch a patched
-version of OTP to get the basic funtionality.
+version of the OTP source to get the basic funtionality.
Implementation summary
----------------------
@@ -66,9 +66,7 @@ following may be executed in a different Pthread:
* `efile_drv` command execution (C code)
* `efile_drv` status return (C code)
-**TODO: keep this description up-to-date.**
-
-Example output from `lib/dtrace/examples/efile_drv.d` while executing
+Example output from `lib/runtime_tools/examples/efile_drv.d` while executing
`file:rename("old-name", "new-name")`:
efile_drv enter tag={3,84} user tag some-user-tag | RENAME (12) | args: old-name new-name , 0 0 (port #Port<0.59>)
@@ -83,7 +81,7 @@ Example output from `lib/dtrace/examples/efile_drv.d` while executing
these two numbers form a unique ID for the I/O operation.
* `12` is the command number for the rename operation. See the
definition for `FILE_RENAME` in the source code file `efile_drv.c`
- or the `BEGIN` section of the D script `lib/dtrace/examples/efile_drv.d`.
+ or the `BEGIN` section of the D script `lib/runtime_tools/examples/efile_drv.d`.
* `old-name` and `new-name` are the two string arguments for the
source and destination of the `rename(2)` system call.
The two integer arguments are unused; the simple formatting code
@@ -101,8 +99,8 @@ So, where does the `some-user-tag` string come from?
At the moment, the user tag comes from code like the following:
- put(dtrace_utag, "some-user-tag"),
- file:rename("old-name", "new-name").
+ dyntrace:put_tag("some-user-tag"),
+ file:rename("old-name", "new-name"),
This method of tagging I/O at the Erlang level is subject to change.
View
@@ -11,24 +11,24 @@ introduction to Erlang DTrace support read [$ERL_TOP/HOWTO/DTRACE.md][].
Requisites
----------
-* Linux Kernel with UTRACE support
-
- check for UTRACE support in your current kernel:
+* Linux Kernel with UTRACE support
+
+ check for UTRACE support in your current kernel:
# grep CONFIG_UTRACE /boot/config-`uname -r`
CONFIG_UTRACE=y
- Fedora 16 is known to contain UTRACE, for most other Linux distributions
- a custom build kernel will be required.
- Check Fedora's SystemTap documentation for additional required packages
- (e.g. Kernel Debug Symbols)
-
-* SystemTap > 1.6
-
- A the time of writing this, the latest released version of SystemTap is
- version 1.6. Erlang's DTrace support requires a MACRO that was introduced
- after that release. So either get a newer release or build SystemTap from
- git yourself (see: http://sourceware.org/systemtap/getinvolved.html)
+ Fedora 16 is known to contain UTRACE, for most other Linux distributions
+ a custom build kernel will be required.
+ Check Fedora's SystemTap documentation for additional required packages
+ (e.g. Kernel Debug Symbols)
+
+* SystemTap > 1.6
+
+ A the time of writing this, the latest released version of SystemTap is
+ version 1.6. Erlang's DTrace support requires a MACRO that was introduced
+ after that release. So either get a newer release or build SystemTap from
+ git yourself (see: http://sourceware.org/systemtap/getinvolved.html)
Building Erlang
---------------
@@ -43,9 +43,11 @@ XML_APPLICATION_FILES = ref_man.xml
XML_REF3_FILES = dbg.xml dyntrace.xml erts_alloc_config.xml
XML_REF6_FILES = runtime_tools_app.xml
-XML_PART_FILES = part_notes.xml part_notes_history.xml
+XML_PART_FILES = part_notes.xml part_notes_history.xml part.xml
XML_CHAPTER_FILES = notes.xml notes_history.xml
+GENERATED_XML_FILES = DTRACE.xml SYSTEMTAP.xml
+
BOOK_FILES = book.xml
XML_FILES = \
@@ -78,6 +80,11 @@ DVIPS_FLAGS +=
# ----------------------------------------------------
# Targets
# ----------------------------------------------------
+$(XML_FILES): $(GENERATED_XML_FILES)
+
+%.xml: $(ERL_TOP)/HOWTO/%.md $(ERL_TOP)/make/emd2exml
+ $(ERL_TOP)/make/emd2exml $< $@
+
$(HTMLDIR)/%.gif: %.gif
$(INSTALL_DATA) $< $@
@@ -34,6 +34,9 @@
<preamble>
<contents level="2"></contents>
</preamble>
+ <parts lift="no">
+ <xi:include href="part.xml"/>
+ </parts>
<applications>
<xi:include href="ref_man.xml"/>
</applications>
@@ -42,7 +42,7 @@
</list>
<p>Both building with dynamic trace probes and using them is experimental and unsupported by Erlang/OTP. It is included as an option for the developer to trace and debug performance issues in their systems.</p>
<p>The original implementation is mostly done by Scott Lystiger Fritchie as an Open Source Contribution and it should be viewed as such even though the source for dynamic tracing as well as this module is included in the main distribution. However, the ability to use dynamic tracing of the virtual machine is a very valuable contribution which OTP has every intention to maintain as a tool for the developer.</p>
- <p>How to write <c>d</c> programs or <c>systemtap</c> scripts can be learned from books and from a lot of pages on the Internet. This manual page does not include any documentation about using the dynamic trace tools of respective platform. The <c>examples</c> directory of the <c>runtime_tools</c> application however contains comprehensive examples of both <c>d</c> and <c>systemtap</c> programs that will help you get started. Another source of information is the <c>DTRACE(.md)</c> and <c>SYSTEMTAP(.md)</c> files in the HOWTO folder in the Erlang source directory.</p>
+ <p>How to write <c>d</c> programs or <c>systemtap</c> scripts can be learned from books and from a lot of pages on the Internet. This manual page does not include any documentation about using the dynamic trace tools of respective platform. The <c>examples</c> directory of the <c>runtime_tools</c> application however contains comprehensive examples of both <c>d</c> and <c>systemtap</c> programs that will help you get started. Another source of information is the <seealso marker="DTRACE">dtrace</seealso> and <seealso marker="SYSTEMTAP">systemtap</seealso> chapters in the Runtime Tools Users' Guide.</p>
</description>
<funcs>
<func>
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE part SYSTEM "part.dtd">
+
+<part xmlns:xi="http://www.w3.org/2001/XInclude">
+ <header>
+ <copyright>
+ <year>2012</year><year>2012</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>Runtime Tools User's Guide</title>
+ <prepared>Lukas Larsson</prepared>
+ <docno></docno>
+ <date>2012-07-18</date>
+ <rev></rev>
+ <file>part.xml</file>
+ </header>
+
+ <description>
+ <p><em>Runtime Tools</em></p>
+ </description>
+
+ <xi:include href="DTRACE.xml"/>
+ <xi:include href="SYSTEMTAP.xml"/>
+</part>
+
+
+
+
View
@@ -266,8 +266,11 @@ parse(#state{code = true, type = blank, line = CB, code_blank = CBs} = S) ->
parse(#state{code = true,
code_blank = CB,
list_lvl = Lvl,
- type = {text, TxtLvl},
- line = Line} = S) when TxtLvl > Lvl ->
+ type = {Type, TxtLvl},
+ line = Line} = S) when TxtLvl > Lvl,
+ (Type == text orelse
+ Type == uolist orelse
+ Type == olist) ->
Data = code(strip_lvls(Lvl+1, Line)),
parse(get_line(put_chars(S#state{code_blank = []},
[strip_code_blank(Lvl+1, CB), Data])));

0 comments on commit 88c8bfd

Please sign in to comment.