nighttrace user’s guide · 2019. 3. 12. · iii preface scope of manual this manual is a...

NightTrace User’s GuideVersion 7.2

(RedHawkTM Linux®)

0898398-170 March 2011

Copyright 2011 by Concurrent Computer Corporation. All rights reserved. This publication or any part thereof is intended for use with Concurrentproducts by Concurrent personnel, customers, and end–users. It may not be reproduced in any form without the written permission of the pub-lisher.

The information contained in this document is believed to be correct at the time of publication. It is subject to change without notice. Concurrent Computer Corporation makes no warranties, expressed or implied, concerning the information contained in this document.

Concurrent Computer Corporation and its logo are registered trademarks of Concurrent Computer Corporation. All other Concurrent product names are trademarks of Concurrent while all other product names are trademarks or registered trademarks of their respective owners.

Linux® is used pursuant to a sublicense from the Linux Mark Institute.

NightStar’s integrated help system is based on Assistant, a QtTM utility. Qt is a trademark of Nokia Corporation.

Preface

Scope of Manual

This manual is a reference document and user’s guide for NightTraceTM - a graphical,interactive debugging and performance analysis tool.

Structure of Manual

The manual includes four major parts as shown below:

• Event Logging and Capture – Chapters 2 through 6

• Graphical Analysis – Chapters 7 through 17

• Programmatic Analysis – Chapter 18

• Reference – appendices and index

Man page descriptions of programs, system calls, subroutines, and file formats appear inthe system manual pages.

Syntax Notation

The following notation is used throughout this guide:

italic

Books, reference cards, and items that the user must specify appear in italictype. Special terms and comments in code may also appear in italic.

list bold

User input appears in list bold type and must be entered exactly asshown. Names of directories, files, commands, options and man page refer-ences also appear in list bold type.

list

Operating system and program output such as prompts and messages and list-ings of files and programs appears in list type. Keywords also appear inlist type.

window

Keyboard sequences and window features such as push buttons, radio buttons,menu items, labels, and titles appear in window type.

iii

NightTrace RT User’s Guide

[ ]

Brackets enclose command options and arguments that are optional. You donot type the brackets if you choose to specify such option or arguments.

{ }

Braces enclose mutually exclusive choices separated by the pipe (|) character,where one choice must be selected. You do not type the braces or the pipecharacter with the choice.

...

An ellipsis follows an item that can be repeated.

iv

Contents

Chapter 1 Introduction

User Trace Point Placement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2Kernel Trace Point Placement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2Timestamps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3Information Displayed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-4

Chapter 2 Using the NightTrace Logging API

Language-Specific Source Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-2Ada . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-2Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-3

Inter-Process Communication and Library Routines . . . . . . . . . . . . . . . . . . . . . .2-5Understanding NightTrace Library Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-6

trace_begin, Trace.begin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-7trace_event, Trace.event and their variants . . . . . . . . . . . . . . . . . . . . . . . . .2-13trace_enable, trace_disable, and their variants . . . . . . . . . . . . . . . . . . . . . . .2-20trace_flush, Trace.flush, trace_trigger, and Trace.trigger. . . . . . . . . . . . . . .2-24trace_set_thread_name, Trace.setThreadName . . . . . . . . . . . . . . . . . . . . . .2-26trace_close_thread, Trace.closeThread. . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-27trace_end, Trace.end. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-29trace_diag_mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-31trace_diag_func . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-32

Disabling Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-33Threads and Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-33Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-34

C Compilation and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-34Fortran Compilation and Linking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-34Ada Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-34Java Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-35

Chapter 3 Capturing User Events with ntraceud

The ntraceud Daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-1ntraceud Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2The Default User Daemon Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2ntraceud Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-3Invoking ntraceud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-6

Chapter 4 Capturing Kernel Events with ntracekd

The ntracekd Daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-1

v


ntracekd Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1ntracekd Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2ntracekd Invocations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5

Chapter 5 Application Illumination

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Illuminator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2NightLight. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Work Flow Illustration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Provided Illuminators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3Detail Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3

