ETS Output 包概述
注意: 本包最初是为访问 Flow Analysis 输出表而提供的,但也可用于其他输出表,包括离散事件仿真与 loads-to-flows。
Flow Analysis 能够生成大量详细信息。这些信息可能对众多 Flow Analysis 客户端(design actions、协议工具、可视化、导出等)都有用处。其中部分信息可以直接使用 Odan_Flan API 从内存中访问,另一部分信息只能从输出表报告中获得。Oma_Ot 包提供了读取输出表(.ot)文件的函数。在某些情况下,直接使用 Oma_Ot 包(“OMA Output Table Package“)采集数据是最佳方式。直接获取数据时存在一些局限:
- 客户端代码与 Flow Analysis 输出表的格式和结构直接绑定。任何变化都会破坏客户端代码。
- 输出表提供逐行的顺序访问。Oma_Ot 包不提供面向对象的访问。
- 表中的某些值是多重键的(例如节点与接口名)。Oma_Ot 包不直接支持基于键(而非简单的行、列值)查找值。
ETS Output 包是构建在 OMA OT 之上的一层抽象,用于高效地解决这些局限。本包旨在以遵循 Ets_Obj_Attr_Get() 属性访问约定的方式访问已注册的输出值。
ETS Output 包有三组函数:
如果数据的位置或格式发生变化,只需更改输出值的注册,客户端代码可以保持不变。
ETS Output 包仅支持访问 OT 文件中的数据。每个值必须位于 OT 文件的全局表(而非对象表)中。全局表中的行必须具有一个热链接(hot-linked)单元格,可用于指示该行对应的对象(或者它必须继承前一行的值)。
本包使用以下数据结构:
- Output Context(
EtsT_Output_Context)——针对特定网络模型的特定输出来源,持有并缓存访问输出信息的状态 - Output Registered Value(
EtsT_Output_Reg_Value)——定义一个已注册的输出值。每个已注册的输出值与一个从输出表中获取该值的函数相关联。ETS Output 包定义了一些常用函数,因此值发布者通常无需自己编写函数。 - Output Value Cache(
EtsT_Output_Value_Cache)——持有关于特定已注册值的信息,使后续调用更高效。每个输出上下文为每个已被访问的注册值持有值缓存。
图 15:输出上下文结构

客户端代码用法
要在代码中访问输出值数据,必须包含以下一行。
#include "ets_api_output.h"
在使用本包的函数之前,要么先调用分析(Flow Analysis 或离散事件仿真),要么确保其已经运行且结果已保存到输出表。(可能需要启用某些报告选项,以生成包含所需信息的报告。)然后:
- 使用 Ets_Output_Context_Create() 初始化输出上下文。
- 使用 Ets_Output_Obj_Value_Get() 访问所需的输出值。
- 使用完毕后,使用 Ets_Output_Context_Destroy() 销毁输出上下文。
注意: 如果分析最近被重新运行过,输出上下文必须销毁并重新创建。
模型开发者用法
要发布一个输出值,首先使用 Ets_Output_Table_Value_Register()(或基于来源的相应形式)注册该输出值。值可以在访问该值之前的任何时间注册(不必在程序初始化时或 Flow Analysis 运行之后进行)。
根据值的复杂程度,你可能需要编写一个回调函数。在许多情况下,你可以使用 ets_output_standard_obj_value_get() 函数。Ets_Output_Value_Cache_ 函数可用于实现高效的自定义查找函数。
示例
单个标量值
最简单的情况是获取与单个对象对应的单个标量输出值。例如,一个 IP 流量流有一个流量速率。原始值存储在 demand 上随时间变化的 Traffic (bits/second) profile 属性中。运行 Flow Analysis 时,每个 demand 的值基于所选的 Flow Analysis Reports 报告间隔、间隔大小以及 Flow Analysis 流量缩放因子。Flow Analysis 的客户端通常希望基于这些相同设置使用单个值。最好的方法是从 Flow Analysis 输出数据中获取该信息。该信息输出在 Performance.Demand Performance 报告中。关注的值位于 Average Bits Per Sec 列。
图 16:Demand Performance 报告

