+-------------+
      |Actor        |
      |.............|
      |  Actor ID   |
      +-------------+
             ^
             |   0 .. N
             |
             V
      +-------------+
      |I2RS Client  |
      |.............|
      |  Client ID  |
      +-------------+
             ^
             |  1 .. N
             |
             V
      +-------------+                 +-----------------------------+
      |I2RS Agent   |---------------->|Trace Log                    |
      |             |                 |.............................|
      +-------------+                 |Log Entry  [1 .. N]          |
             ^                        |.............................|
             |                        |Timestamp                    |
             |                        |Client ID                    |
             |      ^                 |Actor ID                     |
 Operation + | Result Code            |Client Address               |
  Op Data    |                        |Operation                    |
     V       |                        |Operation Data               |
             |                        |Result Code                  |
             V                        |End Of Message               |
      +-------------+                 +-----------------------------+
      |Routing      |
      |System       |
      +-------------+

Figure 1: I2RS Interaction Trace Log Capture

5.2. I2RS Trace Log Mandatory Fields

In order to ensure that each I2RS interaction can be properly traced back to the Client that made the request at a specific point in time, the following information MUST be collected and stored by the Agent.

The list below describes the fields captured in the I2RS trace log.

Entry ID:

This is a unique identifier for each entry in the I2RS trace log. Since multiple operations can occur from the same client at the same time, it is important to have an identifier that can be unambiguously associated to a specific entry.

Timestamp:

The specific time, adhering to [RFC3339] format, at which the I2RS transaction occurred. Given that many I2RS transactions can occur in rapid succession, the use of fractional seconds MUST be used to provide adequate granularity.

Client Identifier:

The I2RS Client identifier used to authenticate the Client to the I2RS Agent.

Actor Identifier:

This is an opaque identifier that may be known to the Client from a northbound controlling application. This is used to trace the northbound actor driving the actions of the Client. The Client may not provide this identifier to the Agent if there is no external actor driving the Client. However, this field MUST be logged. If the Client does not provide an actor ID, then the Agent MUST log an UNAVAILABLE value in the field.

Client Address:

This is the network address of the client that connected to the Agent. For example, this may be an IPv4 or IPv6 address. [Note: will I2RS support interactions that have no network address? If so this field will need to be updated.]

Operation:

This is the I2RS operation performed. For example, this may be an add route operation if a route is being inserted into a routing table.

Operation Data:

This field comprises the data passed to the Agent to complete the desired operation. For example, if the operation is a route add operation, the Operation Data would include the route prefix, prefix length, and next hop information to be inserted as well as the specific routing table to which the route will be added. The operation data can also include interface information. Some operations may not provide operation data, and in those cases this field MUST be logged as a NULL string.

Result Code:

This field holds the result of the operation. In the case of RIB operations, this MUST be the return code as specified in Section 4 of [I-D.nitinb-i2rs-rib-info-model]. The operation may not complete with a result code in the case of a timeout. If the operation fails to complete, it MUST still log the attempted operation with an appropriate result code (e.g., a result code indicating a timeout).

End Of Message:

Each log entry SHOULD have an appropriate End Of Message (EOM) indicator. See section Section 5.3 below for more details.

5.3. End of Message Marker

Because of variability within I2RS trace log fields, implementors MUST use a format-appropriate end of message (EOM) indicator in order to signify the end of a particular record. That is, regardless of format, the I2RS trace log MUST provide a distinct way of distinguishing between the end of one record and the beginning of another. For example, in a linear formated log (similar to syslog) the EOM marker may be a newline character. In an XML formated log, the schema would provide for element tags that denote beginning and end of records. In a JSON formated log, the syntax would provide record separation (likely by comma-separated array elements).

5.4. I2RS Trace Log Extensibility and Optional Fields

[NOTE: This section is TBD based on further development of I2RS WG milestones.]

6. Examples

Here is a proposed sample of what the fields might look like in an I2RS trace log. This is only an early proposal. These values are subject to change.

Entry ID:       1
Timestamp:      2013-09-03T12:00:01.21+00:00
Client ID:      5CEF1870-0326-11E2-A21F-0800200C9A66
Actor ID:       com.example.RoutingApp
Client Address: 192.0.2.2
Operation:      ROUTE_ADD
Operation Data: PREFIX 203.0.113.0 PREFIX-LEN 24 NEXT-HOP
                198.51.100.1
Result Code:    SUCCESS(0)
        

7. Operational Guidance

Specific operational procedures regarding temporary log storage, rollover, retrieval, and access of I2RS trace logs is out of scope for this document. Organizations employing I2RS trace logging are responsible for establishing proper operational procedures that are appropriately suited to their specific requirements and operating environment. In this section we only provide fundamental and generalized operational guidelines that are implementation-independent.

7.1. Trace Log Creation

The I2RS Agent interacts with the Routing and Signaling functions of the Routing Element. Since the I2RS Agent is responsible for actually making the routing changes on the associated network device, it creates and maintains a log of transactions that can be retrieved to troubleshoot I2RS-related impact to the network.

7.2. Trace Log Temporary Storage

The trace information may be temporarily stored either in an in-memory buffer or as a file local to the Agent. Care should be given to the number of I2RS transactions expected on a given agent so that the appropriate storage medium is used and to maximize the effectiveness of the log while not impacting the performance and health of the Agent. Section 7.3 talks about rotating the trace log in order to preserve the transaction history without exhausting Agent or network device resources. It is perfectly acceptable, therefore, to use both an in-memory buffer for recent transactions while rotating or archiving older transactions to a local file.