The NightLight Graphical User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12Help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14

Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16Navigation Panel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16Common Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18Select Programs with Debug Information . . . . . . . . . . . . . . . . . . . . . . . . . 5-19Define an Illuminator for each Program . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-21Select Predefined Illuminators for each Program . . . . . . . . . . . . . . . . . . . . 5-25Relink Illuminated Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-27Activate Illuminators in each Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-30Run Scripts to Launch Programs and NightTrace . . . . . . . . . . . . . . . . . . . 5-32

Session Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-37The Application Illumination Root Item . . . . . . . . . . . . . . . . . . . . . . . . . . 5-38Select Code with Debug Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-39

Context Menus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-39Building Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-42

Create, Customize, and Build Illuminators. . . . . . . . . . . . . . . . . . . . . . . . . 5-43Context Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-43Context Menu on Individual Illuminators . . . . . . . . . . . . . . . . . . . . . . 5-45

Relink Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-47Context Menus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-47Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-48Relink Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-48Illuminators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-50

Activation Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-52Settings For “main” Illuminator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-53Settings For Ordinary Illuminators . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-54Context Menu for an Illuminator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-54Context Menu for a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-55Context Menu for an Activation Set . . . . . . . . . . . . . . . . . . . . . . . . . . 5-56

Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-58New Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-58New Script from Activation Set (NightTrace in File Mode) . . . . . . . . 5-59New Script from Activation Set (NightTrace in Stream Mode),New Script from Activation Set (Launch Programs) . . . . . . . . . . . . . 5-60

Console. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-63Predefined Illuminators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-64

Detail Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-64

vi

Contents

main . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-64glibc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-64pthread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-65ccur_rt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-65cuda. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-65

Illuminator Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-66config.xml. . . . . . . . . . . . . . . . . . 5-66next_event.txt. . . . . . . . . . . . . . . . 5-66illuminator.h . . . . . . . . . . . . . . . . . . 5-66illuminator.map . . . . . . . . . . . . . . . . . 5-66illuminator_level.fmt . . . . . . . . . . . . . . . 5-66illuminator_level.o . . . . . . . . . . . . . . . . 5-66illuminator_level.list . . . . . . . . . . . . . . 5-67illuminator.o . . . . . . . . . . . . . . . . . . 5-67illuminator.vararg . . . . . . . . . . . . . . . 5-67

NightLight Command Line Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-68Commands for Manipulating an Illuminator . . . . . . . . . . . . . . . . . . . . . . . .5-68

nlight --create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-68nlight --populate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-71nlight --build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-72nlight --report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-72

Commands for Linking with Illuminators . . . . . . . . . . . . . . . . . . . . . . . . . .5-73nlight --gcc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-73nlight --g77 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-74nlight --cf77. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-74nlight --ada . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-74

Command for Activating and Deactivating Illuminators . . . . . . . . . . . . . . .5-74program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-74

! . . . . . . . . . . . . . . . . . . . . . . 5-74main[,options]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-74illuminator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-75level. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-75Using NightTrace with Illuminators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-75

Customizing an Illuminator with the Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-76Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-76Search Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-78Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-80

Event IDs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-80Limit on Size of Aggregates Recorded . . . . . . . . . . . . . . . . . . . . . . . . .5-80Include Functions without Dwarf Debug Info . . . . . . . . . . . . . . . . . . .5-80Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-81Object Filenames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-83

Detail Levels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-85Variables to Record. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-87Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-90

Create a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-90Customize a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-91Selecting Members of a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-94

Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-95Adding a Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-95Customizing a Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-95Adding a Function to a Group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-98

Customizing an Illuminator by Editing the config.xml File . . . . . . . . . . . . . . .5-100comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-100

vii


config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-100declare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-101defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-101exclude . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-102function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-102group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-103level. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-104

caller={yes|no} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-105frame={yes|no} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-105aggregate_limit=limit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-105args={yes|no}. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-105addr_args={yes|no} . . . . . . . . . . . . . . 5-106return_val={yes|no} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-106addr_ret={yes|no}. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-106variables={yes|no}. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-106errno={yes|no} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-106exclude={yes|no} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-106