要获取流量速率,按以下步骤进行:
-
注册输出值。
要注册输出值,需要对象列和值列的列标签(column tag)。将报告导出为 XML 并查看列信息。
<?xml version="1.0" encoding="ISO-8859-1" ?> - <table name="Performance.Demand Performance" file="Greenfield_Design-chordal_ring_design_ref-FLAN"> <column tag="DemandName" type="string shared" title="Demand Name" format="%s" /> <column tag="AddressFamily" type="string" title="Address Family" format="%s" /> <column tag="FailedStatus" type="string shared" title="Status" format="%s" /> <column tag="HopCount" type="string" title="Hop Count" format="%s" /> <column tag="AvgBitsPerSec" type="string" title="Average Bits Per Sec" format="%s" /> <column tag="Delay" type="string" title="Average Delay (msec)" format="%s" /> <column tag="Jitter" type="string" title="End to End Jitter (msec)" format="%s" /> <column tag="PacketLoss" type="string" title="Maximum Packet Loss (%)" format="%s" /> <column tag="Volume" type="string" title="Volume" format="%s" /> <column tag="DefinitionDetail" type="string" title="Definition Detail" format="%s" /> <column tag="RoutingDetail" type="string" title="Routing Detail" format="%s" />该报告中的每一行对应一个 IP 流。每个流只用一行表示。这是最简单的情况(一对一映射)。该 XML 显示标识对象的列的列标签是 DemandName,目标值的列标签是 AvgBitsPerSec。注意,标识对象的列必须是 HotLink 列(在 Viewer 中以红色显示的列)。输出值通过以下函数调用注册:
Ets_Output_Table_Value_Register ("Demand Avg Bits Per Sec", EtsC_Output_Source_FLAN, EtsC_Obj_Type_Flow, "Performance.Demand Performance", "AvgBitsPerSec", "DemandName", ets_output_standard_obj_value_get);各参数说明见下表:
表 169:Ets_Output_Table_Value_Register() 参数
参数 类型 定义 value_namechar *输出值的名称,即 Ets_Output_Obj_Value_Get() 的调用者所知的名称。该值将以 Demand Avg Bits Per Sec 发布。对于给定的来源、对象类型二元组,该值应当唯一。 result_sourceEtsT_Output_Source生成输出的来源(分析引擎)。通常引擎是 Flow Analysis(EtsC_Output_Source_FLAN)。 obj_typeEtsT_Obj_Type该输出值适用的对象类型或元类型。像 EtsC_Obj_Mtype_Link 这样的元类型适用于所有派生类型,如 EtsC_Obj_Type_Lkdup。本例中对象类型是 EtsC_Obj_Type_Flow。 table_namechar *包含该输出值的输出表(OT)的名称。该值位于 Performance.Demand Performance 表中。 column_tagchar *包含目标输出值的列的列标签值。它可能与显示的列标题不同。标签可从报告的 .xml 文件中获得。本例的列标签是 AvgBitsPerSec。 hot_link_column_tagchar *包含热链接对象的列的列标签值,该对象用于定义该行对应的对象。通常这是第一列,包含对象的名称。本例的热链接列标签值是 DemandName。 value_func_ptrEtsT_Output_Reg_Function被派发用于获取值的函数。Ets Output 包提供一些预定义的值函数。本例使用其中最简单的一个:ets_output_standard_obj_value_get()。该函数以与表中显示格式相同的形式输出 OT 中的原始单元格值。.xml 文件定义每一列的类型。即使显示的值是数值,列类型通常也是 string。 -
创建输出上下文。
EtsT_Model_Handle model_hndl = Ets_Model_Current_Get (EtsC_Model_Nt); EtsT_Output_Context * c_ptr = Ets_Output_Context_Create (model_hndl, EtsC_Output_Source_FLAN); -
获取目标对象的输出值。
EtsT_Obj_Handle flow_hndl; char * lsp_bw_ptr; if (Ets_Output_Obj_Value_Get (c_ptr, flow_hndl, "Demand Avg Bits Per Sec", &lsp_bw_str) != EtsC_Output_Status_SUCCESS) FRET (PrgC_Compcode_Failure); -
将值转换为所需格式。
输出值是字符串值。要将该值用作以 bps 为单位的流量值,必须将格式化的字符串转换为 double。字符串的内存是在 Ets_Output_Obj_Value_Get() 函数调用中分配的,因此不再需要时也需要释放。
double flow_bps; prg_string_to_double (lsp_bw_str, &flow_bps); prg_string_free (lsp_bw_str); -
销毁输出上下文。
完成从输出来源访问数据后,销毁输出上下文。
Ets_Output_Context_Destroy (c_ptr);如果输出上下文已过期(例如重新运行了 Flow Analysis),应销毁并重新创建输出上下文以刷新缓存。
列表值
在某些情况下,输出值可能对应显示在同一列、连续多行的多个单元格中的一组值。LSP 的路由就是这种输出表格式的一个例子。
图 17:LSP Routes 报告

