Internet Engineering Task Force (IETF) J. Clarke
Request for Comments: 7922 G. Salgueiro
Category: Informational C. Pignataro
ISSN: 2070-1721 Cisco
June 2016
Internet Engineering Task Force (IETF) J. Clarke
Request for Comments: 7922 G. Salgueiro
Category: Informational C. Pignataro
ISSN: 2070-1721 Cisco
June 2016
Interface to the Routing System (I2RS) Traceability: Framework and Information Model
路由系统接口（I2RS）可追溯性：框架和信息模型
Abstract
摘要
This document describes a framework for traceability in the Interface to the Routing System (I2RS) and the information model for that framework. It specifies the motivation, requirements, and use cases, and defines an information model for recording interactions between elements implementing the I2RS protocol. This framework provides a consistent tracing interface for components implementing the I2RS architecture to record what was done, by which component, and when. It aims to improve the management of I2RS implementations, and can be used for troubleshooting, auditing, forensics, and accounting purposes.
本文档描述了路由系统（I2RS）接口的可追溯性框架以及该框架的信息模型。它指定了动机、需求和用例，并定义了用于记录实现I2RS协议的元素之间交互的信息模型。该框架为实现I2RS体系结构的组件提供了一个一致的跟踪接口，以记录完成了什么、由哪个组件完成了什么以及何时完成。它旨在改进I2RS实现的管理，并可用于故障排除、审计、取证和会计目的。
Status of This Memo
关于下段备忘
This document is not an Internet Standards Track specification; it is published for informational purposes.
本文件不是互联网标准跟踪规范；它是为了提供信息而发布的。
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Not all documents approved by the IESG are a candidate for any level of Internet Standard; see Section 2 of RFC 7841.
本文件是互联网工程任务组（IETF）的产品。它代表了IETF社区的共识。它已经接受了公众审查，并已被互联网工程指导小组（IESG）批准出版。并非IESG批准的所有文件都适用于任何级别的互联网标准；见RFC 7841第2节。
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7922.
有关本文件当前状态、任何勘误表以及如何提供反馈的信息，请访问http://www.rfc-editor.org/info/rfc7922.
Copyright Notice
版权公告
Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved.
版权所有（c）2016 IETF信托基金和确定为文件作者的人员。版权所有。
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
本文件受BCP 78和IETF信托有关IETF文件的法律规定的约束(http://trustee.ietf.org/license-info)自本文件出版之日起生效。请仔细阅读这些文件，因为它们描述了您对本文件的权利和限制。从本文件中提取的代码组件必须包括信托法律条款第4.e节中所述的简化BSD许可证文本，并提供简化BSD许可证中所述的无担保。
Table of Contents
目录
1. Introduction ....................................................3
2. Terminology and Conventions .....................................3
3. Motivation ......................................................4
4. Use Cases .......................................................4
5. Information Model ...............................................5
5.1. I2RS Traceability Framework ................................5
5.2. I2RS Trace Log Fields ......................................7
5.3. End of Message Marker .....................................11
6. Examples .......................................................11
7. Operational Guidance ...........................................11
7.1. Trace Log Creation ........................................12
7.2. Trace Log Temporary Storage ...............................12
7.3. Trace Log Rotation ........................................13
7.4. Trace Log Retrieval .......................................13
7.4.1. Retrieval via Syslog ...............................14
7.4.2. Retrieval via I2RS Information Collection ..........14
7.4.3. Retrieval via I2RS Pub/Sub .........................14
8. Security Considerations ........................................15
9. References .....................................................16
9.1. Normative References ......................................16
9.2. Informative References ....................................16
Acknowledgments ...................................................17
Authors' Addresses ................................................17
1. Introduction ....................................................3
2. Terminology and Conventions .....................................3
3. Motivation ......................................................4
4. Use Cases .......................................................4
5. Information Model ...............................................5
5.1. I2RS Traceability Framework ................................5
5.2. I2RS Trace Log Fields ......................................7
5.3. End of Message Marker .....................................11
6. Examples .......................................................11
7. Operational Guidance ...........................................11
7.1. Trace Log Creation ........................................12
7.2. Trace Log Temporary Storage ...............................12
7.3. Trace Log Rotation ........................................13
7.4. Trace Log Retrieval .......................................13
7.4.1. Retrieval via Syslog ...............................14
7.4.2. Retrieval via I2RS Information Collection ..........14
7.4.3. Retrieval via I2RS Pub/Sub .........................14
8. Security Considerations ........................................15
9. References .....................................................16
9.1. Normative References ......................................16
9.2. Informative References ....................................16
Acknowledgments ...................................................17
Authors' Addresses ................................................17
The architecture for the Interface to the Routing System [RFC7921] specifies that I2RS clients wishing to retrieve or change the routing state on a routing element MUST authenticate to an I2RS agent. The I2RS client will have a unique identity it provides for authentication, and should provide another opaque identity for applications communicating through it. The programming of routing state will produce a return code containing the results of the specified operation and associated reason(s) for the result. All of this is critical information to be used for understanding the history of I2RS interactions.
路由系统接口的体系结构[RFC7921]规定，希望检索或更改路由元素上路由状态的I2RS客户端必须通过I2RS代理的身份验证。I2RS客户端将具有它为身份验证提供的唯一标识，并且应该为通过它进行通信的应用程序提供另一个不透明标识。路由状态的编程将产生一个返回代码，其中包含指定操作的结果和结果的相关原因。所有这些都是用于理解I2RS相互作用历史的关键信息。
This document defines the framework necessary to trace those interactions between the I2RS client and I2RS agent. It goes on to describe use cases for traceability within I2RS. Based on these use cases, the document proposes an information model and reporting requirements to provide for effective recording of I2RS interactions. In this context, effective troubleshooting means being able to identify what operation was performed by a specific I2RS client via the I2RS agent, what was the result of the operation, and when that operation was performed.
本文档定义了跟踪I2RS客户端和I2RS代理之间的交互所需的框架。接着描述了I2RS中可追溯性的用例。基于这些用例，本文档提出了一个信息模型和报告要求，以便有效记录I2RS交互。在这种情况下，有效的故障排除意味着能够识别特定I2RS客户端通过I2RS代理执行的操作、操作的结果以及操作的执行时间。
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
本文件中的关键词“必须”、“不得”、“必需”、“应”、“不应”、“应”、“不应”、“建议”、“可”和“可选”应按照[RFC2119]中所述进行解释。
The architecture specification for I2RS [RFC7921] defines additional terms used in this document that are specific to the I2RS domain, such as "I2RS agent", "I2RS client", etc. The reader is expected to be familiar with the terminology and concepts defined in [RFC7921].
I2RS的体系结构规范[RFC7921]定义了本文件中使用的特定于I2RS领域的其他术语，如“I2RS代理”、“I2RS客户端”等。读者应熟悉[RFC7921]中定义的术语和概念。
As networks scale and policy becomes an increasingly important part of the control plane that creates and maintains the forwarding state, operational complexity increases as well. I2RS offers more granular and coherent control over policy and control-plane state, but it also removes or reduces the locality of the policy that has been applied to the control plane at any individual forwarding device. The ability to automate and abstract even complex policy-based controls highlights the need for an equally scalable traceability function to provide recording at event-level granularity of the evolution of the routing system compliant with the requirements of I2RS (Section 5 of [RFC7920]).
随着网络规模和策略成为创建和维护转发状态的控制平面中越来越重要的部分，操作复杂性也随之增加。I2RS提供了对策略和控制平面状态的更细粒度和一致性控制，但它也删除或减少了在任何单个转发设备上应用于控制平面的策略的局部性。自动化和抽象甚至是复杂的基于策略的控制的能力突出了对同样可扩展的跟踪功能的需求，以提供符合I2RS（RFC7920第5节）要求的路由系统演变的事件级粒度记录。
An obvious motivation for I2RS traceability is the need to troubleshoot and identify root causes of problems in these increasingly complex routing systems. For example, since I2RS is a high-throughput multi-channel, full duplex, and highly responsive interface, I2RS clients may be performing a large number of operations on I2RS agents concurrently or at nearly the same time and quite possibly in very rapid succession. As these many changes are made, the network reacts accordingly. These changes might lead to a race condition, performance issues, data loss, or disruption of services. In order to isolate the root cause of these issues, it is critical that a network operator or administrator has visibility into what changes were made via I2RS at a specific time.
I2RS可追溯性的一个明显动机是需要对这些日益复杂的路由系统中的问题进行故障排除并确定其根本原因。例如，由于I2RS是一个高吞吐量、多通道、全双工和高响应的接口，因此I2RS客户端可能同时或几乎同时在I2RS代理上执行大量操作，并且很可能以非常快的速度连续执行。随着这些变化的发生，网络会做出相应的反应。这些更改可能会导致竞争状况、性能问题、数据丢失或服务中断。为了找出这些问题的根本原因，网络运营商或管理员必须了解在特定时间通过I2R进行了哪些更改。
Some network environments have strong auditing requirements for configuration and runtime changes. Other environments have policies that require saving logging information for operational or regulatory compliance considerations. These requirements therefore demand that I2RS provides an account of changes made to network element routing systems.
某些网络环境对配置和运行时更改有很强的审核要求。其他环境具有需要保存日志记录信息以满足操作或法规遵从性考虑的策略。因此，这些要求要求I2RS提供对网元路由系统所做更改的说明。
As I2RS becomes increasingly pervasive in routing environments, a traceability model that supports controllable trace log retention using a standardized structured data format offers significant advantages, such as the ability to create common tools supporting automated testing, and facilitates the following use cases:
随着I2R在路由环境中越来越普及，支持使用标准化结构化数据格式的可控跟踪日志保留的跟踪模型提供了显著的优势，例如能够创建支持自动测试的通用工具，并有助于以下用例：
o real-time monitoring and troubleshooting of router events;
o 路由器事件的实时监控和故障排除；
o automated event correlation, trend analysis, and anomaly detection;
o 自动事件关联、趋势分析和异常检测；
o offline (manual or tools-based) analysis of router state evolution from the retained trace logs;
o 从保留的跟踪日志对路由器状态演变进行离线（手动或基于工具）分析；
o enhanced network audit, management, and forensic analysis capabilities;
o 增强网络审计、管理和法医分析能力；
o improved accounting of routing system operations; and
o 改进路由系统操作的记帐；和
o providing a standardized format for incident reporting and test logging.
o 为事件报告和测试记录提供标准化格式。
These sections describe the I2RS traceability information model and the details about each of the fields to be logged.
这些章节描述了I2RS可追溯性信息模型以及每个待记录字段的详细信息。
This section describes a framework for I2RS traceability based on the I2RS Architecture.
本节描述了基于I2RS体系结构的I2RS可追溯性框架。
The interaction between the optional network application that drives client activity, I2RS client, I2RS agent, the Routing System, and the data captured in the I2RS trace log is shown in Figure 1.
驱动客户端活动的可选网络应用程序、I2RS客户端、I2RS代理、路由系统和I2RS跟踪日志中捕获的数据之间的交互如图1所示。
+---------------+
+----------------+ |
|Application | |
|.............. | | 0 or more Applications
| Application ID | +
+----------------+
^
|
|
v
+-------------+
+-------------+ |
|I2RS Client | |
|.............| | 1 or more Clients
| Client ID | +
+-------------+
^
|
|
v
+-------------+ +-----------------------------+
|I2RS Agent |---------------->|Trace Log |
| | |.............................|
+-------------+ |Log Entry [1 .. N] |
| ^ |.............................|
| | |Event ID |
| | |Starting Timestamp |
| | |Request State |
| | |Client ID |
| | |Client Priority |
| | |Secondary ID |
Operation + | | Result Code |Client Address |
Op Data | | |Requested Operation |
| | |Applied Operation |
| | |Operation Data Present |
| | |Requested Operation Data |
| | |Applied Operation Data |
| | |Transaction ID |
| | |Result Code |
| | |Ending Timestamp |
| | |Timeout Occurred |
v | |End Of Message |
+-------------+ +-----------------------------+
|Routing |
|System |
+-------------+
+---------------+
+----------------+ |
|Application | |
|.............. | | 0 or more Applications
| Application ID | +
+----------------+
^
|
|
v
+-------------+
+-------------+ |
|I2RS Client | |
|.............| | 1 or more Clients
| Client ID | +
+-------------+
^
|
|
v
+-------------+ +-----------------------------+
|I2RS Agent |---------------->|Trace Log |
| | |.............................|
+-------------+ |Log Entry [1 .. N] |
| ^ |.............................|
| | |Event ID |
| | |Starting Timestamp |
| | |Request State |
| | |Client ID |
| | |Client Priority |
| | |Secondary ID |
Operation + | | Result Code |Client Address |
Op Data | | |Requested Operation |
| | |Applied Operation |
| | |Operation Data Present |
| | |Requested Operation Data |
| | |Applied Operation Data |
| | |Transaction ID |
| | |Result Code |
| | |Ending Timestamp |
| | |Timeout Occurred |
v | |End Of Message |
+-------------+ +-----------------------------+
|Routing |
|System |
+-------------+
Figure 1: I2RS Interaction Trace Log Capture
图1:I2RS交互跟踪日志捕获
The following fields comprise an I2RS trace log. These fields ensure that each I2RS interaction can be properly traced back to the client that made the request at a specific point in time.
以下字段构成I2RS跟踪日志。这些字段确保每个I2RS交互可以正确地追溯到在特定时间点发出请求的客户端。
The list below describes the fields captured in the I2RS trace log. This list represents a common set of fields that MUST appear in all I2RS trace logs. In addition to these fields, I2RS agent implementations MAY choose to log additional fields such as I2RS client vendor or agent statistics like free memory, performance metrics, etc.
下面的列表描述了I2RS跟踪日志中捕获的字段。此列表表示必须出现在所有I2RS跟踪日志中的一组公共字段。除了这些字段之外，I2RS代理实现还可以选择记录其他字段，如I2RS客户端供应商或代理统计数据，如可用内存、性能指标等。
Event ID: This is a unique identifier for each event in the I2RS trace log. An event can be a client authenticating with the agent, a client to agent operation, or a client disconnecting from an agent. Operation events can either be logged atomically upon completion (in which case they will have both a Starting and an Ending Timestamp field) or they can be logged at the beginning of each Request State transition. Since 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. If each state transition is logged for an operation, the same ID MUST be used for each of the Request State log entries. In this way, the life of a request can be easily followed in the I2RS trace log. Beyond the requirement that the Event ID MUST be unique for each event, the specific type and value is left up to the implementation.
事件ID：这是I2RS跟踪日志中每个事件的唯一标识符。事件可以是使用代理进行身份验证的客户端、客户端到代理的操作或客户端断开与代理的连接。操作事件可以在完成时以原子方式记录（在这种情况下，它们将具有开始和结束时间戳字段），也可以在每个请求状态转换的开始时记录。由于操作可以在同一时间从同一个客户机进行，因此具有可明确关联到特定条目的标识符非常重要。如果为操作记录了每个状态转换，则必须为每个请求状态日志条目使用相同的ID。这样，可以在I2RS跟踪日志中轻松跟踪请求的生命周期。除了要求每个事件的事件ID必须是唯一的之外，具体的类型和值由实现决定。
Starting Timestamp: The specific time at which the I2RS operation enters the specified Request State within the agent. If the log entry covers the entire duration of the request, then this will be the time that it was first received by the agent. This field MUST be present in all entries that specify the beginning of the state transition, as well as those entries that log the entire duration of the request. The time is passed in the full timestamp format [RFC3339], including the date and offset from Coordinated Universal Time (UTC). Given that many I2RS operations can occur in rapid succession, the fractional seconds element of the timestamp MUST be used to provide adequate granularity. Fractional seconds SHOULD be expressed with at least three significant digits in second.microsecond format.
起始时间戳：I2RS操作在代理内进入指定请求状态的特定时间。如果日志条目覆盖了请求的整个持续时间，那么这将是代理首次接收到它的时间。此字段必须出现在指定状态转换开始的所有条目中，以及记录整个请求持续时间的条目中。时间以完整时间戳格式[RFC3339]传递，包括日期和与协调世界时（UTC）的偏移量。鉴于许多I2RS操作可以快速连续发生，必须使用时间戳的小数秒元素来提供足够的粒度。分数秒应以秒.微秒格式至少三个有效数字表示。
Request State: The state of the given operation within the I2RS agent state machine at the specified Starting or Ending Timestamps. The I2RS agent SHOULD generate a log entry at the moment a request enters and exits a state. Upon entering a new state, the log entry will have a Starting Timestamp set to the time of entry and no Ending Timestamp. Upon exiting a state, the log entry will have an Ending Timestamp set to the time of exit and no Starting Timestamp. The progression of the request through its various states can be linked using the Event ID. The states can be one of the following values:
请求状态：I2RS代理状态机中给定操作在指定开始或结束时间戳的状态。I2RS代理应该在请求进入和退出状态时生成日志条目。在进入新状态时，日志条目将具有设置为条目时间的开始时间戳，而没有结束时间戳。退出状态时，日志条目将有一个结束时间戳设置为退出时间，而没有开始时间戳。可以使用事件ID链接请求通过其各种状态的进程。这些状态可以是以下值之一：
PENDING: The request has been received and queued for processing.
挂起：已收到请求并排队等待处理。
IN PROCESS: The request is currently being handled by the I2RS agent.
正在处理中：请求当前由I2RS代理处理。
COMPLETED: The request has reached a terminal point.
已完成：请求已到达终点。
Every state transition SHOULD be logged unless doing so will put an undue performance burden on the I2RS agent. However, an entry with the Request State set to COMPLETED MUST be logged for all operations. If the COMPLETED state is the only entry for a given request, then it MUST have both Starting and Ending Timestamps that cover the entire duration of the request from ingress to the agent until completion.
应记录每个状态转换，除非这样做会给I2RS代理带来不适当的性能负担。但是，对于所有操作，必须记录请求状态设置为“已完成”的条目。如果完成状态是给定请求的唯一条目，那么它必须具有开始和结束时间戳，覆盖从进入代理到完成的整个请求持续时间。
Client Identity: The I2RS client identity used to authenticate the client to the I2RS agent.
客户端标识：用于向I2RS代理验证客户端的I2RS客户端标识。
Client Priority: The I2RS client priority assigned by the access control model that authenticates the client. For example, this can be set by the Network Configuration Protocol (NETCONF) Access Control Model (NACM) as described in [RFC6536].
客户端优先级：由验证客户端的访问控制模型分配的I2RS客户端优先级。例如，这可以通过[RFC6536]中所述的网络配置协议（NETCONF）访问控制模型（NACM）进行设置。
Secondary Identity: This is an opaque identity that may be known to the client from a controlling network application. This is used to trace the network application driving the actions of the client. The client may not provide this identity to the agent if there is no external network application driving the client. However, this field MUST be logged even if the client does not provide a Secondary Identity. In that case, the field will be logged with an empty value.
次要标识：这是一个不透明标识，客户端可能从控制网络应用程序中知道该标识。这用于跟踪驱动客户端操作的网络应用程序。如果没有外部网络应用程序驱动客户端，客户端可能不会向代理提供此标识。但是，即使客户端未提供辅助标识，也必须记录此字段。在这种情况下，将使用空值记录该字段。
Client Address: This is the network address of the client that connected to the agent. For example, this may be an IPv4 or an IPv6 address.
客户端地址：这是连接到代理的客户端的网络地址。例如，这可能是IPv4或IPv6地址。
Requested Operation: This is the I2RS operation that was requested to be performed. For example, this may be an add route operation if a route is being inserted into a routing table. This may not be the operation that was actually applied to the agent.
请求的操作：这是请求执行的I2RS操作。例如，如果正在将路由插入路由表，则这可能是添加路由操作。这可能不是实际应用于代理的操作。
In the case of a client authenticating to the agent, the Requested Operation MUST be "CLIENT AUTHENTICATE". In the case of a client disconnecting from the agent, the Requested Operation MUST be "CLIENT DISCONNECT".
在客户端向代理进行身份验证的情况下，请求的操作必须是“客户端身份验证”。在客户端与代理断开连接的情况下，请求的操作必须是“客户端断开连接”。
Applied Operation: This is the I2RS operation that was actually performed. This can differ from the Requested Operation in cases where the agent cannot satisfy the Requested Operation. This field may not be logged unless the Request State is COMPLETED.
应用操作：这是实际执行的I2RS操作。当代理无法满足请求的操作时，这可能与请求的操作不同。除非请求状态已完成，否则无法记录此字段。
Operation Data Present: This is a Boolean field that indicates whether or not additional per-Operation Data is present.
存在操作数据：这是一个布尔字段，指示是否存在额外的每操作数据。
Requested 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. If Operation Data is provided, then the Operation Data Present field MUST be set to TRUE. Some operations may not provide operation data. In those cases, the Operation Data Present field MUST be set to FALSE, and this field MUST be empty. This may not represent the data that was used for the operation that was actually applied on the agent.
请求的操作数据：此字段包含传递给代理以完成所需操作的数据。例如，如果操作是路由添加操作，则操作数据将包括要插入的路由前缀、前缀长度和下一跳信息以及将添加路由的特定路由表。如果提供了操作数据，则必须将“操作数据显示”字段设置为TRUE。某些操作可能不提供操作数据。在这些情况下，“操作数据显示”字段必须设置为FALSE，并且该字段必须为空。这可能不代表实际应用于代理的操作所使用的数据。
When a client authenticates to the agent, the Requested Operation Data MUST contain the client priority. Other attributes such as credentials used for authentication MAY be logged.
当客户端向代理进行身份验证时，请求的操作数据必须包含客户端优先级。可能会记录其他属性，例如用于身份验证的凭据。
Applied Operation Data: This field comprises the data that was actually applied as part of the Applied Operation. If the agent cannot satisfy the Requested Operation with the Requested Operation Data, then this field can differ from the Requested Operation Data. This field will be empty unless the Requested Operation Data was specified. This field may not be logged unless the Request State is COMPLETED.
应用的操作数据：此字段包含作为应用的操作的一部分实际应用的数据。如果代理无法使用请求的操作数据满足请求的操作，则此字段可能与请求的操作数据不同。除非指定了请求的操作数据，否则此字段将为空。除非请求状态已完成，否则无法记录此字段。
Transaction ID: The Transaction Identity represents that this particular operation is part of a long-running I2RS transaction that can consist of multiple, related I2RS operations. Using this value, one can relate multiple log entries together as they are part of a single, overall I2RS operation. This is an optional field that may not be logged unless the event is part of a long-running transaction.
事务ID：事务标识表示此特定操作是长时间运行的I2RS事务的一部分，该事务可以由多个相关的I2RS操作组成。使用此值，可以将多个日志条目关联在一起，因为它们是单个整体I2RS操作的一部分。这是一个可选字段，除非事件是长期运行事务的一部分，否则可能不会记录该字段。
Result Code: This field holds the result of the operation once the Request State is COMPLETED. In the case of Routing Information Base (RIB) operations, this MUST be the return code as specified in Section 4 of [RIBINFO]. 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.
结果代码：该字段保存请求状态完成后的操作结果。对于路由信息库（RIB）操作，必须是[RIBINFO]第4节中规定的返回代码。在超时的情况下，操作可能不会以结果代码完成。如果操作未能完成，它仍必须使用适当的结果代码记录尝试的操作。
Timeout Occurred: This is a Boolean field that indicates whether or not a timeout occurred in the operation. When this is true, the value of the Ending Timestamp MUST be set to the time the agent recorded for the timeout occurrence. This field may not be logged unless the Request State is COMPLETED.
超时发生：这是一个布尔字段，指示操作中是否发生超时。如果为true，则结束时间戳的值必须设置为代理为超时事件记录的时间。除非请求状态已完成，否则无法记录此字段。
Ending Timestamp: The specific time at which the I2RS operation exits the specified Request State within the I2RS agent. If the log entry covers the entire duration of the request, then this will be the time that the request reached a terminal point within the agent. This field MUST be present in all entries that specify the ending of the state transition, as well as those entries that log the entire duration of the request. The time is passed in the full timestamp format [RFC3339], including the date and offset from Coordinated Universal Time (UTC). See the description for Starting Timestamp above for the proper format of the Ending Timestamp.
结束时间戳：I2RS操作在I2RS代理中退出指定请求状态的特定时间。如果日志条目覆盖请求的整个持续时间，则这将是请求到达代理内的终点的时间。此字段必须出现在所有指定状态转换结束的条目中，以及记录整个请求持续时间的条目中。时间以完整时间戳格式[RFC3339]传递，包括日期和与协调世界时（UTC）的偏移量。有关结束时间戳的正确格式，请参见上面的开始时间戳说明。
End Of Message: Each log entry SHOULD have an appropriate End Of Message (EOM) indicator. See Section 5.3 below for more details.
消息结束：每个日志条目应具有适当的消息结束（EOM）指示器。详见下文第5.3节。
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-formatted log (similar to a syslog) the EOM marker may be a newline character. In an XML-formatted log, the schema would provide for element tags that denote the beginning and end of records. In a JSON-formatted log, the syntax would provide record separation (likely by comma-separated array elements).
由于I2RS跟踪日志字段中的可变性，实现者必须使用适合格式的消息结束（EOM）指示器来表示特定记录的结束。也就是说，无论采用何种格式，I2RS跟踪日志都必须提供一种独特的方式来区分一条记录的结束和另一条记录的开始。例如，在线性格式日志（类似于系统日志）中，EOM标记可以是换行符。在XML格式的日志中，模式将提供表示记录开始和结束的元素标记。在JSON格式的日志中，语法将提供记录分隔（可能通过逗号分隔的数组元素）。
This section shows a sample of what the fields and values could look like.
本节展示了字段和值的示例。
Event ID: 1
Starting Timestamp: 2013-09-03T12:00:01.21+00:00
Request State: COMPLETED
Client ID: 5CEF1870-0326-11E2-A21F-0800200C9A66
Client Priority: 100
Secondary ID: com.example.RoutingApp
Client Address: 2001:db8:c0c0::2
Requested Operation: ROUTE_ADD
Applied Operation: ROUTE_ADD
Operation Data Present: TRUE
Requested Operation Data: PREFIX 2001:db8:feed:: PREFIX-LEN 64
NEXT-HOP 2001:db8:cafe::1
Applied Operation Data: PREFIX 2001:db8:feed:: PREFIX-LEN 64
NEXT-HOP 2001:db8:cafe::1
Transaction ID: 2763461
Result Code: SUCCESS(0)
Timeout Occurred: FALSE
Ending Timestamp: 2013-09-03T12:00:01.23+00:00
Event ID: 1
Starting Timestamp: 2013-09-03T12:00:01.21+00:00
Request State: COMPLETED
Client ID: 5CEF1870-0326-11E2-A21F-0800200C9A66
Client Priority: 100
Secondary ID: com.example.RoutingApp
Client Address: 2001:db8:c0c0::2
Requested Operation: ROUTE_ADD
Applied Operation: ROUTE_ADD
Operation Data Present: TRUE
Requested Operation Data: PREFIX 2001:db8:feed:: PREFIX-LEN 64
NEXT-HOP 2001:db8:cafe::1
Applied Operation Data: PREFIX 2001:db8:feed:: PREFIX-LEN 64
NEXT-HOP 2001:db8:cafe::1
Transaction ID: 2763461
Result Code: SUCCESS(0)
Timeout Occurred: FALSE
Ending Timestamp: 2013-09-03T12:00:01.23+00:00
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.
有关临时日志存储、滚动、检索和访问I2RS跟踪日志的具体操作程序不在本文档范围内。采用I2RS跟踪日志记录的组织负责建立适合其特定需求和操作环境的适当操作程序。在本节中，我们仅提供独立于实现的基本和通用操作指南。
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 operations that can be retrieved to troubleshoot I2RS-related impact to the network. Changes that occur to the network element's local configuration outside of the I2RS protocol that preempt I2RS state will only be logged if the network element notifies the I2RS agent.
I2RS代理与路由元素的路由和信令功能交互。由于I2RS代理负责在关联的网络设备上实际进行路由更改，因此它创建并维护一个操作日志，可以检索该日志以排除与I2RS相关的对网络的影响。只有当网元通知I2RS代理时，才会记录在I2RS协议之外的网元本地配置发生的更改，这些更改会抢占I2RS状态。
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 operations 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. client requests may not always be processed synchronously or within a bounded time period. Consequently, to ensure that trace log fields, such as "Operation" and "Result Code", are part of the same trace log record, buffering of the trace log entries may be required. This buffering may result in additional resource load on the agent and the network element.
跟踪信息可以临时存储在内存缓冲区中，也可以作为代理的本地文件。应注意给定代理上预期的I2RS操作数，以便使用适当的存储介质，并最大限度地提高日志的有效性，同时不影响代理的性能和运行状况。客户端请求可能并不总是同步处理或在限定的时间段内处理。因此，为了确保跟踪日志字段（如“操作”和“结果代码”）是同一跟踪日志记录的一部分，可能需要缓冲跟踪日志条目。此缓冲可能会导致代理和网元上的额外资源负载。
Section 7.3 discusses rotating the trace log in order to preserve the operation history without exhausting agent or network device resources. It is perfectly acceptable, therefore, to use both an in-memory buffer for recent operations while rotating or archiving older operations to a local file.
第7.3节讨论了旋转跟踪日志，以便在不耗尽代理或网络设备资源的情况下保存操作历史。因此，在将较旧的操作旋转或归档到本地文件的同时，为最近的操作使用内存缓冲区是完全可以接受的。
It is outside the scope of this document to specify the implementation details (i.e., size, throughput, data protection, etc.) for the physical storage of the I2RS log file. In terms of data retention, attention should be paid to the length of time that the I2RS trace log data is kept when that data contains security- or privacy-sensitive attributes. The longer this data is retained, the higher the impact if it were to be leaked. It is also possible that legislation may impose some additional requirements on the minimum and/or maximum durations for which some kinds of data may be retained.
为I2RS日志文件的物理存储指定实施细节（即大小、吞吐量、数据保护等）超出了本文件的范围。在数据保留方面，当I2RS跟踪日志数据包含安全或隐私敏感属性时，应注意该数据保留的时间长度。这些数据保留的时间越长，如果泄露，影响就越大。立法也可能对某些类型的数据可能被保留的最短和/或最长期限提出一些额外要求。
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 are outside the scope of this document. However, it should be possible to do a file rotation based on either the 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.
为了防止I2RS代理或其关联网络设备上的资源耗尽，建议I2RS代理执行跟踪日志轮换。关于如何实现这一点的细节留待实施，不在本文件的范围之内。但是，应该可以根据当前跟踪日志的时间或大小进行文件旋转。如果支持文件滚动，则应支持多个归档日志文件，以便最大限度地利用跟踪日志的故障排除和记帐优势。
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 a vendor-agnostic and consistent interface to collect I2RS trace data. Correspondingly, retrieval of the data should also be made vendor-agnostic.
实现者可以自由地提供自己的专有接口，并开发自定义工具来检索和显示I2RS跟踪日志。这些可能包括将I2RS跟踪日志显示为命令行界面（CLI）输出。然而，定义此信息模型的一个关键目的是建立一个与供应商无关且一致的接口来收集I2RS跟踪数据。相应地，数据的检索也应与供应商无关。
Despite the fact that export of I2RS trace log information could be an invaluable diagnostic tool for off-box analysis, exporting this information MUST NOT interfere with the ability of the agent to process new incoming operations.
尽管I2RS跟踪日志信息的导出可能是一个非常宝贵的诊断工具，可用于机箱外分析，但导出此信息不得干扰代理处理新传入操作的能力。
The following three sections describe potential ways the trace log can be accessed. The use of I2RS pub/sub for accessing trace log data is mandatory-to-implement, while others are optional.
以下三节描述了访问跟踪日志的可能方式。使用I2RS发布/订阅访问跟踪日志数据是强制实现的，而其他是可选的。
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. Syslog MAY be employed as a means of retrieving or disseminating the I2RS trace log contents.
syslog协议[RFC5424]是从主机向收集器发送事件通知消息的标准方式。然而，该协议没有定义任何用于存储消息的标准格式，因此I2RS跟踪的实现者将被留给定义他们自己的格式。因此，尽管syslog消息中包含的数据将遵循此信息模型，并且可能由人工操作员使用，但机器无法轻松解析它。Syslog可以用作检索或传播I2RS跟踪日志内容的手段。
If syslog is used for trace log retrieval, then existing logging infrastructure and capabilities of syslog [RFC5424] should be leveraged without the need to define or extend existing formats. That is, the various fields described in Section 5.2 SHOULD be modeled and encoded as Structured Data Elements (referred to as "SD-ELEMENT"), as described in Section 6.3.1 of [RFC5424].
如果syslog用于跟踪日志检索，则应利用syslog[RFC5424]的现有日志基础设施和功能，而无需定义或扩展现有格式。也就是说，第5.2节中描述的各种字段应建模并编码为结构化数据元素（称为“SD元素”），如[RFC5424]第6.3.1节所述。
Section 7.7 of the I2RS architecture [RFC7921] 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.
I2RS体系结构[RFC7921]第7.7节定义了信息收集机制。收集的信息包括从网元获取大量数据的快照。I2RS的目的是以实现者不可知的方式提供这些数据。因此，I2RS跟踪日志应通过I2RS信息收集机制作为单个快照或通过订阅流提供。
Section 7.6 of the I2RS architecture [RFC7921] goes on to describe notification mechanisms for a feed of changes happening within the I2RS layer. Specifically, the requirements for a publish-subscribe system for I2RS are defined in [RFC7923]. I2RS agents MUST support publishing I2RS trace log information to that feed as described in [RFC7923]. 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. The full range of potential activities is virtually limitless and the details of how they are performed are outside the scope of this document, however.
I2RS体系结构[RFC7921]的第7.6节继续描述了在I2RS层内发生的变更反馈的通知机制。具体而言，[RFC7923]中定义了i2R发布-订阅系统的要求。I2RS代理必须支持将I2RS跟踪日志信息发布到该提要，如[RFC7923]中所述。然后，订阅者将收到跟踪日志格式的I2RS交互的实时流，并可以灵活地选择使用日志消息执行许多操作。例如，订阅者可以将消息记录到数据存储、聚合和总结来自单个客户机的交互等。但是，潜在活动的全部范围实际上是无限的，如何执行这些活动的细节不在本文档的范围内。
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.
I2RS跟踪日志与任何日志文件一样，揭示了生成它的实体的状态以及包含它的系统的标识信息元素和详细交互。本文档中描述的信息模型本身并不引入任何安全问题，但它定义了组成I2RS日志文件的一组属性。这些属性可能包含敏感信息，因此应遵守使用I2RS日志文件的组织的安全、隐私和权限策略。
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.
指定如何保护存储的日志文件不在本文档的范围内，但需要采取适当的预防措施和安全最佳做法，如磁盘加密、适当限制的文件/目录权限、日志实体的适当强化和物理安全、相互认证、传输加密、，传输日志文件时的通道机密性和通道完整性。此外，操作员应充分匿名化或模糊化日志文件中包含的潜在敏感信息，以确保其隐私。
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <http://www.rfc-editor.org/info/rfc2119>.
[RFC2119]Bradner，S.，“RFC中用于表示需求水平的关键词”，BCP 14，RFC 2119，DOI 10.17487/RFC2119，1997年3月<http://www.rfc-editor.org/info/rfc2119>.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, <http://www.rfc-editor.org/info/rfc3339>.
[RFC3339]Klyne，G.和C.Newman，“互联网上的日期和时间：时间戳”，RFC 3339，DOI 10.17487/RFC3339，2002年7月<http://www.rfc-editor.org/info/rfc3339>.
[RFC5424] Gerhards, R., "The Syslog Protocol", RFC 5424, DOI 10.17487/RFC5424, March 2009, <http://www.rfc-editor.org/info/rfc5424>.
[RFC5424]Gerhards，R.，“系统日志协议”，RFC 5424DOI 10.17487/RFC54242009年3月<http://www.rfc-editor.org/info/rfc5424>.
[RFC7921] Atlas, A., Halpern, J., Hares, S., Ward, D., and T. Nadeau, "An Architecture for the Interface to the Routing System", RFC 7921, DOI 10.17487/RFC7921, June 2016, <http://www.rfc-editor.org/info/rfc7921>.
[RFC7921]Atlas，A.，Halpern，J.，Hares，S.，Ward，D.，和T.Nadeau，“路由系统接口架构”，RFC 7921，DOI 10.17487/RFC7921，2016年6月<http://www.rfc-editor.org/info/rfc7921>.
[RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements for Subscription to YANG Datastores", RFC 7923, DOI 10.17487/RFC7923, June 2016.
[RFC7923]Voit，E.，Clemm，A.和A.Gonzalez Prieto，“YANG数据存储订阅要求”，RFC 7923，DOI 10.17487/RFC79232016年6月。
[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration Protocol (NETCONF) Access Control Model", RFC 6536, DOI 10.17487/RFC6536, March 2012, <http://www.rfc-editor.org/info/rfc6536>.
[RFC6536]Bierman，A.和M.Bjorklund，“网络配置协议（NETCONF）访问控制模型”，RFC 6536，DOI 10.17487/RFC6536，2012年3月<http://www.rfc-editor.org/info/rfc6536>.
[RFC7920] Atlas, A., Ed., Nadeau, T., Ed., and D. Ward, "Problem Statement for the Interface to the Routing System", RFC 7923, DOI 10.17487/RFC7923, June 2016, <http://www.rfc-editor.org/info/rfc7920>.
[RFC7920]Atlas，A.，Ed.，Nadeau，T.，Ed.，和D.Ward，“路由系统接口问题声明”，RFC 7923，DOI 10.17487/RFC79232016年6月<http://www.rfc-editor.org/info/rfc7920>.
[RIBINFO] Bahadur, N., Ed., Kini, S., Ed., and J. Medved, "Routing Information Base Info Model", Work in Progress, draft-ietf-i2rs-rib-info-model-08, October 2015.
[RIBINFO]Bahadur，N.，Ed.，Kini，S.，Ed.，和J.Medved，“路由信息基础信息模型”，正在进行的工作，草案-ietf-i2rs-rib-Info-Model-082015年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, Dean Bogdanovich, Ignas Bagdonas, Nobo Akiya, Kwang-koog Lee, Sue Hares, Mach Chen, Alex Clemm, Stephen Farrell, Benoit Claise, Les Ginsberg, Suresh Krishnan, and Elwyn Davies for their reviews, contributed text, and suggested improvements to this document.
作者要感谢Alia Atlas对这项工作的初步反馈和全面支持。此外，作者感谢Alvaro Retana、Russ White、Matt Birkner、Jeff Haas、Joel Halpern、Dean Bogdanovich、Ignas Bagdonas、Nobo Akiya、Kwang koog Lee、Sue Hares、Mach Chen、Alex Clemm、Stephen Farrell、Benoit Claise、Les Ginsberg、Suresh Krishnan和Elwyn Davies的评论，贡献了文本，并对本文件提出了改进建议。
Authors' Addresses
作者地址
Joe Clarke Cisco Systems, Inc. 7200-12 Kit Creek Road Research Triangle Park, NC 27709 United States
Joe Clarke Cisco Systems，Inc.美国北卡罗来纳州Kit Creek Road研究三角公园7200-12号，邮编：27709
Phone: +1-919-392-2867
Email: jclarke@cisco.com
Phone: +1-919-392-2867
Email: jclarke@cisco.com
Gonzalo Salgueiro Cisco Systems, Inc. 7200-12 Kit Creek Road Research Triangle Park, NC 27709 United States
Gonzalo Salgueiro Cisco Systems，Inc.美国北卡罗来纳州Kit Creek Road研究三角公园7200-12号，邮编：27709
Email: gsalguei@cisco.com
Email: gsalguei@cisco.com
Carlos Pignataro Cisco Systems, Inc. 7200-11 Kit Creek Road Research Triangle Park, NC 27709 United States
Carlos Pignataro Cisco Systems，Inc.美国北卡罗来纳州Kit Creek Road研究三角公园7200-11号，邮编：27709
Email: cpignata@cisco.com
Email: cpignata@cisco.com