2.4 Common System Logger services and reporting

< Day Day Up >

2.4 Common System Logger services and reporting

System Logger provides a set of services to manage the log data that has been passed to it and to exploit log stream functions. The services allow you to define a log stream, connect to it, and to write, read, and delete data from the log stream. When System Logger encounters an error, the resulting console message will usually include the name of the service that encountered the problem.

Defining, updating and deleting the log stream - IXGINVNT

The IXGINVNT macro is similar to IXCMIAPU in that it is used to define, maintain and delete CF-Structure and DASD-only log stream information in the System Logger policy.

Using IXGINVNT, an exploiter can:

Define and update log stream definitions using REQUEST=DEFINE or REQUEST=UPDATE with TYPE=LOGSTREAM.
Define a CF structure that is to be associated with a log stream using REQUEST=DEFINE with TYPE=STRUCTURE.
Delete log stream and CF structure definitions using REQUEST=DELETE.

We will discuss log stream and CF structure definition parameters in 2.5, "Log streams" on page 22.

Connecting to a log stream - IXGCONN

Before you can write, browse, or delete data from a log stream, you must be connected to it. Exploiters use the IXGCONN service to establish a connection to the log stream specified in the request by specifying REQUEST=CONNECT. The service will return a unique connection identifier, called a STREAMTOKEN. This is used in subsequent System Logger service requests to identify the exploiter's connection.

The calling program must also request authorization to the log stream:

If AUTH=READ is specified, that application will only be able to issue IXGCONN, IXGBRWSE, and IXGQUERY requests. For AUTH=READ, the caller must have READ access to RESOURCE(log_stream_name) in CLASS(LOGSTRM).
If AUTH=WRITE is specified, that program can request any System Logger service. For AUTH=WRITE, the caller must have UPDATE access to RESOURCE(log_stream_name) in CLASS(LOGSTRM).

An exploiter can connect to the log stream in different ways, for example:

One Connection per Address Space: Once a program has connected to a log stream, any task running in the same address space shares the connect status and can use the same stream token to request other System Logger services. Any task in the address space can disconnect the entire address space from the log stream by issuing the IXGCONN REQUEST=DISCONNECT call.
One Connection Per Program: One or more tasks in a single address space can issue IXGCONN REQUEST=CONNECT individually to connect to the same log stream and receive separate stream tokens. Each program must disconnect from the log stream individually.
Multiple Systems Connecting to a Log Stream: Multiple address spaces on one or more z/OS systems can connect to a single CF log stream, but each one must issue IXGCONN individually to connect to and then disconnect from the log stream. Each one receives a unique stream token; multiple address spaces cannot share a stream token.

The IXGCONN service is also used to disconnect from the log stream by issuing REQUEST=DISCONNECT and specifying the STREAMTOKEN received on connect. This will invalidate the stream token; any future services specifying that token would fail.

When connecting to a log stream, there are additional considerations to be taken into account for each type.

CF-Structure based log streams

When an application issues IXGCONN to connect to a CF-Structure based log stream:

If it is the first connector to the CF structure in this system, the System Logger address space will establish a connection to the structure.
If it is the first connection to the structure in the sysplex, the structure will be allocated.

DASD-only log streams

DASD-only log streams are single system scope; that is, you can only establish connections from one system in the sysplex at a time to a given DASD-only log stream. Any other systems in the sysplex that attempt to connect will fail until all the connections to the log stream from the connected system have been disconnected. However, there can be multiple connections from the same system to a DASD-only log stream.

Note

For both CF-Structure based (if using staging data sets) and DASD-only log streams, the first connect to the log stream from a given system will result in staging data sets being created.

For more information on using the IXGCONN service, see topic 27.4.5 in z/OS MVS Assembler Services Guide, SA22-7605.

Writing data to a log stream - IXGWRITE

Now that the exploiter is connected to the log stream, log records can be written to it. The IXGWRITE service is used to write data to a log stream. The data is stored in interim storage until it can be offloaded (see 2.6, "Offload processing" on page 57 for more information on offload):

For CF-Structure based log streams, System Logger writes the data to the CF structure space associated with the log stream when an IXGWRITE request is issued. System Logger also duplexes the data to either a System Logger-owned dataspace or a staging data set. For more information on duplexing log data, see 2.8.1, "Failure independence" on page 65.
For DASD-only log streams, System Logger writes the data to interim storage in a System Logger-owned dataspace for the system associated with the log stream and simultaneously to a staging data set on DASD.

