Difference between revisions of "Aprobe FAQ"

From OC Systems Wiki!
Jump to: navigation, search
m (What tools make up Aprobe?)
m (Is there a point-and-click (GUI) interface to Aprobe?)
Line 122: Line 122:
 
==== <span id="q12.12"></span>  Is there a point-and-click (GUI) interface to Aprobe? ====
 
==== <span id="q12.12"></span>  Is there a point-and-click (GUI) interface to Aprobe? ====
  
Yes. It's called RootCause. See [[RootCause_FAQ#q1.1 | #What is RootCause?"]] .
+
Yes. It's called RootCause. See [[RootCause_FAQ#q1.1 |"What is RootCause?"]] .
  
Also, Some predefined probes (see [#predefined  Q15.] below) include a Java GUI to specify configuration parameters for that probe.
+
Also, Some predefined probes (see [[#q15|"Predefined_Probes"]] below) include a Java GUI to specify configuration parameters for that probe.
  
 
</div><div>
 
</div><div>

Revision as of 22:01, 10 May 2017

Aprobe FAQ

Frequently Asked Questions for Probe (All Platforms) Updated May 2017

This document describes aspects of the "Aprobe" product from OC Systems, Inc. (www.ocsystems.com):

It consists of questions asked by evaluators and customers, as well as "artificial" questions intended to provide an introduction to the use of the products.

More complete and detailed descriptions of RootCause are provided by the User's Guides for those products, but this FAQ may provide answers not easily found there, and also includes specific code examples not applicable to a general User's Guide.

Aprobe underlies RootCause, which provides support for constructing sets of probes which can be deployed remotely. See "What is RootCause?" for more information.

Users are encouraged to send questions (and answers!) to support@ocsystems.com.


Note to Windows and Solaris Users:

The last updates to RootCause/Aprobe for the Windows and Solaris platforms were version 2.1.4b/4.3.4b in mid-2006. Support for these platforms was officially dropped in 2011. A recent update of this FAQ has removed all questions and answers that are specific to those platforms. If by some unlucky chance you're still using them, here is the [rc_aprobe_faq-2007.html old version of the FAQ].


Note to 64-bit RootCause/Aprobe Users:

Whereever you read APROBE in the questions and answers below, replace with APROBE64. Different file names and environment variables must be used to allow both 32- and 64-bit versions to co-exist.

This FAQ is Copyright (c) 2017 by OC Systems, Inc. ALL RIGHTS RESERVED.

What is Aprobe?

Aprobe is a suite of tools and libraries which support dynamic modification and extension of a program by dynamically patching the program executable and/or shared libraries.

A dictionary defines "Probe" as "Device for exploring an otherwise inaccessible place or object." "Aprobe" stands for "Algorithmic Probe". It is hence a tool for exploring your program with the help of user-written algorithmic probes. These probes are installed into your program with the help of OC Systems' patented "dynamic action linking" technology.

A user runs a program with the "aprobe" tool, indicating that certain "probes" are to be patched into the program and executed as the program itself runs.

A "probe" consists of "actions" composed in C, with some special syntax added to indicate where in the program the actions are to be invoked.

There are a number of predefined probes included in Aprobe; there is a tool to generate simple probes directly from a linked or unlinked object file; or the user may easily compose his own probes in a simple extension of the C language.

See also "What is RootCause?"

What is ProbePak?

The ProbePak was an experiment at introducing users to the power of Aprobe and RootCause by making a subset available for free download. It didn't work out, and ProbePak is no longer supported. See the main page www.ocsystems.com for information on our current products.

What are some potential uses of Aprobe?

Read more about uses of Aprobe in the Product section of the web site or read thewhite papers in the Resources section. See also "What are some potential uses of RootCause?"

How do I get started quickly with Aprobe?

The best way to get started writing probes is to look at examples, and make some small changes.

If you have RootCause and have been using the GUI, you can use the Custom... button in the Trace Setup window to generate a probe, and look at that. If that looks too daunting, or you want a more tutorial approach, try the graduated examples in the $APROBE/examples (or $APROBE/ada_examples) and $APROBE/demo/Aprobe subdirectories of the Aprobe installation. Check out $APROBE/examples/evaluate/README.

Who can use Aprobe?

Technical people who are developing, testing, and maintaining software.

What different versions of Aprobe are there?

The current version of Aprobe is 4.4.6d, released in May 2017.

The original version of Aprobe is version 2. for AIX, included as part of OC Systems LegacyAda/OATS product, and in earlier versions of OC Systems "PowerAda" product.. While it shares the "probe" concept with the newer version, the user interface and details of Aprobe Version 2 differ substantially from Versions 3 and 4.

For which platforms is Aprobe available?

Same as those for RootCause: See "For which platforms is RootCause available?".

How do I get Aprobe?

E-mail , and we will arrange for you to receive the software.

What documentation is available for Aprobe?

The new Aprobe User Guide is available on-line in this DocsWiki Aprobe User Guide .

There are a series of graduated examples that come with their own text documentation in the $APROBE/examples and $APROBE/demo subdirectories of the Aprobe installation. You should read $APROBE/examples/evaluate/README and try at least some of the examples under that directory, before trying Aprobe on your own application or looking through this FAQ for answers.

What tools make up Aprobe?

  • apcgen - generates APC for some or all functions in the specified object file(s)
  • apc - compiles and links the specified APC file(s) into a UAL.
  • aprobe] - runs the specified program after loading and applying patches in the specified UAL(s).
  • apformat] - formats any data logged in the specified APD file(s).

These tools are described further in other questions below. A number of additional tools and scripts and for specific situations are also provided. See Tools Reference.

How is Aprobe licensed?

Same as RootCause. See "How is RootCause licensed?" .

Is there a point-and-click (GUI) interface to Aprobe?

Yes. It's called RootCause. See "What is RootCause?" .

Also, Some predefined probes (see "Predefined_Probes" below) include a Java GUI to specify configuration parameters for that probe.

Can I run Aprobe on any executable program file?

Yes. You can run aprobe (without any probes) on any application at all unless:

  • It is a secure application which a debugger doesn't have authority to attach to. In this case you should get a clear explanatory message.
  • The application does something very strange like replacing some low-level system routines with its own versions that do something different.
  • There's a bug in Aprobe.

If you find that using aprobe causes your application to crash, you should try running aprobe without any probes. If it still crashes, it should be reported as a bug to support@ocsystems.com.

A slightly different question is, "Can I use Aprobe to put probes on any program?" To actually apply probes to a native module, there are three basic requirements:

  • Symbols

For Aprobe to do what it does it must be able to figure out where the subroutines you are trying to probe have been linked and loaded. We call this location information "symbols". All symbolic debuggers have the same requirement. See #q12.17 : Q12.17 .

The symbols may be as originally added to the application (i.e., not stripped, see Q12.16 ), or they may have been saved separately by Aprobe using apmkadi (see Q13.9 ).

Most programs delivered with the operating system, and off-the-shelf software, are stripped, so you can't use Aprobe directly on the application code, but you can generally probe shared libraries (DLLs) that support them.

Standard Call/Return behavior
If the program uses a mechanism that transfers control other than by the normal call and return mechanism, such as setjmp / longjmp or an unsupported exception mechanism, and there is an active probe at the time of that non-standard transfer of control, the program will likely crash.
Supported exception mechanism.
Ada and C (and Java, but that's a separate issue) support exceptions which are non-standard transfers of control. Each compiler does this in a different way, and must be explicitly supported by the Aprobe runtime. See Q12.15.

In what language(s) can my program be written?

Same as for RootCause. See [#q1.10 Q1.10]

What compiler(s) must have been used to compile my program?

Same as for RootCause. See [#q1.11 Q1.11]

How do I tell if a program file is "stripped"?

Use the "file" command, e.g.:

AIX:

$ file a.out
a.out:      executable (RISC System/6000) or object module not stripped
$ file /bin/ls
bin/ls:     executable (RISC System/6000) or object module

Linux:

$ file a.out
a.out: ELF 32-bit LSB executable, Intel 80386, version 1, dynamically linked (uses shared libs), not stripped
$ file /bin/ls
/bin/ls: ELF 32-bit LSB executable, Intel 80386, version 1, dynamically linked (uses shared libs), stripped

How do I tell what symbols a program has available?

The command apcgen -L will list the Aprobe function symbols in any compiled object module, for example:

apcgen -L C:\WinNT\system32\kernel32.dll
apcgen -L /usr/lib/libc.so
apcgen -L /work/programs/prog.exe

There are other apcgen options such as -m to show "mangled" names and -v to show file names--use apcgen -h for usage.

The RootCause Trace Setup window shows a tree of all the functions organized by module, directory and file, using the same mechanism used by apcgen.

If you want information about data symbols, or want to confirm that a function may actually be probed, you can use the apinfo command, which runs the "info" predefined probe. This only works on executable programs. For example:

apinfo -d /work/programs/prog.exe

will show all the global and file-static data symbols found when prog.exe is loaded by aprobe. There are lots of other options: use apinfo -h to see them.

What do I do to get symbols in my program?

On Unix, every program has its symbols unless they're explicitly stripped (see [#q12.16 Q12.16]

What do I do to get "debug information" in my program?

This is documented in Chapter 10 of the RootCause User's Guide, "Building a Traceable Application", and in Chapter 3 of the Aprobe User's Guide, but it's summarized here:

  • For C/C compilers compile with -g.
  • With PowerAda you get debug information by default, but you need the PowerAda program library available just as you would for adbg.

In addition to compiling with the right option to generate the debug information, you also must retain that information and have it available where it's supposed to be:

  • For gcc-based compilers, including GNAT, and IBM's C and C compilers, debug information is collected at link-time into the executable, and is retained unless you explicitly use the "strip" command.
  • PowerAda line information is recorded in the executable and can't be stripped, so you don't need any debug information at run-time. However, for `apc' and the RootCause GUI, you need the Ada program library, which must be consistent with the executable and available at the same location recorded in the executable. If the library is moved, you can specify its location with the environment variable APROBE_POWERADA_LIBRARY, for example
  export APROBE_POWERADA_LIBRARY=/builds/old/prog1/adalib

How do I tell if a program file has "debug information"?

The apcgen command will list those functions that have debug information associated with them:

apcgen -Ld a.out

This should be all you need, but there are some system utilities that look in the object files themselves that may also be used:

  • On Linux you should find objdump :
  objdump -W a.out | grep "DW_TAG_subprogram" | awk '{ print $NF }'
  • On AIX, you can use the dump utility with the -t option to dump symbol information, including debug "stab" strings. For example:
  dump -t a.out | grep ":F"
  • will show the functions that have debug information.

What is a "probe"?

A "probe" is a "user action" associated with a specific location in a program. The user action is executed whenever control passes through the location with which it is associated. A "probe" is described in an extension of C called "APC", for example:

probe thread
{
  probe "foo"
  {
    on_entry
    {
      printf("Entering foo.\n");
    }
  }
}

The block following the "on_entry" is the "user action". The syntax surrounding it describes exactly where and when the action should be executed: immediately upon entering function "foo()" in each thread.

What is a "UAL" (.ual file)?

A UAL is a "User Action Library". It is the output of the "apc" command, and is a shared library consisting of the object code generated from your apc files. Not just any shared library (DLL) may be used as a UAL, and it a UAL may not be renamed after creation, because it has specially-named entry points based on its filename which are called by the Aprobe runtime to perform initialization.

What is "logging"?

With respect to Aprobe, "logging" means "writing data to a file for later analysis" Aprobe provides a built-in logging facility that allows saving raw data in a time and space-efficient way, and using "apformat" to display the logged data later. See [#logging "Logging Data"] for related questions.

What is an ".apd" file?

An ".apd" file is one that contains the data generated by a program run under aprobe. These are binary files which are read with the "apformat" tool.

There is always a ".apd" file generated giving aprobe invocation information, even if no "log" statements are executed. If log statements were executed there will be a "-1.apd" file, and maybe "-2.apd" files as well.

What can't I do if my executable or library doesn't have debug information?

You can't reference source-level information in your probes. It's just like using a source level debugger in this respect, and for the same reason. A good rule is, if the debugger can print the value of a variable x at line 15, then you can do "on_line(15) log($x)" in your probe.

More specifically, you need to specify "-x exe_or_library " on the apc command, and the exe_or_library must contain debugging information, if you use a construct in your probe that cannot be resolved without specific debug information from the program. Such constructs are:

(a) target expressions: names from the probed program preceded by $, or $* ($1, $2 are ok, as are hardware-register references starting with '$$').

and

(b) references to specific source lines;

Note that there are lots of probes you can write; for example, all but one of the predefined probes provided with Aprobe will work fine in the absence of debug information, and the one that does require it (coverage) does so in order to get source line number information.

Does use of on_line() requires application to be have debug information?

Yes, but things aren't that simple. To build a probe that requires debug information (including line information), the debug must be available when the probe is compiled. However, the debug information can then be stripped and the probe run against the stripped executable.

For the symbol table, the necessary symbols must be present at runtime, either in the application (or application libraries) or in a [[AUG_Files_Reference#ADI File|.adi] file which is generated with the tool apmkadi. That tool allows you to capture the symbol table in an internal form and then strip the executable.

Also, PowerAda programs always contain source line information -- this is not considered debug information.

Finally for low-level hacking, you can instrument specific offsets using on_offset.

What is the maximum number of probes allowed?

For probes you are just limited by paging space. For UALs there is a more practical limit - we limit the total number of modules to 255 and that includes UALs.

Is there access to C private/protected variables?

Yes, if it's in the debug we can see it. We don't look at whether the debug says it's private, protected or public - we just use it.

Is there any way to attach with Aprobe to a running application?

No. This question is very frequently asked. It sounds great in theory but in practice Aprobe is a tool for tracking problems that have yet to happen, not those that have just happened. There is also quite a bit of work done by Aprobe when an application starts up; often doing this to a running application is as big an issue as re-starting the application.Finally for Java you wouldn't be able to change the classpath to see our classes or intercept classes that have already loaded.

Is there a way to probe a function for which no symbol is available?

Yes, if you know its address and size, you can define a symbol for it using ap_RecordDynamicFuntionSymbol() in the Aprobe Runtime Library and and then apply probes using the define symbol.

Here is are example C and Apc files illustrating how to use it.

defsym.c

 #include
 #include
 
 static char *image(char *s)
 {
    char *s1 = strdup(s);
    return s1;
 }
 
 int main (void)
 {
   printf (image("Hello\n"));
   return 0;
 }
 

defsym.apc

 //---------------------------------------------------------------------------
 // Define Dynamic Function Symbol Example
 //
 // This is an example of using ap_RecordDynamicFunctionSymbol()
 // to define symbols when no debug information is available.
 //
 // NOTE:  If the offset for symbols is wrong the program will
 // likely crash because you will have directed Aprobe to instrument
 // the wrong piece of code.
 //---------------------------------------------------------------------------
 
 #include "aprobe.h"
 
 // To define your symbols early enough to be instrumented and
 // probed, you have to define them from a UAL initalize function.
 // The initial part of the name must be InitializeUal_, and the first
 // character following that must be lower in the ASCII collating order
 // than the first character of the UAL name. '0' is the lowest legal
 // character.
 
 void InitializeUal_0_defsym_apc()
 {
    // In this example I just define an alias for the symbol "main"
    // and probe that instead.  You have to know the correct offset
    // and size of the function (though size is not so critical).
    // The offset is the offset in the moudle, not just the text
    // section.
    ap_SymbolIdT NewSym =
       ap_RecordDynamicFunctionSymbol (
          ap_ApplicationModuleId(),
          "MyAliasForMain",
          ap_ExternSymbol,
          ap_IntegerToOffset(0x10),
          0x1d,
          0);
    if (ap_IsNoSymbolId(NewSym))
    {
       printf("Couldn't define symbol...\n");
    }
 }
 
 probe thread
 {
    // You'll get a warning about the symbol not being defined
    // when you compile this with apc, but it's OK.
    probe "MyAliasForMain"
    {
       on_entry  printf("Hello again...\n");
    }
 }