instrumentation.c

Go to the documentation of this file.

/*
 * instrumentation.c
 *
 * Copyright (c) 2003, 2004 The University of Utah and the Flux Group.
 * All rights reserved.
 *
 * This file is licensed under the terms of the GNU Public License.  
 * See the file "license.terms" for restrictions on redistribution 
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 */

/**
 * @file instrumentation.c
 *
 * Implementation of the functions in instrumentation.h.
 */

#include "config.h"

#include <math.h>
#include <time.h>
#include <sys/types.h>
#include <sys/param.h>
#include <string.h>
#include <unistd.h>
#include <float.h>
#include <assert_pp.h>

#include "instrumentation.h"

/**
 * Add an amount to an existing index into the ip_History.data array of the
 * iPoint structure.  In case the addition causes the index to extend beyond
 * the bounds of the array, the result will be wrapped around to the beginning.
 *
 * @param ip A pointer to a valid iPoint.
 * @param amount The amount to add to the ip_History.start value.
 * @return The new index.
 */
#define IP_HISTORY_START_ADD(ip, amount) \
    ((ip)->ip_History.start + (amount)) % (ip)->ip_History.length

/**
 * The default file name format for the instrumentation file.
 */
static const char *DEFAULT_INSTRUMENTATION_FILE_NAME =
    PACKAGE "-instrumentation-%d.txt";

struct iInstrumentationData instrumentation_data;

/**
 * Initialize an instrumentation point and add it to the list of active points.
 * Normally, a point starts out with all fields initialized to zero, unless a
 * history array is provided.  We must then perform some additional setup by
 * assigning default values to some fields.
 *
 * @param ip The point to initialize.
 *
 * @todo Make thread safe.
 */
static void iInitPoint(struct iPoint *ip)
{
    require(ip != NULL);
    require(ip->ip_Name != NULL);

    /* Assign default values and */
    ip->ip_Minimum = FLT_MAX;
    ip->ip_Maximum = FLT_MIN;
    if( ip->ip_Format == NULL )
    {
        ip->ip_Format = "%10.2f  ";
    }
    /* ... link the point into the global list. */
    if( ip->ip_Succ == NULL )
    {
        if( instrumentation_data.iid_FirstPoint == NULL )
        {
            instrumentation_data.iid_FirstPoint =
                &instrumentation_data.iid_NullPoint;
        }
        ip->ip_Succ = instrumentation_data.iid_FirstPoint;
        instrumentation_data.iid_FirstPoint = ip;
    }
}

void iPostFloatData(struct iPoint *ip, double value)
{
    require(ip != NULL);
    require(ip->ip_Name != NULL);

    /* Check if we need to do any initialization, */
    if( ip->ip_Count == 0 )
    {
        iInitPoint(ip);
    }
    /* ... try to record the value in the history, and */
    if( ip->ip_History.data != NULL )
    {
        if( ip->ip_Count >= ip->ip_History.length )
        {
            ip->ip_History.lost += 1;
            if( ip->ip_Flags & IPF_DROP_HISTORY_START )
            {
                ip->ip_History.data[ip->ip_History.start] = value;
                ip->ip_History.start = IP_HISTORY_START_ADD(ip, 1);
            }
        }
        else
        {
            ip->ip_History.data[ip->ip_Count] = value;
        }
    }
    /* ... update the statistics. */
    ip->ip_Count += 1;
    ip->ip_Total += value;
    if( value < ip->ip_Minimum )
    {
        ip->ip_Minimum = value;
    }
    if( value > ip->ip_Maximum )
    {
        ip->ip_Maximum = value;
    }
}

