SDA 4.1 Documentation for SDALOG

NAME

sdalog - Generate a report of SDA usage

USAGE

sdalog -g filename [options]

DESCRIPTION

SDALOG reads the SDA logfile and generates a report on SDA usage. Note that the logfile read by SDALOG is the special file written by SDA -- not the access log maintained by the Web server software. The name of the logfile is specified in the SDA Manager as a Global Specification that applies to a group of SDA datasets.

OUTPUT FORMATS

The default output format reports the following information:

how many times each SDA program or procedure was executed,
how many times each dataset (using the name specified in the SDA Manager) was accessed,
and how many of the reported procedures were run in each of the months.

An optional format (used if a '-c' option was specified) reports the following information:

the client addresses
and how many times each client executed an SDA procedure.
If the '-c all' option is used, this style of report will include the full addresses (the hostname, if available, or else the numeric IP).
If the '-c 1', '-c 2', or '-c 3' option is used, then only the last one, two, or three final segments of the hostnames (if available) are displayed. For example, the last segment of the hostname is the top level domain name -- like 'COM' or 'EDU'. If the '-c 1' option is specified, a summary of usage by those top level domains will be generated. (With these options, the numeric IP addresses are not displayed separately; rather, they are combined together and reported as a group.)
Note that the ability to display all or part of a hostname assumes that Tomcat has been configured (when SDA was installed) to resolve IP addresses (usually possible only for a subset of client addresses). See the SDA Installation Guide for more information on configuring Tomcat to show hostnames in the SDA log file.

OPTIONS

The following command-line options are recognized.
Some options affect the logfile -- the pathname of the file, and which records in the logfile should be included in the report. Other options affect the output format -- whether to produce the default output or the optional IP address output.
The only required option is the specification of the name of the logfile.

Log File Options

-g filename: The specified filename is the pathname of a logfile maintained by SDA. (REQUIRED)
-e filename: The specified filename contains a list of client addresses or portions of addresses to exclude from the report. Each address (or portion of an address) should be on a separate line in the file. For example, the client address used by the local system programmer might be excluded from the usual reports. Note that the addresses given in this file are treated as case-insensitive. For example, if '.Com' is specified, all log entries containing '.COM', or '.com' in the address field of the logfile will be excluded from the report.
-f filter_string: Each line of the logfile is scanned for the presence of the specified string of characters. If the string is not contained in a line, that line is excluded from the report.
This option can be repeated. Only the lines containing all of the specified filter strings will be included in the report.
-F filter_string: The specified string of characters is used as a selection filter (as with the '-f' option). However, the filter string is case-insensitive. In other words, if the specified filter string is 'gss', lines containing 'gss', 'GSS', or 'Gss' will all be included in the report.
This option can be repeated. Only the lines containing all of the specified filter strings will be included in the report.
-s study_name: In each line of the logfile, the field containing the name of the study or dataset is scanned for the presence of the specified study name. If the specified study name is not in a line, that line is excluded from the report. Note that the study names given in this file are treated as case-insensitive.
This option can be repeated, in order to include multiple specified studies in the report.

Output Options

-o filename

Output from SDALOG will be written to this file. If this option is not specified, output will be routed to the user's screen (standard output).

-c all

The report will list the full client addresses (hostnames, if available, or numeric addresses) of the computers used by the SDA users (instead of the default output format). The number of procedures executed by each client will also be reported.

-c 1

Only the last segment of hostnames (top level domains like EDU, COM, NET, etc.) will be reported (instead of the full hostname of each user). Numeric IP addresses will not be listed; rather, they will be combined into a single group.

-c 2

The last 2 segments of hostnames will be reported.

-c 3

The last 3 segments of hostnames will be reported.

Miscellaneous Options

-x filename

Write lines with badly formed log entries (if any) into this file. This option is for diagnostic purposes.

-u

Print out a list of options (but do not execute the program)

EXAMPLES

Basic example: sdalog -g SDAlog -o logreport.txt
Filter for a specific dataset (GSS2020): sdalog -g SDAlog -s gss2020 -o logreport.txt
Get the top level domains of users: sdalog -g SDAlog -c 1 -o logreport.txt

CSM, UC Berkeley/ISA
April 14, 2021