Link 列中的对象列表可以用与前面标量值示例类似的方式获取。
-
注册输出值。
输出值使用 Ets_Output_Table_Value_Register_With_Type() 注册。符号常量
EtsC_Output_Value_Type_Hot_Link_Object_Name使该值指向目标单元格中的热链接对象,而不是单元格的显示值。值函数 ets_output_standard_obj_value_list_get() 用于将值作为EtsT_Obj_List输出。Ets_Output_Table_Value_Register_With_Type ("LSP Route", EtsC_Output_Source_FLAN, EtsC_Obj_Type_Path, "Performance.LSP Routes", "Link", "LspName", EtsC_Output_Value_Type_Hot_Link_Object_Name, ets_output_standard_obj_value_list_get); -
获取输出值。
创建输出上下文与标量值的情况相同。获取输出值也非常类似。
EtsT_Obj_List *route_lptr = PRGC_NIL; // Get the ordered list of link objects in the LSP path in // the output variable route_lptr. if (Ets_Output_Obj_Value_Get (c_ptr, lsp_hndl, "LSP Route", route_lptr) != EtsC_Output_Status_SUCCESS) FRET (route_lptr); Ets_Obj_List_Destroy (route_lptr);
多列键
在前两个示例中,输出值的键只是一个对象,且输出表中存在对应该对象的一个条目。在某些情况下,需要多个列(二元组、三元组等)来标识表中的目标值。例如,考虑获取某个队列的利用率。队列不是一级对象,它由节点、接口和流量类别标识。节点是用作主键的一级对象,接口和流量类别补全用作 DiffServ-Interface Queue Usage 报告中目标输出值键的三元组。
图 18:LSP Routes 报告