It is outside the scope of this document to specify the implementation details (i.e., size, throughput, data protection, privacy, etc.) for the physical storage of the I2RS log file. Data retention policies of the I2RS traceability log is also outside the scope of this document.

7.3. Trace Log Rotation

In order to prevent the exhaustion of resources on the I2RS Agent or its associated network device, it is RECOMMENDED that the I2RS Agent implements trace log rotation. The details on how this is achieved are left to the implementation and outside the scope of this document. However, it should be possible to do file rotation based on either time or size of the current trace log. If file rollover is supported, multiple archived log files should be supported in order to maximize the troubleshooting and accounting benefits of the trace log.

7.4. Trace Log Retrieval

Implementors are free to provide their own, proprietary interfaces and develop custom tools to retrieve and display the I2RS trace log. These may include the display of the I2RS trace log as Command Line Interface (CLI) output. However, a key intention of defining this information model is to establish an implementor-agnostic and consistent interface to collect I2RS trace data. Correspondingly, retrieval of the data should also be made implementor-agnostic.

The following three sections describe potential ways the trace log can be accessed. At least one of these three MUST be used, with the I2RS mechanisms being preferred as they are implementor-independent approaches to retrieving the data.

7.4.1. Retrieval Via Syslog

The syslog protocol [RFC5424] is a standard way of sending event notification messages from a host to a collector. However, the protocol does not define any standard format for storing the messages, and thus implementors of I2RS tracing would be left to define their own format. So, while the data contained within the syslog message would adhere to this information model, and may be consumable by a human operator, it would not be easily parseable by a machine. Therefore, syslog MAY be employed as a means of retrieving or disseminating the I2RS trace log contents.

7.4.2. Retrieval Via I2RS Information Collection

Section 6.7 of the I2RS architecture [I-D.ietf-i2rs-architecture] defines a mechanism for information collection. The information collected includes obtaining a snapshot of a large amount of data from the network element. It is the intent of I2RS to make this data available in an implementor-agnostic fashion. Therefore, the I2RS trace log SHOULD be made available via the I2RS information collection mechanism either as a single snapshot or via a subscription stream.

7.4.3. Retrieval Via I2RS Pub-Sub

Section 6.7 of the I2RS architecture [I-D.ietf-i2rs-architecture] goes on to define a publish-subscribe mechanism for a feed of changes happening within the I2RS layer. I2RS Agents SHOULD support publishing I2RS trace log information to that feed as described in that document. Subscribers would then receive a live stream of I2RS interactions in trace log format and could flexibly choose to do a number of things with the log messages. For example, the subscribers could log the messages to a datastore, aggregate and summarize interactions from a single client, etc. Using pub-sub for the purpose of logging I2RS interactions augments the areas described by [I-D.camwinget-i2rs-pubsub-sec]. The full range of potential activites is virtually limitless and the details of how they are performed are outside the scope of this document, however.

8. IANA Considerations

This document makes no request of IANA.

9. Security Considerations

The I2RS trace log, like any log file, reveals the state of the entity producing it as well as the identifying information elements and detailed interactions of the system containing it. The information model described in this document does not itself introduce any security issues, but it does define the set of attributes that make up an I2RS log file. These attributes may contain sensitive information and thus should adhere to the security, privacy and permission policies of the organization making use of the I2RS log file.

It is outside the scope of this document to specify how to protect the stored log file, but it is expected that adequate precautions and security best practices such as disk encryption, appropriately restrictive file/directory permissions, suitable hardening and physical security of logging entities, mutual authentication, transport encryption, channel confidentiality, and channel integrity if transferring log files. Additionally, the potentially sensitive information contained in a log file SHOULD be adequately anonymized or obfuscated by operators to ensure its privacy.

10. Acknowledgments

The authors would like to thank Alia Atlas for her initial feedback and overall support for this work. Additionally, the authors acknowledge Alvaro Retana, Russ White, Matt Birkner, Jeff Haas, Joel Halpern and Dean Bogdanovich for their reviews, contributed text, and suggested improvements to this document.

11. References

11.1. Normative References

[I-D.ietf-i2rs-architecture]	Atlas, A., Halpern, J., Hares, S., Ward, D. and T. Nadeau, "An Architecture for the Interface to the Routing System", Internet-Draft draft-ietf-i2rs-architecture-00, August 2013.
[I-D.ietf-i2rs-problem-statement]	Atlas, A., Nadeau, T. and D. Ward, "Interface to the Routing System Problem Statement", Internet-Draft draft-ietf-i2rs-problem-statement-00, August 2013.
[RFC2119]	Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.

11.2. Informative References

[I-D.camwinget-i2rs-pubsub-sec]	Beck, K., Cam-Winget, N. and D. McGrew, "Using the Publish-Subscribe Model in the Interface to the Routing System", Internet-Draft draft-camwinget-i2rs-pubsub-sec-00, July 2013.
[I-D.nitinb-i2rs-rib-info-model]	Bahadur, N., Folkes, R., Kini, S. and J. Medved, "Routing Information Base Info Model", Internet-Draft draft-nitinb-i2rs-rib-info-model-02, August 2013.
[RFC3339]	Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, July 2002.
[RFC5424]	Gerhards, R., "The Syslog Protocol", RFC 5424, March 2009.
[RFC5737]	Arkko, J., Cotton, M. and L. Vegoda, "IPv4 Address Blocks Reserved for Documentation", RFC 5737, January 2010.

Authors' Addresses