Logging Schema

See subversion log for revision information: https://redmine.dataone.org/projects/d1/repository/changes/documents/Projects/cicore/architecture/api-documentation/source/design/logging.txt

This schema for logging documents specifies the information returned by DataONE when requests for logs have been made from either Coordinating Nodes or Member Nodes. The log information is maintained dynamically by both the Coordinating Nodes and Member Nodes whenever a significant event occurs for a tracked object in the system. Tracked objects include all data objects and science metadata objects in the system. Events of significance include the insertion, update, deletion, or reading of these objects.

Log data are considered operational information needed to run DataONE, and can be read by all Coordinating Nodes in the course of service provision. In order to reduce issues with third-party tracking of data status information, users can read log information for an object if they have the access rights to read the corresponding object on which the event was logged.

The following list of fields represents the set of information returned upon a request for logging.

Table 1. Quick reference to the Logging fields described in more detail below.

Group	Field	Type	Cardinality
Log
	entryId	Types.IdentifierType	1
	identifier	Types.IdentifierType	1
	ipAddress	String	1
	userAgent	String	1
	principal	Types.PrincipalType	1
	event	Types.EventType	1
	logDate	Types.DateTime	1
	memberNode	Types.NodeReferenceType	1

Logging fields

LoggingSchema.entryId

The identifier of a particular log record, used to differentiate it from other log records on the same objects.

Cardinality:1 ValueSpace:Types.IdentifierType Generated By:Node Required Version:  0.3

LoggingSchema.identifier

The identifier of the object on which a logged event occurred.

Cardinality:1 ValueSpace:Types.IdentifierType Generated By:Node Required Version:  0.3

LoggingSchema.logDate

Date and time (UTC) that the event was logged in the DataONE system.

Cardinality:1 ValueSpace:Types.DateTime, an ISO 8601 Date-time value in UTC Generated By:Node Required Version:  0.3

LoggingSchema.ipAddress

The InternetProtocol address from which an originating event request originated.

Cardinality:1 ValueSpace:String Internet IP address in either IP4 or IP6 syntax Generated By:Node Required Version:  0.3

LoggingSchema.userAgent

A string indicating the type of client software agent that was used by the user to connect to the service and originate the logged event.

Cardinality:1 ValueSpace:Any string value signifying a user software agent and its version. Generated By:Node Required Version:  0.3

LoggingSchema.event

The type of event that was logged, such as an object insertion or deletion.

Cardinality:1 ValueSpace:Types.EventType Generated By:Node Required Version:  0.3

LoggingSchema.principal

Principal who generated the event through a request to the node. If the event was recorded without identifying the principal, then the principal will be recorded as ‘public’.

Cardinality:1 ValueSpace:Types.PrincipalType Generated By:Node Required Version:  0.3

LoggingSchema.memberNode

The Member Node Identifier of the node on which this logged event occurred. This field is used to distinguish log records that occur at the same time on different Member Nodes, such as simultaneous downloads.

Cardinality:1 ValueSpace:Types.NodeReferenceType Generated By:Node Required Version:  0.3

Example Log Instance Document

The example instance document included here was auto-generated so does not include useful values. It is included here to provide a general indication as to the structure of a populated log document.

Log Schema Document

The XSD schema file for the LoggingSchema is included here for reference.