Make sure you’ve installed base packages before installing this instrumentation.

Installing instrumentation

Instrumentation for apache is provided as a pair of DSO modules called mod_oboe and mod_oboe_ps. They hook into the input handler, header filter, and body filters. The input handler (entry event) is applied immediately to incoming requests. The header filter is applied to outgoing responses only in the case of requests that don’t generate response bodies—HEAD requests, for example. The body filter is the most common exit event point for instrumentation of http requests, occurring when the last part of the response has been generated by the app server below Apache. What this means: the measurements of time spent in Apache generated by mod_oboe are mostly time spent before the child request layer rather than after. Therefore Apache can be used to measuring queuing in app layers below.

Installing from packages

Instrumentation for apache is provided as a pair of DSO modules called mod_oboe and mod_oboe_ps, and they are available as packages from our repositories. These packages can be installed using your package manager but only after you’ve installed our base packages. This is because when you ran our install script install_traceview.sh, it not only installed mod_oboes dependencies, but it also added an AppNeta repository and floated it to the top of your sources list.

debian/ubuntu

The package containing the TraceView instrumentation modules is libapache2-mod-oboe. The module binaries will be installed in /usr/lib/apache2/modules/; any files with ‘oboe’ in their filename are related to instrumentation. Each module comes with two config files will be installed in /etc/apache2/mods-available/: the .load files contain a solitary LoadModule directive, and the .config files set the tracing mode and inject the rum js.

  1. apt-get install the package containing the webserver instrumentation and auto-rum instrumentation modules.

    apt-get install libapache2-mod-oboe
    
  2. mod_oboe must be loaded before you are using mod_rewrite or mod_proxy. If you’re using either of these modules:

    1. Copy/paste the LoadModule directive in oboe.load into apache.conf so that it appears before the mod_rewrite and/or mod_proxy LoadModule directives.
    2. Comment out the LoadModule directive in oboe.load.
  3. Reload apache so that the new configs are included.

redhat/centos

The package containing the TraceView instrumentation modules is libapache2-mod-oboe. Once installed you’ll have two config files in /etc/httpd/conf.d/: oboe.conf and oboe_ps.conf. The latter is a config file related to rum, and you won’t need to manipulate this file. But, where apache instrumentation offers configuration opportunities, those changes will be make in oboe.conf. The module binaries are installed in the /usr/lib/httpd/modules/ or /usr/lib64/httpd/modules/ depending your system architecture; any files with ‘oboe’ in their filename are related to instrumentation.

  1. yum install the package containing the webserver instrumentation and the auto-rum instrumentation modules.

    yum install libapache2-mod-oboe
    
  2. mod_oboe must be loaded before you you are using mod_rewrite or mod_proxy. If you’re using either of these modules:
    1. Copy/paste the LoadModule directive in oboe.conf into apache.conf so that it appears before the mod_rewrite and/or mod_proxy LoadModule directives.
    2. Comment out the LoadModule directive in oboe.conf.
  3. Reload apache so the new configs are included.

Installing binaries manually

If installing from our packages isn’t suitable for your environment, e.g., because you’re running a package that was not officially provided by your vendor for your distro, or building you built from source, you can still install our instrumentation.

  1. Place the webserver and rum instrumentation modules matching your environment into your modules directory. The examples below assume the standard location.

    # 64-bit apache 2.2
    wget http://files.tv.solarwinds.com/libapache2-mod-oboe/x64/mod_oboe.so -P /usr/local/apache2/modules/
    wget http://files.tv.solarwinds.com/libapache2-mod-oboe/x64/mod_oboe_ps.so -P /usr/local/apache2/modules/
    # 32-bit apache 2.2
    wget http://files.tv.solarwinds.com/libapache2-mod-oboe/i386/mod_oboe.so -P /usr/local/apache2/modules/
    wget http://files.tv.solarwinds.com/libapache2-mod-oboe/i386/mod_oboe_ps.so -P /usr/local/apache2/modules/
    # 64-bit apache 2.4
    wget http://files.tv.solarwinds.com/libapache2-mod-oboe/x64/mod_oboe-apache24.so -P /usr/local/apache2/modules/
    wget http://files.tv.solarwinds.com/libapache2-mod-oboe/x64/mod_oboe_ps_ap24.so -P /usr/local/apache2/modules/
    # 32-bit apache 2.4
    wget http://files.tv.solarwinds.com/libapache2-mod-oboe/i386/mod_oboe-apache24.so -P /usr/local/apache2/modules/
    wget http://files.tv.solarwinds.com/libapache2-mod-oboe/i386/mod_oboe_ps_ap24.so -P /usr/local/apache2/modules/
    
  2. Add the following config to http.conf. It loads the instrumentation and rum modules and enables auto-rum. auto-rum is a switch provided on a per-app basis that enables you to turn rum on and off without having to change your apache config and reload. When toggled, the TraceView dashboard sends a signal to instrumented apache based on directives in http.conf. Our packages come pre-configured for auto-rum, but because you’re using the alternate install method, you need to make a few configuration changes before you can use it. In addition, make sure mod_oboe is loaded before mod_proxy and mod_rewrite.

    # -------------- start traceview config snippet -------------
    # Uncomment the appropriate line to load webserver instrumentation module
    # In addition, make sure mod_oboe is loaded before mod_proxy and mod_rewrite
    # LoadModule oboe_module PREFIX/mod_oboe.so
    # LoadModule oboe_module PREFIX/mod_oboe-apache24.so
    
    # uncomment the line that matches your rum module  
    # LoadModule oboe_ps_module PREFIX/mod_oboe_ps.so
    # LoadModule oboe_ps_module PREFIX/mod_oboe_ps_ap24.so
    
    # enable tracing and set to initiate traces in apache
    # enclosed in ifmodule so that config doesn't break if instrumentation modules are not present
    <IfModule mod_oboe.c>
        OboeTracingMode always
    </IfModule>
    
    # the remainder of this config is for auto-rum
    ModOboePagespeed on
    
    # choose a location for the pagespeed cache that is writable by apache/httpd
    ModOboePagespeedFileCachePath "/var/cache/mod_oboe_ps/"  
    
    ModOboePagespeedInheritVHostConfig on
    AddOutputFilterByType MOD_OBOE_PS_OUTPUT_FILTER text/html
    ModOboePagespeedRewriteLevel PassThrough
    ModOboePagespeedEnableFilters traceview_rum
    ModOboePagespeedTraceviewLayerName _PAGESPEED_FLAGS_0_:apache
    ModOboePagespeedModifyCachingHeaders off
    # -------------- end traceview config snippet ------------------
    
  3. Reload apache so that it registers the config changes you just made.