options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-107event_ids=“N-[M]” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-107aggregate_limit=“limit” . . . . . . . . . . . . 5-107nodebug={yes|no} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-107underscores={yes|no} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-107std={yes|no} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-108iregex=“regex”, xregex=“regex” . . . . . . . . . 5-108filename=“filename” . . . . . . . . . . . . . . 5-108

variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-108wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-109wrapper_file_scope. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-109wrapper_post. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-109wrapper_pre . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-109wrapper_real . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-110

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-112

Chapter 6 Performance Tuning

Preventing Trace Event Loss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1Daemon Scheduling Adjustment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1Increasing Trace Buffer Size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2Programmatic Flushing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3

Conserving Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3Conserving Memory and Accelerating ntrace . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3

Chapter 7 Invoking NightTrace

Command-line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1Summary Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6

Command-line Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10Trace Event Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11Event Map Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11Table Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14

Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14String Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-15Pre-Defined Strings Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-17

viii

Contents

Format Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-20Session Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-24Trace Data Segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-25

Chapter 8 The NightTrace Main Window

Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-2File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-2View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-7Daemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-9Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-10Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-14Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-15

Export Profiles to NightTrace API Source File. . . . . . . . . . . . . . . . . . .8-17Timelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-19Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-27Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-29

Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-30Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-33Panels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-35Preferences Dialog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-39

General Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-40Timeline Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-41Font Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-42

NightStar Global Fonts Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-46Advanced Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-49

Chapter 9 Daemons Panel

Context Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-2Control Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-6Edit Daemon Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-8

General Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-9Trace Buffer Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-11

Trace Daemon Runtime Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-14Enabled Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-15

Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-16Edit Triggers Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-17

Streaming Memory Usage Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-18Streaming Memory Usage Control Dialog. . . . . . . . . . . . . . . . . . . . . . . . . .9-19

Chapter 10 Trace Segments Panel

Trace Segments Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-1Context Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-2Control Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-4

Chapter 11 Events Panel

Textual Event Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-1Context Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-3

ix


Chapter 12 Timeline Panels

Default Timeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1Current Timeline Indicator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2Global Ruler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2Interval Ruler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3Event Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-5Event Description Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6Keyboard Traversal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-7Creating Timeline Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-8

Event Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-10State Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-11Data Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-12

Data Graph Options Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-13Drawing and Coloring Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-16Color Selection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-17Standard Color Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-19

Interval Ruler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-20Global Ruler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-20Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-20Data Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-20

Chapter 13 Profiles Panels

Profile Definition Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1Control Buttons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-9

Summarizing Statistical Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-11Condition Summaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-11State Summaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-11Summary Scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-11

Summary Script Environment Variables . . . . . . . . . . . . . . . . . . . . . . 13-12Profile Status List Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-13

Profile Status List Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-13Context Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-14

Chapter 14 Event Descriptions Panel

Chapter 15 Tags List Panel

Creating Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1Tags List Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-2Context Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-2Control Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-3

Chapter 16 Using Expressions

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1Operands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-4

Function Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-9

x

Contents

Function Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-11String Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-16

strcmp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-16strncmp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-17