void iPrintPoint(FILE *file, struct iPoint *ip)
{
    double stddev = 0.0;
    
    require(file != NULL);
    require(ip != NULL);
    require(ip->ip_Name != NULL);
    require(ip->ip_Format != NULL);
    require(ip->ip_Count > 0);
    require((ip->ip_Flags & ~IPF_MASK) == 0);

    /* Print the summary for just the history array or */
    if( ip->ip_History.data != NULL )
    {
        double minimum = FLT_MAX, maximum = FLT_MIN, total = 0.0, avg;
        double stddev_total = 0.0;
        int lpc;

        /* Analyze the data posted to the history, */
        for( lpc = 0;
             (lpc < ip->ip_Count) && (lpc < ip->ip_History.length);
             lpc++ )
        {
            double value = ip->ip_History.data[IP_HISTORY_START_ADD(ip, lpc)];

            if( value < minimum )
            {
                minimum = value;
            }
            if( value > maximum )
            {
                maximum = value;
            }
            total += value;
        }
        avg = total / ((double)lpc);
        for( lpc = 0;
             (lpc < ip->ip_Count) && (lpc < ip->ip_History.length);
             lpc++ )
        {
            double value = ip->ip_History.data[IP_HISTORY_START_ADD(ip, lpc)];

            stddev_total += (value - avg) * (value - avg);
        }
        stddev = sqrt(stddev_total / ((double)lpc));
        /* ... give the user the summary, and */
        fprintf(file,
                "%s: "
                "count=%d/%qd total=%f min=%f max=%f avg=%f stddev=%f '%s'\n",
                ip->ip_Name,
                lpc, ip->ip_Count,
                total,
                minimum,
                maximum,
                avg,
                stddev,
                ip->ip_Description != NULL ? ip->ip_Description : "");
        /* ... possibly the whole history. */
        if( ip->ip_Flags & IPF_PRINT_HISTORY )
        {
            int lpc;
            
            if( ip->ip_History.lost > 0 )
            {
                fprintf(file,
                        "\tLost %d data points at the start\n",
                        ip->ip_History.lost);
            }
            for( lpc = 0;
                 (lpc < ip->ip_Count) && (lpc < ip->ip_History.length);
                 )
            {
                int row_count;
                
                fprintf(file, "\t");
                for( row_count = 0;
                     (row_count < 5) &&
                         (lpc < ip->ip_Count) &&
                         (lpc < ip->ip_History.length);
                     row_count++, lpc++ )
                {
                    fprintf(file,
                            ip->ip_Format,
                            ip->ip_History.data[IP_HISTORY_START_ADD(ip,
                                                                     lpc)]);
                }
                fprintf(file, "\n");
            }
        }
    }
    /* ... all of the data that has been posted. */
    else
    {
        fprintf(file,
                "%s: count=%qd total=%f min=%f max=%f avg=%f '%s'\n",
                ip->ip_Name,
                ip->ip_Count,
                ip->ip_Total,
                ip->ip_Minimum,
                ip->ip_Maximum,
                ip->ip_Total / ((double)ip->ip_Count),
                ip->ip_Description != NULL ? ip->ip_Description : "");
    }
}

void iPrintPoints(FILE *file)
{
    struct iPoint *ip;
    
    require(file != NULL);

    /* Print all active points. */
    ip = instrumentation_data.iid_FirstPoint;
    while( (ip != NULL) && (ip != &instrumentation_data.iid_NullPoint) )
    {
        iPrintPoint(file, ip);
        ip = ip->ip_Succ;
    }
}

void iPrintPointsAtExit(void)
{
    /* Make sure there are some points to print out. */
    if( instrumentation_data.iid_FirstPoint != NULL )
    {
        const char *file_name;
        FILE *file;

        /* Check for a user specified file name, otherwise */
        if( ((file_name = getenv(INSTR_FILE_NAME_ENV)) != NULL) ||
            ((file_name = instrumentation_data.iid_OutputFileName) != NULL) )
        {
            if( strcmp("-", file_name) == 0 )
            {
                file = stdout;
            }
            else
            {
                file = fopen(file_name, "a");
            }
        }
        /* ... use the default format. */
        else
        {
            static char formatted_filename[PATH_MAX];
            
            sprintf(formatted_filename,
                    DEFAULT_INSTRUMENTATION_FILE_NAME,
                    getpid());
            file = fopen(formatted_filename, "a");
        }

        /* Try to write to the file. */
        if( file != NULL )
        {
            time_t cl;

            cl = time(NULL);
            fprintf(file, "\n** %s", ctime(&cl));
            iPrintPoints(file);
            fclose(file);
        }
        else
        {
            fprintf(stderr,
                    "Warning: unable to create instrumentation file.\n");
        }

        /* Finally, clear the list so we do not repeatedly print the points. */
        instrumentation_data.iid_FirstPoint = NULL;
    }
}

---