Uninstalling instrumentation

If you installed from packages you can used apt-get purge or yum remove.

# debian/ubuntu
apt-get purge libapache2-mod-oboe
# rhel/centos 
yum remove libapache2-mod-oboe

Upgrading instrumentation

redhat/centos

  1. To check for updates to the apache oboe module package run:

    yum info libapache2-mod-oboe
    
  2. Pending releases will be listed under an ‘available packages’ heading. If you don’t see this you’re all up to date! If you there is a new version available it can be upgraded by running:

    yum -y update libapache2-mod-oboe
    

debian/ubuntu

  1. To check for updates to the apache oboe module package run:

    apt-get update
    apt-cache policy libapache2-mod-oboe
    
  2. If the displayed latest version matches the current candidate version you’re all up to date! If there is a new version available it can be upgraded by running:

    apt-get install -y --only-upgrade libapache2-mod-oboe
    

Configuring instrumentation

Change the tracing mode

The tracing mode is configured through oboe.conf. OboeTracingMode determines when traces should be initiated for incoming requests. It’s variants are as follows:

always
(Default) Continue existing traces, otherwise attempt to start a new one. This is the default for web server layers, like Apache.
through
Continue existing traces, but never start them. This mode assumes that a higher layer makes the decision whether to trace. This is not typically used for webservers unless they are behind a tracing load balancer.
never
Never continue existing traces or start new ones.

Exclude url query parameters

Apache instrumentation reports two key/value pairs, Request-Orig-URI and Query-String, which show up on the trace details page and might contain url query parameters. For privacy reasons you might like to suppress those query parameters so that for example “http://www.somewhere.com/serv/search?a=1&text=’this” becomes “http://www.somewhere.com/serv/search”. To do this, add OboeIncludeUrlQuery off to oboe.conf. This line will strip query parameters off of Request-Orig-URI leaving only the path portion of the url, and Query-String will not be reported at all.

Disable tracing for static files

To selectively trace and/or sample segments of your setup, you may place oboe OboeTracingMode directives inside VirtualHost, Location, LocationMatch, or other containers. For example, to exclude static content you might do something like:

<IfModule mod_oboe.c>
  <LocationMatch "\.gif|jpg|png|css|js|ico|txt|swf)$">
    OboeTracingMode never
  </LocationMatch>
</IfModule>

If apache is running mod_dav_svn to serve up an svn repository, that’s another good candidate for exclusion from tracing. Modify your existing svn location or virtualhost directive with an OboeTracingMode directive as follows.

<location svn=""> 
  DAV svn SVNParentPath "/net/svn.nfs/repositories" SVNActivitiesDB "/var/db/svn/activities" OboeTracingMode never
</location>

You can also use the OboeTracingMode directive in an .htaccess file if the AllowOverride option is set for the directory that the .htaccess file is in.

<VirtualHost *:80>
  DocumentRoot /var/www
  ServerName docs.traceview.solarwinds.com
    <Directory /var/www/docs>
      AllowOverride OboeTracingMode
    </Directory>
</VirtualHost>