Note

Log data stored in interim storage is duplexed. For more information, see "Duplexing log data for CF-Structure based log streams" on page 42 and "Duplexing log data for DASD-only log streams" on page 54.

Log blocks can be written either synchronously or asynchronously, depending on the MODE specified on the System Logger IXGWRITE request. Before data can be written out to the log stream, it must be placed in a buffer to form the log block. System Logger has no requirements for the format of the data in log blocks (except that the log blocks cannot be larger than 65532 bytes); it is entirely up to the exploiter as to how the data within the log block is created and used.

For each log block written to the log stream, System Logger will return a unique identifier (the BLOCKID) which can be used on subsequent IXGDELET and IXGBRWSE requests to search for, delete, read, or set the browse cursor position to that log block. For CF-Structure log streams, the BLOCKID is returned by the CF, ensuring that the BLOCKID is unique for that log stream across the whole sysplex. For DASD-only log streams, because each log stream is only accessed by one system, the BLOCKID is generated by System Logger itself.

The BLOCKID is used when an exploiter wants to retrieve log blocks from System Logger. However, if the data within the log block is going to be used for a time-sensitive task such as recovering a database, the exploiter is responsible for timestamping its log records, and sorting its log records into the correct time order. It cannot assume ascending BLOCKIDs necessarily indicate correspondingly ascending times when the log records were created.

Note

It is important to understand that System Logger does not guarantee log blocks will be sequenced in the order they were written using the IXGWRITE service. Instead, log blocks are written in the order they are received by System Logger; if you have multiple applications writing to the same log stream, System Logger might not receive them in the same order they were written. System Logger does generate a time stamp in both local and Greenwich mean time (GMT) that indicates the time that the log block was processed. This can be returned to the application by specifying the TIMESTAMP parameter.

An imbedded application time stamp will not effect the order in which log blocks are written; if an application needs to ensure that log blocks are received into the log stream in the order written, the application can serialize on the log stream.

Let's discuss the logic of how log blocks are written to System Logger; that is, where do log blocks go? Figure 2-2 on page 19 contains a graphical depiction of System Logger writes. For a CF-Structure based log stream, the log blocks are first written to the CF structure (interim storage) and then duplexed to either staging data sets, a System Logger-owned dataspace, or another CF structure (depending on several different factors, see "Duplexing log data for CF-Structure based log streams" on page 42 for more information). For a DASD-only log stream, log blocks are written to a System Logger-owned dataspace and then duplexed to staging data sets (see "Duplexing log data for DASD-only log streams" on page 54).

click to expand
Figure 2-2: Writing to a System Logger log stream

Browsing and reading log data - IXGBRWSE

Applications can use the IXGBRWSE service to read and browse a log stream for log block information. IXGBRWSE can be used to read consecutive blocks in a log stream or search for and read a specific log block. IXGBRWSE returns the specified log block to the calling program's buffer.

The IXGBRWSE service requires that you have an existing connection. To browse a log stream, exploiters use the following requests:

Start a browse session and select the initial cursor position - REQUEST=START. This will return a 4-byte browse token; subsequent requests will use this token to identify this browse session. It is possible to have multiple browse sessions running concurrently. Each browse session also has a browse cursor that points to the current location in the log stream. You can specify the starting position of the browse cursor using one of the following optional keywords:
- OLDEST - which is the default, starts the browse session at the oldest (earliest) log block.
- YOUNGEST - starts the browse session at the youngest (latest) log block. Note that the record that is the youngest when the browse session starts might no longer be the youngest record at the end of the browse session because of concurrent write activity to the log stream.
- STARTBLOCKID - specifies that the browse session start at a specified log block identifier. The block identifier for a log block is returned by System Logger when it is written to the log stream (IXGWRITE) in the field specified by the RETBLOCKID parameter.
- SEARCH - specifies that the browse session start at the log block with the specified time stamp. See topic 27.4.7.4 in z/OS MVS Assembler Services Guide, SA22-7605, for details on how IXGBRWSE processes time stamps.
REQUEST=RESET positions the browse cursor to either the oldest or youngest (POSITION=OLDEST or POSITION=YOUNGEST) log block in the log stream.
REQUEST=READBLOCK reads a selected log block in the log stream. You identify the block you want to read by either the block identifier (BLOCKID parameter) or the timestamp (SEARCH parameter). The block identifier for a log block is returned by System Logger in the field specified by the RETBLOCKID parameter when the log block is written to the log stream (IXGWRITE).
REQUEST=READCURSOR reads the next oldest or youngest log block or blocks in the log stream, depending on the direction specified on the request (DIRECTION=OLDTOYOUNG or YOUNGTOOLD). The block or blocks read also depend on the position of the cursor at the time you issue the request. The MULTIBLOCK parameter determines whether one or more blocks will be returned; System Logger will return as many complete log blocks that meet the browse parameter criteria and fit in the caller's buffer.
End a browse session - (REQUEST=END). This will result in the browse token being invalidated.

