From 88c8bfd614477085bfc9f878d3812a47d16f25d4 Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Wed, 18 Jul 2012 21:16:00 +0200 Subject: Add DTRACE and SYSTEMTAP howtos as User Guide --- .gitignore | 2 ++ HOWTO/DTRACE.md | 26 ++++++++++----------- HOWTO/SYSTEMTAP.md | 28 +++++++++++------------ lib/runtime_tools/doc/src/Makefile | 9 +++++++- lib/runtime_tools/doc/src/book.xml | 3 +++ lib/runtime_tools/doc/src/dyntrace.xml | 2 +- lib/runtime_tools/doc/src/part.xml | 42 ++++++++++++++++++++++++++++++++++ make/emd2exml.in | 7 ++++-- 8 files changed, 87 insertions(+), 32 deletions(-) create mode 100644 lib/runtime_tools/doc/src/part.xml diff --git a/.gitignore b/.gitignore index e64cc9ec81..3b0e21bde3 100644 --- a/.gitignore +++ b/.gitignore @@ -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/ diff --git a/HOWTO/DTRACE.md b/HOWTO/DTRACE.md index 1d495b0eaf..b719c68c59 100644 --- a/HOWTO/DTRACE.md +++ b/HOWTO/DTRACE.md @@ -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. diff --git a/HOWTO/SYSTEMTAP.md b/HOWTO/SYSTEMTAP.md index 094b61f1c0..ce9c0b2f0c 100644 --- a/HOWTO/SYSTEMTAP.md +++ b/HOWTO/SYSTEMTAP.md @@ -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 --------------- diff --git a/lib/runtime_tools/doc/src/Makefile b/lib/runtime_tools/doc/src/Makefile index d240b287c3..51d93df418 100644 --- a/lib/runtime_tools/doc/src/Makefile +++ b/lib/runtime_tools/doc/src/Makefile @@ -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) $< $@ diff --git a/lib/runtime_tools/doc/src/book.xml b/lib/runtime_tools/doc/src/book.xml index 3f0dd7d55e..ad7d709644 100644 --- a/lib/runtime_tools/doc/src/book.xml +++ b/lib/runtime_tools/doc/src/book.xml @@ -34,6 +34,9 @@ + + + diff --git a/lib/runtime_tools/doc/src/dyntrace.xml b/lib/runtime_tools/doc/src/dyntrace.xml index 9bcbdfc19a..f0149d0665 100644 --- a/lib/runtime_tools/doc/src/dyntrace.xml +++ b/lib/runtime_tools/doc/src/dyntrace.xml @@ -42,7 +42,7 @@

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.

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.

-

How to write d programs or systemtap 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 examples directory of the runtime_tools application however contains comprehensive examples of both d and systemtap programs that will help you get started. Another source of information is the DTRACE(.md) and SYSTEMTAP(.md) files in the HOWTO folder in the Erlang source directory.

+

How to write d programs or systemtap 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 examples directory of the runtime_tools application however contains comprehensive examples of both d and systemtap programs that will help you get started. Another source of information is the dtrace and systemtap chapters in the Runtime Tools Users' Guide.

diff --git a/lib/runtime_tools/doc/src/part.xml b/lib/runtime_tools/doc/src/part.xml new file mode 100644 index 0000000000..948d4a8020 --- /dev/null +++ b/lib/runtime_tools/doc/src/part.xml @@ -0,0 +1,42 @@ + + + + +
+ + 20122012 + Ericsson AB. All Rights Reserved. + + + 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. + + + + Runtime Tools User's Guide + Lukas Larsson + + 2012-07-18 + + part.xml +
+ + +

Runtime Tools

+ + + + + + + + + diff --git a/make/emd2exml.in b/make/emd2exml.in index 5bf7758be3..b677ef8ed4 100644 --- a/make/emd2exml.in +++ b/make/emd2exml.in @@ -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]))); -- cgit v1.2.3