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 或离散事件仿真),要么确保其已经运行且结果已保存到输出表。(可能需要启用某些报告选项,以生成包含所需信息的报告。)然后:

  1. 使用 Ets_Output_Context_Create() 初始化输出上下文。
  2. 使用 Ets_Output_Obj_Value_Get() 访问所需的输出值。
  3. 使用完毕后,使用 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 报告

Demand Performance 报告

要获取流量速率,按以下步骤进行:

  1. 注册输出值。

    要注册输出值,需要对象列和值列的列标签(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_name char * 输出值的名称,即 Ets_Output_Obj_Value_Get() 的调用者所知的名称。该值将以 Demand Avg Bits Per Sec 发布。对于给定的来源、对象类型二元组,该值应当唯一。
    result_source EtsT_Output_Source 生成输出的来源(分析引擎)。通常引擎是 Flow Analysis(EtsC_Output_Source_FLAN)。
    obj_type EtsT_Obj_Type 该输出值适用的对象类型或元类型。像 EtsC_Obj_Mtype_Link 这样的元类型适用于所有派生类型,如 EtsC_Obj_Type_Lkdup。本例中对象类型是 EtsC_Obj_Type_Flow。
    table_name char * 包含该输出值的输出表(OT)的名称。该值位于 Performance.Demand Performance 表中。
    column_tag char * 包含目标输出值的列的列标签值。它可能与显示的列标题不同。标签可从报告的 .xml 文件中获得。本例的列标签是 AvgBitsPerSec。
    hot_link_column_tag char * 包含热链接对象的列的列标签值,该对象用于定义该行对应的对象。通常这是第一列,包含对象的名称。本例的热链接列标签值是 DemandName。
    value_func_ptr EtsT_Output_Reg_Function 被派发用于获取值的函数。Ets Output 包提供一些预定义的值函数。本例使用其中最简单的一个:ets_output_standard_obj_value_get()。该函数以与表中显示格式相同的形式输出 OT 中的原始单元格值。.xml 文件定义每一列的类型。即使显示的值是数值,列类型通常也是 string。
  2. 创建输出上下文。

    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);
    
  3. 获取目标对象的输出值。

    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);
    
  4. 将值转换为所需格式。

    输出值是字符串值。要将该值用作以 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);
    
  5. 销毁输出上下文。

    完成从输出来源访问数据后,销毁输出上下文。

    Ets_Output_Context_Destroy (c_ptr);
    

    如果输出上下文已过期(例如重新运行了 Flow Analysis),应销毁并重新创建输出上下文以刷新缓存。

列表值

在某些情况下,输出值可能对应显示在同一列、连续多行的多个单元格中的一组值。LSP 的路由就是这种输出表格式的一个例子。

图 17:LSP Routes 报告

LSP Routes 报告

Link 列中的对象列表可以用与前面标量值示例类似的方式获取。

  1. 注册输出值。

    输出值使用 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);
    
  2. 获取输出值。

    创建输出上下文与标量值的情况相同。获取输出值也非常类似。

    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 报告

LSP Routes 报告

这种输出值称为多列值。该值使用 Ets_Output_Table_Multi_Col_Value_Register_With_Type() 注册。主对象作为 hot_link_column_tag 传入,其他列的标签以列表形式传入。

  1. 注册多列值。

    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);
    
  2. 基于多列键获取值。

    获取该值的方式是传入输出值名称以及限定列的值。例如,要获取接口 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)

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · Documentation compiled and provided by Beijing ZNetLink Technology Co., Ltd.

交流群 · QQ Group:OPNET/智网妙算网络仿真交流群(群号 486383494)

原文档 © 2017 Riverbed Technology · 本站为公益翻译,由 AI 辅助完成,请仔细甄别

Original documentation © 2017 Riverbed Technology. Community translation, AI-assisted. Contact: jiazequn@znetlink.com