这种输出值称为多列值。该值使用 Ets_Output_Table_Multi_Col_Value_Register_With_Type() 注册。主对象作为 hot_link_column_tag 传入,其他列的标签以列表形式传入。
-
注册多列值。
multi_col_lptr = prg_list_create (); prg_list_insert (multi_col_lptr,prg_string_copy ("Interface"), PRGC_LISTPOS_TAIL); prg_list_insert (multi_col_lptr, prg_string_copy ("Traffic Class"), PRGC_LISTPOS_TAIL); Ets_Output_Table_Multi_Col_Value_Register_With_Type "Queue Interface Utilization", EtsC_Output_Source_FLAN, EtsC_Obj_Mtype_Node, "Performance.Diffserv-Interface Queue Usage", "Interface Utilization By Queue (%)", "Node", EtsC_Output_Value_Type_Cell_Value, multi_col_lptr, ets_output_standard_obj_multi_col_value_get); prg_list_destroy (multi_col_lptr, 1); -
基于多列键获取值。
获取该值的方式是传入输出值名称以及限定列的值。例如,要获取接口 IF10 的 best-effort 队列利用率,
output_value_name为:Queue Interface Utilization [IF10] [best-effort]
char attr_name [1024]; char * util_str = PRGC_NIL; double util; sprintf (attr_name, "Queue Interface Utilization [%s] [%s]", ifc_name, queue_name); if (Ets_Output_Obj_Value_Get (c_ptr, node_hndl, attr_name, &util_str) != EtsC_Output_Status_SUCCESS) util = 0.0; else { // Convert string to double prg_string_to_double (util_str, &util); prg_string_free (util_str); }在大多数情况下,给定的主对象在输出表中只给出一次(如队列利用率的情况)。对应于给定主对象的所有行在一个连续块中给出。通常,如果在对象的第一个块中找不到目标值,就认为它不在表中。在某些情况下,表中可能有多行对应同一主对象且在表中不连续。一个例子是链路利用率表,链路的每个方向各占一行。如果表按利用率排序,两个方向可能在表中不相邻。为了支持这种行为,需要通过调用 Ets_Output_Reg_Value_Multiple_Discontiguous_Rows_Support() 设置一个选项。这只适用于多列输出值。
标准输出值
某些输出值注册在文件 util/flan_register_values.ets.c 中并包含在 flan.ets.dll 中。该库在加载 Flow Analysis 时总是被加载,因此这些值对所有 Flow Analysis 客户端都可用。
表 170:标准 Flow Analysis 输出值
| 输出值名称 | 主对象 | 附加列 | 值类型 | 定义 |
|---|---|---|---|---|
| Demand Avg Bits Per Sec | Flow | 字符串(bps) | IP demand 在报告周期内的平均比特率 | |
| Mean Utilization | Link | 字符串(利用率,百分比) | 链路的平均利用率值(两个方向中的较高者) | |
| Mean Utilization | Path | 字符串(利用率,百分比) | LSP 的平均利用率值(LSP 预留带宽的百分比) | |
| Mean Flow Bandwidth | Link | 字符串(流量,Mbps) | 经由链路的流量 demand 的平均流量(Mbps,两个方向中的较高者)。不包括间接使用该链路的 demand(经由虚电路承载等)或背景负载。 | |
| Mean Flow Bandwidth | Path | 字符串(流量,Mbps) | 经由 LSP 的流量 demand 的平均流量(Mbps) | |
| Mean Consumed Bandwidth | Link | 字符串(消耗带宽,Mbps) | 链路的消耗带宽(Mbps,两个方向中的较高者)。消耗带宽包括背景负载和流量 demand,包括直接和间接使用链路的流量。 | |
| Mean Consumed Bandwidth | Path | 字符串(消耗带宽,Mbps) | 链路的消耗带宽(Mbps)。消耗带宽包括背景负载和流量 demand。 | |
| Failed LSP Route Type | Path | 字符串(路由类型,如 CSPF、Explicit Route、Operational) | 获取路由失败的 LSP 的尝试路由类型 | |
| Throughput Forward | Link | 字符串(Mbps) | 链路前向方向的吞吐量(Mbps) | |
| Throughput Return | Link | 字符串(Mbps) | 链路返回方向的吞吐量(Mbps) | |
| LSP Route Origin | Path | 字符串(路由来源值,如 Explicit Route、CSPF、Operational) | 获取成功路由的 LSP 的路由来源 | |
| LSP Route | Path | EtsT_Obj_List(路径中的链路列表) |
输出成功路由的 LSP 路由中的链路列表 | |
| Queue Interface Utilization | Node | [Interface Name][Traffic Class Name] | 字符串(该队列对该接口的利用率) | 该队列对该接口的利用率(占接口总带宽的百分比) |
| Traffic Engineering Residual Bandwidth | Node | [Interface Name][Class Type] | 字符串(Mbps) | 接口上针对给定 MPLS DS-TE 类别类型的剩余可预留带宽量。 |
| Failed LSP Bottleneck Links | Path | EtsT_Obj_List(链路对象列表) |
路由失败的 LSP 的候选路径中的瓶颈链路。 | |
| Failed LSP Candidate Routes | Path | PrgT_List(字符串值列表) |
列表中的每个 LSP 候选路由都是一个包含节点、链路、节点名称的字符串,这些名称为层次化名称 | |
| Interface Scheduler Bandwidth | Node | [Interface] | 字符串(Mbps) | 该接口调度器的总带宽(Mbps) |