Trace Event Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-18id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-20arg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-21arg_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-22arg_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-23arg_long_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-24arg_long_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-25blk_arg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-26blk_arg_bits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-27blk_arg_char() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-28blk_arg_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-29blk_arg_flt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-30blk_arg_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-31blk_arg_long_bits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-32blk_arg_long_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-33blk_arg_long_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-34blk_arg_long_ubits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-35blk_arg_short() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-36blk_arg_string() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-37blk_arg_ubits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-38blk_arg_uchar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-39blk_arg_uint() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-40blk_arg_ulong_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-41blk_arg_ushort() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-42num_args() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-43pid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-44thread_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-45task_id(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-46tid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-47cpu() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-48offset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-49time() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-50node_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-51pid_table_name(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-52tid_table_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-53node_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-54process_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-55task_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-56thread_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-57Multi-Event Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-58

event_gap(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-58event_matches() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-59

State Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-60Start Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-60

start_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-62start_arg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-63start_arg_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-64start_arg_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-65start_arg_long_dbl(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-66start_arg_long_long(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-67

xi


start_blk_arg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-68start_blk_arg_bits(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-69start_blk_arg_char() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-70start_blk_arg_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-71start_blk_arg_flt(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-72start_blk_arg_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-73start_blk_arg_long_bits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-74start_blk_arg_long_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-75start_blk_arg_long_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-76start_blk_arg_long_ubits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-77start_blk_arg_short() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-78start_blk_arg_string() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-79start_blk_arg_ubits(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-80start_blk_arg_uchar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-81start_blk_arg_uint() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-82start_blk_arg_ulong_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-83start_blk_arg_ushort() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-84start_num_args(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-85start_pid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-86start_thread_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-87start_task_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-88start_tid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-89start_cpu(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-90start_offset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-91start_time() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-92start_node_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-93start_pid_table_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-94start_tid_table_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-95start_node_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-96

End Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-97end_id(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-99end_arg(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-100end_arg_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-101end_arg_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-102end_arg_long_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-103end_arg_long_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-104end_blk_arg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-105end_blk_arg_bits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-106end_blk_arg_char(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-107end_blk_arg_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-108end_blk_arg_flt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-109end_blk_arg_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-110end_blk_arg_long_bits(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-111end_blk_arg_long_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-112end_blk_arg_long_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-113end_blk_arg_long_ubits(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-114end_blk_arg_short() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-115end_blk_arg_string() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-116end_blk_arg_ubits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-117end_blk_arg_uchar(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-118end_blk_arg_uint() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-119end_blk_arg_ulong_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-120end_blk_arg_ushort() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-121end_num_args() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-122

xii

Contents

end_pid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-123end_thread_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-124end_task_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-125end_tid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-126end_cpu() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-127end_offset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-128end_time() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-129end_node_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-130end_pid_table_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-131end_tid_table_name(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-132end_node_name(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-133

Multi-State Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-134state_gap() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-134state_dur() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-135state_matches(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-136state_status(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-137

Offset Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-138offset_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-140offset_arg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-141offset_arg_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-142offset_arg_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-143offset_arg_long_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-144offset_arg_long_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-145offset_blk_arg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-146offset_blk_arg_bits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-147offset_blk_arg_char() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-148offset_blk_arg_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-149offset_blk_arg_flt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-150offset_blk_arg_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-151offset_blk_arg_long_bits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-152offset_blk_arg_long_dbl(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-153offset_blk_arg_long_long(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-154offset_blk_arg_long_ubits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-155offset_blk_arg_short() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-156offset_blk_arg_string() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-157offset_blk_arg_ubits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-158offset_blk_arg_uchar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-159offset_blk_arg_uint(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-160offset_blk_arg_ulong_long(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-161offset_blk_arg_ushort() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-162offset_num_args() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-163offset_pid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-164offset_thread_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-165offset_task_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-166offset_tid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-167offset_cpu() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-168offset_time() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-169offset_node_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-170offset_pid_table_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-171offset_tid_table_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-172offset_node_name(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-173offset_process_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-174offset_task_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-175offset_thread_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-176

xiii


Summary Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-177min() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-177max() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-178avg(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-179sum() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-180min_offset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-181max_offset(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-182summary_matches(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-183

Format and Table Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-184get_string(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-184get_item(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-186get_format() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-188format() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-190lookup_pc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-191

Profile References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-193

Chapter 17 Kernel Tracing

Primary Kernel Trace Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1Context Switch Trace Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2Interrupt Trace Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2Exception Trace Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-3Syscall Trace Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-4Kernel Work Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-5

Additional Kernel Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-7Logging Custom Kernel Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-8

From User Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-9From Kernel Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-9Retrieving Custom Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-10

Viewing Kernel Trace Event Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-11Kernel Timelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-12

Node and CPU Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-13Context Switch Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-13Interrupt Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-14Exception Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-14System Call Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-15Process Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-16Kernel Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-16Color Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-17

Kernel String Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-17

Chapter 18 Using the NightTrace Analysis API

NightTrace Analysis Application Programming Interface . . . . . . . . . . . . . . . . 18-1Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2

tr_arg_t. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2tr_cb_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-3tr_cond_cb_func_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-3tr_cond_func_t. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-4tr_cond_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-4tr_dir_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-4tr_offset_t. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-4tr_state_action_t. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5

xiv

Contents

tr_state_cb_func_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-5tr_state_info_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-6tr_state_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-7tr_stream_event_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-7tr_stream_func_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-7tr_string_node_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-7tr_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-8

Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-9API Initialization and Destruction. . . . . . . . . . . . . . . . . . . . . . . . . . . .18-14

tr_init() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-14tr_destroy(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-14

Error Detection, Collection, and Reporting . . . . . . . . . . . . . . . . . . . .18-16tr_error_clear() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-16tr_error_check() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-17

Input Specification and Streaming Control . . . . . . . . . . . . . . . . . . . . .18-18tr_open_file() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-18tr_open_stream() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-19tr_close() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-20tr_stream_notify() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-21tr_stream_read() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-22tr_stream_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-23tr_free() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-24

Event Offset Positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-25tr_next_event() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-25tr_next_event_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-26tr_prev_event(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-26tr_prev_event_(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-27tr_search() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-28tr_seek() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-29

Basic Event Attribute Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-30tr_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-32tr_id_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-32tr_time() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-33tr_time_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-34tr_nargs() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-35tr_nargs_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-35tr_arg_int() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-36tr_arg_int_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-37tr_arg_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-38tr_arg_dbl_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-38tr_arg_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-39tr_arg_long_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-40tr_arg_long_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-41tr_arg_long_dbl_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-41tr_arg_long_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-42tr_arg_long_long_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-43tr_arg_int_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-44tr_arg_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-45tr_arg_dbl_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-45tr_arg_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-46tr_arg_long_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-47tr_arg_long_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-48tr_arg_long_dbl_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-48tr_arg_long_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-49

xv


tr_argtype() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-50tr_argtype_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-51tr_blk_arg(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-51tr_blk_arg_(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-52tr_blk_arg_bits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-53tr_blk_arg_bits_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-54tr_blk_arg_char() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-55tr_blk_arg_char_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-55tr_blk_arg_dbl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-56tr_blk_arg_dbl_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-57tr_blk_arg_flt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-58tr_blk_arg_flt_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-58tr_blk_arg_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-59tr_blk_arg_long_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-60tr_blk_arg_long_bits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-61tr_blk_arg_long_bits_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-62tr_blk_arg_long_dbl(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-63tr_blk_arg_long_dbl_(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-63tr_blk_arg_long_long(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-64tr_blk_arg_long_long_(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-65tr_blk_arg_long_ubits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-66tr_blk_arg_long_ubits_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-67tr_blk_arg_short(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-68tr_blk_arg_short_(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-68tr_blk_arg_string() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-69tr_blk_arg_string_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-70tr_blk_arg_ubits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-71tr_blk_arg_ubits_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-72tr_blk_arg_uchar() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-73tr_blk_arg_uchar_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-74tr_blk_arg_ushort(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-75tr_blk_arg_ushort_(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-75tr_pid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-76tr_pid_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-77tr_tid(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-78tr_tid_(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-78tr_thread_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-79tr_thread_id_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-80tr_task_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-81tr_task_id_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-81tr_cpu() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-82tr_cpu_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-83tr_node() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-84tr_node_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-84tr_process_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-85tr_process_name_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-86tr_task_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-86tr_task_name_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-87tr_thread_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-88tr_thread_name_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-88

Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-90tr_cond_create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-91tr_cond_reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-92tr_cond_find(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-92

xvi

Contents

tr_cond_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-93tr_cond_id_range(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-94tr_cond_id_clear() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-95tr_cond_cpu() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-96tr_cond_cpu_clear() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-97tr_cond_pid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-98tr_cond_pid_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-99tr_cond_pid_clear() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-100tr_cond_tid(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-101tr_cond_tid_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-102tr_cond_tid_clear(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-103tr_cond_node() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-104tr_cond_node_clear() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-105tr_cond_func_or() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-106tr_cond_func_and() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-108tr_cond_func_clear() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-110tr_cond_expr_and() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-111tr_cond_expr_or() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-112tr_cond_not() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-113tr_cond_or() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-114tr_cond_and() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-115tr_cond_copy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-116tr_cond_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-118tr_cond_satisfy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-118tr_cond_satisfy_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-119tr_cond_register(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-120tr_cond_offset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-121

State-oriented Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-122tr_state_create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-122tr_state_find(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-123tr_state_name(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-124tr_state_start_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-125tr_state_start_id_range() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-126tr_state_start_id_clear() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-127tr_state_end_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-127tr_state_end_id_range() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-128tr_state_end_id_clear(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-129tr_state_start_cond(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-130tr_state_start_cond_clear(). . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-131tr_state_end_cond() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-131tr_state_end_cond_clear() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-132tr_activate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-133tr_state_info(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-134tr_state_info_(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-135tr_state_active() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-136tr_state_active_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-137

Output Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-138tr_copy_input(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-138tr_copy_input_range() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-139

String Table Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-140tr_get_string(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-140tr_get_item(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-141tr_create_table() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-142tr_append_table() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-143

xvii


Callback Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-145tr_iterate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-145tr_halt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-146tr_cancel_cb() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-146tr_cond_cb() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-147tr_state_cb() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-148

Appendix A NightStar Licensing

License Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1License Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2License Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2License Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3Firewall Configuration for Floating Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3License Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4

Appendix B Kernel Dependencies

Advantages for NightView. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1Advantages for NightTrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1Advantages for NightProbe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2Advantages for NightTune . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2Frequency Based Scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3

Appendix C Privileged Access

Capabilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1

Appendix D NightTrace Logging API Examples

Single Threaded C Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-1Multi-Threaded C++ Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-3Fortran Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-6Simple Java Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-6Multi-Threaded Java Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-8Rare Occurrence Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-9

Appendix E NightTrace Analysis API Examples

list. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2list.c. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2

search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-4search.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-4

watchdog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-6watchdog.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-6

ptime. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-9ptime.c. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-10

browse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-12browse.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-12

detect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-23detect.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-24

xviii

Contents

Appendix F NightTrace Application Illumination Examples

Illuminating Some Object Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-1Illuminating A Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-5Illuminating An Entire Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-6Illuminating A C++ Class -- Excluding Some Functions . . . . . . . . . . . . . . . . . . F-7Illuminating An API -- Libraries Without Source or Debug Info . . . . . . . . . . . . F-9Customizing an Illuminator -- Logging Extra Information . . . . . . . . . . . . . . . . .F-11Tutorial Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-13

main.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-13math.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-13work.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-14classy.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-14api.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-15

Appendix G Answers to Common Questions

Appendix H Glossary

Index

Illustrations

Figure 2-1. Inter-Process Communication and Library Routines. . . . . . . . . . . . .2-4Figure 8-1. NightTrace Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-1Figure 8-2. File Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-2Figure 8-3. View Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-6Figure 8-4. Toolbars Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-7Figure 8-5. Daemons Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-8Figure 8-6. Search Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-9Figure 8-7. Summary Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-11Figure 8-8. Profiles Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-13Figure 8-9. Export Profiles Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-14Figure 8-10. Timelines Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-17Figure 8-11. Default User Timeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-18Figure 8-12. Create Custom Kernel Timeline Dialog . . . . . . . . . . . . . . . . . . . .8-19Figure 8-13. Tools Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-20Figure 8-14. Help Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-22Figure 8-15. Tab Context Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-26Figure 8-16. Rename Page Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-26Figure 8-17. Move Page Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-27Figure 8-18. Page with Profile Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-28Figure 8-19. Panel Detaches from Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-29Figure 8-20. Panel Movement in Progress . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-30Figure 8-21. Profile Status List Panel on Top of Profile Definition Panel . . . .8-31Figure 8-22. Event Descriptions Panel added to Page . . . . . . . . . . . . . . . . . . . .8-32Figure 8-23. Panel in Motion Creating Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-33Figure 9-1. Daemons Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-1Figure 9-2. Daemons Panel Context Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-2Figure 9-3. Import Daemon Definitions Dialog . . . . . . . . . . . . . . . . . . . . . . . . .9-3Figure 9-4. Attach to Running Daemons Dialog . . . . . . . . . . . . . . . . . . . . . . . . .9-4

xix


Figure 9-5. Edit Triggers Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6Figure 9-6. Add Triggers Entry Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7Figure 9-7. Edit Daemon Definition Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10Figure 10-1. Trace Segments Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1Figure 10-2. Trace Segment Panel Context Menu . . . . . . . . . . . . . . . . . . . . . . 10-2Figure 10-3. Trace Data Segment Properties Description Dialog . . . . . . . . . . 10-3Figure 11-1. Events Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1Figure 11-2. Events Panel Context Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3Figure 11-3. Search Events for Text Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4Figure 11-4. Edit Event Description Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . 11-6Figure 12-1. Default User Timeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1Figure 12-2. Global Ruler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2Figure 12-3. Interval Ruler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3Figure 12-4. Event Graph with Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-5Figure 12-5. Event Description Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6Figure 12-6. Timeline Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-8Figure 12-7. Timeline Context Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-9Figure 12-8. Edit Event Graph Profile Dialog . . . . . . . . . . . . . . . . . . . . . . . . 12-10Figure 12-9. Edit State Graph Profile Dialog . . . . . . . . . . . . . . . . . . . . . . . . . 12-11Figure 12-10. Edit Data Graph Profile Dialog . . . . . . . . . . . . . . . . . . . . . . . . 12-12Figure 12-11. Edit Data Box Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-14Figure 13-1. Profile Definition Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2Figure 13-2. Profile Status List Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-12Figure 13-3. Profile Status List Panel Context Menu . . . . . . . . . . . . . . . . . . 13-13Figure 14-1. Event Descriptions Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1Figure 14-2. Event Description Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2Figure 15-1. Tags List Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1Figure 15-2. Tags List Panel Context Menu . . . . . . . . . . . . . . . . . . . . . . . . . . 15-3Figure 16-1. Function Terminology Illustrated . . . . . . . . . . . . . . . . . . . . . . . 16-12Figure 16-2. States and Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-12Figure 17-1. Sample Kernel timeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-10Figure 17-2. Node and CPU Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-11Figure 17-3. Context Switch Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-11Figure 17-4. Interrupt Box and Interrupt Graph . . . . . . . . . . . . . . . . . . . . . . . 17-12Figure 17-5. Exception Box and Exception Graph . . . . . . . . . . . . . . . . . . . . . 17-12Figure 17-6. System Call Box and System Call Graph. . . . . . . . . . . . . . . . . . 17-13Figure 17-7. Process Information Row . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-14Figure 17-8. Kernel Events Row . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-14Figure 17-9. Color Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-15Figure B-1. Automatically Generated Data Display Page . . . . . . . . . . . . . . . . . C-5

Tables

Table 3-1. NightTrace Configuration Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3Table 5-1. Character Entities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15Table 5-2. System Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19Table 12-1. Timeline Keyboard Traversal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-7Table 16-1. Time Units and Constant Suffixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-3Table 16-1. NightTrace Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-5Table 17-1. PROCESS Event Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-6Table 17-2. NETWORK Kernel Event Sub-ID Codes . . . . . . . . . . . . . . . . . . . . . . . 17-6Table 17-3. MEMORY Kernel Event Sub-ID Codes . . . . . . . . . . . . . . . . . . . . . . . . 17-7

xx

Contents

xxi


xxii

1Chapter 1Introduction

111

NightTrace is a member of the NightStarTM family of tools. NightTrace provides an inter-active debugging and performance analysis tool, trace data collection daemons, and twoApplication Programming Interfaces (APIs) allowing user applications to log data valuesas well as analyze data collected from user or kernel daemons. NightTrace allows you tographically display information about important events in your application and the kernel,including event occurrences, timings, and data values. NightTrace consists of the follow-ing parts:

ntrace

a graphical tool that controls daemon sessions and presents user and kerneltrace events for interactive analysis

ntraceud

a daemon program that copies user applications’ trace events from sharedmemory to trace event files

ntracekd

a daemon program that copies operating system kernel trace events from ker-nel memory to trace event files

NightTrace Logging API

libraries and include files for use in user applications that log trace events toshared memory

NightTrace Analysis API

libraries and include files for use in user applications that want to analyze datacollected from user or kernel daemons

illuminator

a command line tool for generating code to log trace events at subroutine entryand return points

illuminate

a command line tool for turning on and off the code generated by the illu-minator tool

NightTrace operates in conjunction with other members of the NightStar RT family.NightView, a multi-process and multi-thread application debugger, provides for dynamicinsertion of trace points in programs being debugged. The NightProbe data recording util-ity allows sampled data to be passed directly to NightTrace for graphic or textual display.

NightTrace uses the NightStar License Manager (NSLM) to control access to the

1-1


NightStar tools. See “NightStar Licensing” on page A-1 for more information.

IMPORTANT

Kernel tracing is only supported on some operating system distri-butions. See “Kernel Dependencies” on page B-1 for more infor-mation.

User Trace Point Placement 1

A user trace point is a place of interest in application source code. At each user tracepoint, you make your application log some user-specified information. This logged infor-mation is collectively called a trace event. Each trace event has a user-defined trace eventID number and optional user-supplied arguments.

Some typical user trace-point locations include:

• Suspected bug locations

• Process, subprogram, or loop entry and exit points

• Timing points

• Synchronization points for multi-process interaction

• Endpoints of atomic operations

The Application Illumination facility can be used to automatically generate user tracepoints for function entry and return. These trace events can include return address, param-eter values, return values, etc. as arguments.

In addition to the user-supplied information, trace events automatically contain informa-tion identifying the process ID of the program generating the trace event. Formulti-threaded applications, the thread ID of the specific thread generating the trace isrecorded.

Kernel Trace Point Placement 1

Operating system distributions which support NightTtrace kernel tracing build their traceand debug kernels with trace points inserted at various points throughout the kernel sourcecode. These trace point provide information relating to:

• System call entry and exit

• Interrupt entry and exit

• Exception entry and exit

• Kernel service routines

1-2

Introduction

• Process creation, termination, and signalling

• Network activity

Analysis of kernel trace events can provide significant insight into the operation of thesystem and interactions between user applications. In addition to graphical displays,NightTrace provides textual description of kernel trace events which reveal useful infor-mation even for those not familiar with kernel programming.

For kernel programmers, additional custom trace events can be logged with simple kernelutility routines which can be inserted into the kernel source or in kernel module sourceroutines.

Timestamps 1

Each trace event is tagged with a timestamp with sub-microsecond precision. This allowsyou to view and comprehend complex interactions between multiple processes and theoperating system, executing on single or multiple CPU systems.

By default, an architecture-specific timing source is utilized. For Intel and AMD64, theIntel Time Stamp Counter (TSC register) is used.

If your operating system supports the Real-Time Clock and Interrupt Module (RCIM),that clock can be also used as a timestamp source.

The RCIM is a hardware module available from Concurrent Computer Corpration whichprovides a variety of clocks and interrupt sources, including two high-resolution timerswhich may be synchronized between multiple systems. Use of the RCIM timing sourceby NightTrace is advantageous when gathering data from multiple systems simulta-neously. NightTrace can then present a synchronized view of user and kernel activity onmultiple systems from a single session.

For more information about the RCIM, please see the clock_synchronize(1M),rcim(7), rcimconfig(1M), and sync_clock(7) man pages.

Languages 1

The application programming interface for logging trace events is provided in C and For-tran for use with the following compilers:

• Concurrent Ada

• GNU C/C++

• GNU Fortran

• Intel C/C++

• Intel Fortran

1-3

NightT

nighttrace user’s guide · 2019. 3. 12. · iii preface scope of manual this manual is a...

Documents