Note

Here are some further notes on the IXGBRWSE service:

The IXGBRWSE service can be used to browse just active data or all data - even blocks that have been logically deleted (but not physically deleted yet).
A browse session may result in an offload data set that has been migrated being recalled; this can cause elongated response times.

Deleting log data - IXGDELET

Using the IXGDELET service, exploiters can mark some or all of their log blocks in the log stream for deletion. For a CF-Structure log stream, the group of blocks you specify for deletion can reside in both the CF and offload data sets. For a DASD-only log stream, the group of blocks you specify for deletion can reside in both the System Logger-owned dataspace and offload data sets. The way System Logger processes log data that is marked for deletion depends on whether a retention period and automatic deletion have been specified for a log stream in the LOGR CDS. For more information on how System Logger deletes log data, refer to 2.7, "Deleting log data" on page 62.

Applications use the BLOCKS parameter to specify a range of blocks to be deleted:

Either all log blocks are deleted or
A log block ID is specified, in which case System Logger will delete all log blocks from the log stream that are older than that blockid.

You will note that IXGDELET only marks the log blocks for deletion (that is, they are logically rather than physically deleted). The actual deletion takes place during offload processing, or subsequently when the offload data set is deleted. IXGDELET is the only way that log blocks get logically deleted—if an IXGDELET is not issued for a log block, the log block will not be deleted until it has been offloaded and all the log blocks in the offload data set have exceeded their retention period (assuming AUTODELETE(YES) is specified).

Required access levels

Before using any of these services, you will have to grant access to the classes and resources as shown in Table 2-2.

Table 2-2: Required SAF accesses for System Logger services
Defining SAF Authorization For System Logger Resources
System Logger Service	Access Type	SAF class and resource
IXGINVNT REQUEST=DEFINE, TYPE=LOGSTREAM	ALTER	RESOURCE(log_stream_name) CLASS(LOGSTRM)
IXGINVNT REQUEST=UPDATE, TYPE=LOGSTREAM
IXGINVNT REQUEST=DELETE, TYPE=LOGSTREAM
IXGINVNT REQUEST=DEFINE, TYPE=LOGSTREAM, STRUCTNAME=structname	ALTER	RESOURCE(log_stream_name) CLASS(LOGSTRM)
	UPDATE	RESOURCE(IXLSTR.structure_name) CLASS(FACILITY)
IXGINVNT REQUEST=DEFINE, TYPE=LOGSTREAM, LIKE=like_log_stream_name	ALTER	RESOURCE(log_stream_name) CLASS(LOGSTRM)
	UPDATE	RESOURCE(like_log_stream) CLASS(LOGSTRM)
		RESOURCE(IXLSTR.like_structure_name) CLASS(FACILITY)
IXGINVNT REQUEST=DEFINE, TYPE=STRUCTURE	ALTER	RESOURCE(MVSADMIN.LOGR) CLASS(FACILITY)
IXGINVNT REQUEST=DELETE, TYPE=STRUCTURE
IXGCONN REQUEST=CONNECT, AUTH=WRITE	UPDATE	RESOURCE(log_stream_name) CLASS(LOGSTRM)
IXGCONN REQUEST=CONNECT, AUTH=READ	READ	RESOURCE(log_stream_name) CLASS(LOGSTRM)

Return and reason codes for System Logger services can be found in z/OS MVS Authorized Assembler Services Reference ENF-IXG, SA22-7610.

< Day Day Up >