Changes between Initial Version and Version 1 of User/3aOMLInterface

Feb 18, 2019, 6:03:59 PM (3 years ago)



  • User/3aOMLInterface

    v1 v1  
     1= OML Generic Interface =
     3Several OML applications use different terminologies for the same thing. This page is an attempt to list an authoritative naming for these concepts, that the user should expect to find with any OML application, regardless of how it has been instrumented.
     5Please file a new issue if you find some parts of the OML suite to not comply with it. Features marked EXPERIMENTAL or DEPRECATED are however not yet (or no longer) guaranteed; neither is their stability.
     7== OML Concepts ==
     9An OML experiment consists of one or more application, running on one or more nodes, measuring and reporting a set of samples.
     11* '''Application''': application name '''WARNING:''' must be a valid C identifier (i.e., matching /[a-zA-Z_][0-9a-zA-Z_]*/);
     12* '''Node''': node identifier (e.g., network name or function in the experiment);
     13* '''Domain''': name of the experimental domain (used to group measurements);
     15== Command Line Interface ==
     17OML-instrumented application provide generic command-line and environment interfaces to the user, regardless of the instrumentation method. The OML4R equivalent is also given in parentheses; they can be used to hardcode default values.
     19The precedence of options is as follows:
     22hardcoded < environment < configuration file < command line
     23(:appName): application name WARNING must be hardcoded in the application
     24--oml-id/OML_ID (:nodeID): node identifier
     25--oml-domain/OML_DOMAIN (:domain): experimental domain;
     26--oml-collect URI/OML_COLLECT (:omlCollect): send measurements to URI which can be either [tcp:]HOST[:PORT] for a remote collection point (PORT is 3003 by default), or file:LOCALFILE (file:- being the standard output);
     27Default behaviour: the application will create a text file in the current directory containing OML text protocol for its measurement. The file will be named APPNAME_ID_DOMAIN_TIMESTAMP.
     28--oml-noop: don't report anything (overrides anything else).
     29Obsolescent options¶
     30--oml-exp-id/OML_EXP_ID (:expID): OBSOLESCENT equivalent to --oml-domain;
     31--oml-server URI/OML_SERVER (:omlServer): OBSOLESCENT send measurements to URI; equivalent to --oml-collect URI;
     32--oml-file FILE: OBSOLESCENT write measurements to file FILE; - means stdout; equivalent to --oml-collect file:FILE;
     33OML_NAME, (:id): DEPRECATED equivalent to OML_ID;
     34OML_URL, (:omlURL, :url): DEPRECATED equivalent to OML_COLLECT.
     37== Data Types ==
     39OML supports types similar to basic C types. Their C declaration, as well as their Ruby counterpart (for oml2-scaffold(1)'s defMetric), is given below. Depending on the storage backend, some idiosyncratic behaviour may be noticed, as detailed.
     42OML_INT32_VALUE (:int32): 32-bit integer;
     43OML_UINT32_VALUE (:uint32): unsigned 32-bit integer;
     44OML_INT64_VALUE (:int64): 64-bit integer;
     45OML_UINT64_VALUE (:uint64): unsigned 64-bit integer WARNING depending on the storage backend, there might be issues storing or representing numbers larger than 2^63 (see #1611, #1613);
     46OML_DOUBLE_VALUE (:double): floating point number;
     47OML_STRING_VALUE (:string): character string;
     48OML_BLOB_VALUE (:blob): arbitrary binary data;
     49OML_GUID_VALUE (:guid): a GUID type used to group measurement tuples together, either within or accross MPs (see omlc_guid_generate );
     50OML_BOOL_VALUE (:string): a logical True/False value.
     53=== Vectors ===
     54Since OML 2.11, vectors of data are supported for types other than strings, blobs and GUIDs. They are formed from the name of the singular type, e.g., vectors of OML_INT32_VALUE ar stored in OML_VECTOR_INT32_VALUE types. In the schema declaration, they are put within brackets, e.g., a vector of double@s will be represented as [double]@.
     56=== Deprecated Types ===
     59OML_INTEGER_VALUE (:int): integer which size doesn't really matter; equivalent to OML_INT32_VALUE;
     60(:integer): DEPRECATED equivalent to :int;
     61(:flag): DEPRECATED equivalent to :boolean
     62OML_LONG_VALUE (:long): DEPRECATED cast to OML_INT32_VALUE;