Issues for Lightweight Log FTF
To comment on any of these issues, send email to lwlog-ftf@omg.org. (Please include the issue number in the Subject: header, thusly: [Issue ###].) To submit a new issue, send email to issues@omg.org.
List of issues (green=resolved, yellow=pending Board vote, red=unresolved)
Issue 5767: Adding some filtering capabilities to the Lightweight Logging Service
Issue 5767: Adding some filtering capabilities to the Lightweight Logging Service (lwlog-ftf)
Click here for this issue's archive.
Source: THALES (Ms. Virginie Watine, virginie.watine(at)thalesgroup.com)
Nature: Uncategorized Issue
Severity:
Summary:
In order to add some possibilities to filter records, we would like methods
that retrieve log records according to the fields defined in struct
ProducerLogRecord (namely the level, producerId and producerName).
That would consist in the three following methods to be added on the
LogConsumer object.
That point has been discussed during the Yokohama meeting with the
supporters of this submission (in particular with Jeff Smith) and no
difficulty to add these methods was foreseen.
Resolution: see above
Revised Text: In the document Lightweight Log Service Specification - OMG Final Adopted Specification ptc/03/04/01
UPDATE figure 2-1 with the new/changed operations
REPLACE all occurrences of retrieve_by_id with retrieve_records
REPLACE all occurrences of retrieveById with retrieveRecords with the exception of Sections 2.4.1 and 3.3.2.1
Section 2.4.1 CHANGE
FROM:
The getRecordIdFromTime operation returns the record Id of the first record in the Log with a time stamp that is greater than, or equal to, the time specified in the fromTime parameter. If the Log does not contain a record that meets the criteria provided, then the RecordId returned corresponds to the next record that will be recorded in the future. In this way, if this "future" recordId is passed into the retrieveById operation, an empty record will be returned unless records have been recorded since the time specified. Note that if the time specified in the fromTime parameter is in the future, there is no guarantee that the resulting records returned by the retrieveById operation will have a time stamp after the fromTime parameter if the returned recordId from this invocation of the getRecordIdFromTime operation is subsequently used as input to the retrieveById operation.
TO:
The getRecordIdFromTime operation returns the record Id of the first record in the Log with a time stamp that is greater than, or equal to, the time specified in the fromTime parameter. If the Log does not contain a record that meets the criteria provided, then the RecordId returned corresponds to the next record that will be recorded in the future. In this way, if this "future" recordId is passed to a retrieval operation, an empty record will be returned unless records have been recorded since the time specified. Note that if the time specified in the fromTime parameter is in the future, there is no guarantee that the resulting records returned by a retrieval operation will have a time stamp after the fromTime parameter if the returned recordId from this invocation of the getRecordIdFromTime operation is subsequently used as input to a retrieval operation.
Section 3.3.2.1 CHANGE
FROM:
The get_record_id_from_time operation returns the record Id of the first record in the Log with a time stamp that is greater than, or equal to, the time specified in the fromTime parameter. If the Log does not contain a record that meets the criteria provided, then the RecordId returned corresponds to the next record that will be recorded in the future. In this way, if this "future" recordId is passed into the retrieveById operation, an empty record will be returned unless records have been recorded since the time specified. Note that if the time specified in the fromTime parameter is in the future, there is no guarantee that the resulting records returned by the retrieveById operation will have a time stamp after the fromTime parameter if the returned recordId from this invocation of the get_record_id_from_time operation is subsequently used as input to the retrieveById operation.
TO:
The get_record_id_from_time operation returns the record Id of the first record in the Log with a time stamp that is greater than, or equal to, the time specified in the fromTime parameter. If the Log does not contain a record that meets the criteria provided, then the RecordId returned corresponds to the next record that will be recorded in the future. In this way, if this "future" recordId is passed into a retrieval operation, an empty record will be returned unless records have been recorded since the time specified. Note that if the time specified in the fromTime parameter is in the future, there is no guarantee that the resulting records returned by a retrieval operation will have a time stamp after the fromTime parameter if the returned recordId from this invocation of the get_record_id_from_time operation is subsequently used as input to a retrieval operation.
Add new sections to the LogConsumer Interface Operations starting with 2.4.3
2.4.3 retrieveRecordsByLevel
Retrieves a specified number of records from the Log that correspond to the provided log levels.
Synopsis
+ retrieveRecordsByLevel (inout currentId : RecordId,
inout howMany : unsigned long,
in valueList : LogLevelSequence)
: LogRecordSequence
Parameters and Return
(ADD the Table with headings Parameter Type Description
currentId RecordId The ID of the starting record
howMany unsigned long The number of records to retrieve, will be updated to the number of records actually retrieved.
valueList LogLevelSequence The sequence of log levels that will be sought
<return> LogRecordSequence The sequence of retrieved records
)
Exceptions
This operation raises the InvalidParam exception if a supplied parameter is invalid.
Description
The retrieveRecordsByLevel operation returns a LogRecordSequence of records that correspond to the supplied LogLevels. Refer to section 2.2.2. The valueList parameter is composed of an undefined number of LogLevels. Candidate records for the LogRecordSequence begin with the record specified by the currentId parameter. The number of records in the LogRecordSequence returned by the retrieveRecordsByLevel operation is equal to the number of records specified by the howMany parameter, or the number of records available if the number of records specified by the howMany parameter cannot be met. The log will update howMany to indicate the number of records returned and will set currentId to either the id of the record following the last examined record or the next record that will be recorded in the future, if there are no further records available. If the record specified by currentId does not exist, but corresponds to the next record that will be recorded in the future, the retrieveRecordsByLevel operation returns an empty list of LogRecords, sets howMany to zero, and leaves the value of currentId unchanged. If the record specified by currentId does not exist and does not correspond to the next record that will be recorded in the future, or if the Log is empty, the retrieveRecordsByLevel operation returns an empty list of LogRecords, and sets both currentId and howMany to zero. Note that this operation does not guarantee a return of sequential records in Log and modifies the currentId value. Consequently, subsequent invocations of this operation with a different valueList or the other retrieval operations before reestablishing a record ID with the getRecordIdFromTime operation may result in the Log consumer not being able to obtain some of the records.
2.4.4 retrieveRecordsByProducerId
Retrieves a specified number of records from the Log that correspond to the provided producer IDs.
Synopsis
+ retrieveRecordsByProducerId (inout currentId : RecordId,
inout howMany : unsigned long,
in valueList : StringSequence)
: LogRecordSequence
Parameters and Return
(ADD the Table with headings Parameter Type Description
currentId RecordId The ID of the starting record
howMany unsigned long The number of records to retrieve, will be updated to the number of records actually retrieved.
valueList StringSequence The sequence of producer IDs that will be sought
<return> LogRecordSequence The sequence of retrieved records
)
Exceptions
This operation raises the InvalidParam exception if a supplied parameter is invalid.
Description
The retrieveRecordsByProducerId operation returns a LogRecordSequence of records that correspond to the supplied producerIds. Refer to section 2.2.11. The valueList parameter is composed of an undefined number of producerIds. Candidate records for the LogRecordSequence begin with the record specified by the currentId parameter. The number of records in the LogRecordSequence returned by the retrieveRecordsByProducerId operation is equal to the number of records specified by the howMany parameter, or the number of records available if the number of records specified by the howMany parameter cannot be met. The log will update howMany to indicate the number of records returned and will set currentId to either the id of the record following the last examined record or the next record that will be recorded in the future, if there are no further records available. If the record specified by currentId does not exist, but corresponds to the next record that will be recorded in the future, the retrieveRecordsByProducerId operation returns an empty list of LogRecords, sets howMany to zero, and leaves the value of currentId unchanged. If the record specified by currentId does not exist and does not correspond to the next record that will be recorded in the future, or if the Log is empty, the retrieveRecordsByProducerId operation returns an empty list of LogRecords, and sets both currentId and howMany to zero. Note that this operation does not guarantee a return of sequential records in Log and modifies the currentId value. Consequently, subsequent invocations of this operation with a different valueList or the other retrieval operations before reestablishing a record ID with the getRecordIdFromTime operation may result in the Log consumer not being able to obtain some of the records.
2.4.5 retrieveRecordsByProducerName
Retrieves a specified number of records from the Log that correspond to the provided producer names.
Synopsis
+ retrieveRecordsByProducerName (inout currentId : RecordId,
inout howMany : unsigned long,
in valueList : StringSequence)
: LogRecordSequence
Parameters and Return
(ADD the Table with headings Parameter Type Description
currentId RecordId The ID of the starting record
howMany unsigned long The number of records to retrieve, will be updated to the number of records actually retrieved.
valueList StringSequence The sequence of producer names that will be sought
<return> LogRecordSequence The sequence of retrieved records
)
Exceptions
This operation raises the InvalidParam exception if a supplied parameter is invalid.
Description
The retrieveRecordsByProducerName operation returns a LogRecordSequence of records that correspond to the supplied producerNames. Refer to section 2.2.11. The valueList parameter is composed of an undefined number of producerNames. Candidate records for the LogRecordSequence begin with the record specified by the currentId parameter. The number of records in the LogRecordSequence returned by the retrieveRecordsByProducerName operation is equal to the number of records specified by the howMany parameter, or the number of records available if the number of records specified by the howMany parameter cannot be met. The log will update howMany to indicate the number of records returned and will set currentId to either the id of the record following the last examined record or the next record that will be recorded in the future, if there are no further records available. If the record specified by currentId does not exist, but corresponds to the next record that will be recorded in the future, the retrieveRecordsByProducerName operation returns an empty list of LogRecords, sets howMany to zero, and leaves the value of currentId unchanged. If the record specified by currentId does not exist and does not correspond to the next record that will be recorded in the future, or if the Log is empty, the retrieveRecordsByProducerName operation returns an empty list of LogRecords, and sets both currentId and howMany to zero. Note that this operation does not guarantee a return of sequential records in Log and modifies the currentId value. Consequently, subsequent invocations of this operation with a different valueList or the other retrieval operations before reestablishing a record ID with the getRecordIdFromTime operation may result in the Log consumer not being able to obtain some of the records.
Modify the LogConsumer Interface Section 3.3.2
interface LogConsumer : LogStatus
{
RecordId
get_record_id_from_time (
in LogTime fromTime)
raises(InvalidParam);
LogRecordSequence
retrieve_records (
inout RecordId currentId,
inout unsigned long howMany)
raises(InvalidParam);
LogRecordSequence
retrieve_records_by_level(
inout RecordId currentId,
inout unsigned long howMany,
in LogLevelSequence valueList)
raises(InvalidParam);
LogRecordSequence
retrieve_records_by_producer_id(
inout RecordId currentId,
inout unsigned long howMany,
in StringSeq valueList)
raises(InvalidParam);
LogRecordSequence
retrieve_records_by_producer_name(
inout RecordId currentId,
inout unsigned long howMany,
in StringSeq valueList)
raises(InvalidParam);
};
Add new sections to the LogConsumer Interface PSM starting with 3.3.2.3
3.3.2.3 retrieve_records_by_level
Retrieves a specified number of records from the Log that correspond to the provided log levels.
Parameters and Return
(ADD the Table with headings Parameter Type Description
currentId RecordId The ID of the starting record.
howMany unsigned long The number of records to retrieve.
valueList LogLevelSequence The sequence of log levels that will be sought
<return> LogRecordSequence The sequence of retrieved records
)
Exceptions
This operation raises the InvalidParam exception if a supplied parameter is invalid.
Description
The retrieve_records_by_level operation returns a LogRecordSequence of records that correspond to the supplied LogLevels. Candidate records for the LogRecordSequence begin with the record specified by the currentId parameter. The number of records in the LogRecordSequence returned by the retrieve_records_by_level operation is equal to the number of records specified by the howMany parameter, or the number of records available if the number of records specified by the howMany parameter cannot be met. The log will update howMany to indicate the number of records returned and will set currentId to either the id of the record following the last examined record or the next record that will be recorded in the future, if there are no further records available. If the record specified by currentId does not exist, but corresponds to the next record that will be recorded in the future, the retrieve_records_by_level operation returns an empty list of LogRecords, sets howMany to zero, and leaves the value of currentId unchanged. If the record specified by currentId does not exist and does not correspond to the next record that will be recorded in the future, or if the Log is empty, the retrieve_records_by_level operation returns an empty list of LogRecords, and sets both currentId and howMany to zero. Note that this operation does not guarantee a return of sequential records in Log and modifies the currentId value. Consequently, subsequent invocations of this operation with a different valueList or the other retrieval operations before reestablishing a record ID with the get_record_id_from_time operation may result in the Log consumer not being able to obtain some of the records.
Mapping from the Platform Independent Model
This IDL operation definition is the result of a one-to-one mapping from operation
retrieveRecordsByLevel, defined in the UML class Log and made visible through interface LogConsumer in the PIM (See Section 2.4.3, "retrieveRecordsByLevel," on page 2-XXX). The spelling of the operation name has been changed to conform to the OMG IDL Style Guide.
Difference to the Telecom Log Service
This is a new operation, not available in the Telecom Log Service. It reflects the architectural and operational difference between the two services.
3.3.2.4 retrieve_records_by_producer_id
Retrieves a specified number of records from the Log that correspond to the provided producer IDs.
Parameters and Return
(ADD the Table with headings Parameter Type Description
currentId RecordId The ID of the starting record.
howMany unsigned long The number of records to retrieve.
valueList StringSeq The sequence of producer IDs that will be sought
<return> LogRecordSequence The sequence of retrieved records
)
Exceptions
This operation raises the InvalidParam exception if a supplied parameter is invalid.
Description
The retrieve_records_by_producer_id operation returns a LogRecordSequence of records that correspond to the supplied producerIds. Candidate records for the LogRecordSequence begin with the record specified by the currentId parameter. The number of records in the LogRecordSequence returned by the retrieve_records_by_producer_id operation is equal to the number of records specified by the howMany parameter, or the number of records available if the number of records specified by the howMany parameter cannot be met. The log will update howMany to indicate the number of records returned and will set currentId to either the id of the record following the last examined record or the next record that will be recorded in the future, if there are no further records available. If the record specified by currentId does not exist, but corresponds to the next record that will be recorded in the future, the retrieve_records_by_producer_id operation returns an empty list of LogRecords, sets howMany to zero, and leaves the value of currentId unchanged. If the record specified by currentId does not exist and does not correspond to the next record that will be recorded in the future, or if the Log is empty, the retrieve_records_by_producer_id operation returns an empty list of LogRecords, and sets both currentId and howMany to zero. Note that this operation does not guarantee a return of sequential records in Log and modifies the currentId value. Consequently, subsequent invocations of this operation with a different valueList or the other retrieval operations before reestablishing a record ID with the get_record_id_from_time operation may result in the Log consumer not being able to obtain some of the records.
Mapping from the Platform Independent Model
This IDL operation definition is the result of a one-to-one mapping from operation
retrieveRecordsByProducerId, defined in the UML class Log and made visible through interface LogConsumer in the PIM (See Section 2.4.4, "retrieveRecordsByProducerId," on page 2-XXX). The spelling of the operation name has been changed to conform to the OMG IDL Style Guide.
Difference to the Telecom Log Service
This is a new operation, not available in the Telecom Log Service. It reflects the architectural and operational difference between the two services.
3.3.2.5 retrieve_records_by_producer_name
Retrieves a specified number of records from the Log that correspond to the provided producer names.
Parameters and Return
(ADD the Table with headings Parameter Type Description
currentId RecordId The ID of the starting record.
howMany unsigned long The number of records to retrieve.
valueList StringSeq The sequence of producer names that will be sought
<return> LogRecordSequence The sequence of retrieved records
)
Exceptions
This operation raises the InvalidParam exception if a supplied parameter is invalid.
Description
The retrieve_records_by_producer_name operation returns a LogRecordSequence of records that correspond to the supplied producerNames. Candidate records for the LogRecordSequence begin with the record specified by the currentId parameter. The number of records in the LogRecordSequence returned by the retrieve_records_by_producer_name operation is equal to the number of records specified by the howMany parameter, or the number of records available if the number of records specified by the howMany parameter cannot be met. The log will update howMany to indicate the number of records returned and will set currentId to either the id of the record following the last examined record or the next record that will be recorded in the future, if there are no further records available. If the record specified by currentId does not exist, but corresponds to the next record that will be recorded in the future, the retrieve_records_by_producer_name operation returns an empty list of LogRecords, sets howMany to zero, and leaves the value of currentId unchanged. If the record specified by currentId does not exist and does not correspond to the next record that will be recorded in the future, or if the Log is empty, the retrieve_records_by_producer_name operation returns an empty list of LogRecords, and sets both currentId and howMany to zero. Note that this operation does not guarantee a return of sequential records in Log and modifies the currentId value. Consequently, subsequent invocations of this operation with a different valueList or the other retrieval operations before reestablishing a record ID with the get_record_id_from_time operation may result in the Log consumer not being able to obtain some of the records.
Mapping from the Platform Independent Model
This IDL operation definition is the result of a one-to-one mapping from operation
retrieveRecordsByProducerName, defined in the UML class Log and made visible through interface LogConsumer in the PIM (See Section 2.4.5, "retrieveRecordsByProducerName," on page 2-XXX). The spelling of the operation name has been changed to conform to the OMG IDL Style Guide.
Difference to the Telecom Log Service
This is a new operation, not available in the Telecom Log Service. It reflects the architectural and operational difference between the two services.
Add new operations to the Complete Logging Service IDL Section 4
After the producer log sequence typedef
typedef sequence<LogLevel> LogLevelSequence;
typedef sequence<string> StringSeq;
After the retrieve_by_id(records) operation
LogRecordSequence retrieve_records_by_level(
inout RecordId currentId,
inout unsigned long howMany,
in LogLevelSequence valueList)
raises(InvalidParam);
LogRecordSequence retrieve_records_by_producer_id(
inout RecordId currentId,
inout unsigned long howMany,
in StringSeq valueList)
raises(InvalidParam);
LogRecordSequence retrieve_records_by_producer_name(
inout RecordId currentId,
inout unsigned long howMany,
in StringSeq valueList)
raises(InvalidParam);
Actions taken:
November 26, 2002: received issue
November 6, 2003: closed issue
Discussion: Resolution:
Agreed to introduce filtering and modify the name of the retrieve by id operation to better align with the new operations