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

Timestamp:

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

Author:

seskar

Comment:

--

User/3aOMLInterface

@@ +1 @@
+= OML Generic Interface =
+
+Several 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.
+
+Please 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.
+
+== OML Concepts ==
+
+An OML experiment consists of one or more application, running on one or more nodes, measuring and reporting a set of samples.
+
+* '''Application''': application name '''WARNING:''' must be a valid C identifier (i.e., matching /[a-zA-Z_][0-9a-zA-Z_]*/);
+* '''Node''': node identifier (e.g., network name or function in the experiment);
+* '''Domain''': name of the experimental domain (used to group measurements);
+
+== Command Line Interface ==
+
+OML-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.
+
+The precedence of options is as follows:
+
+{{{
+hardcoded < environment < configuration file < command line
+(:appName): application name WARNING must be hardcoded in the application
+--oml-id/OML_ID (:nodeID): node identifier
+--oml-domain/OML_DOMAIN (:domain): experimental domain;
+--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);
+Default 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.
+--oml-noop: don't report anything (overrides anything else).
+Obsolescent options¶
+--oml-exp-id/OML_EXP_ID (:expID): OBSOLESCENT equivalent to --oml-domain;
+--oml-server URI/OML_SERVER (:omlServer): OBSOLESCENT send measurements to URI; equivalent to --oml-collect URI;
+--oml-file FILE: OBSOLESCENT write measurements to file FILE; - means stdout; equivalent to --oml-collect file:FILE;
+OML_NAME, (:id): DEPRECATED equivalent to OML_ID;
+OML_URL, (:omlURL, :url): DEPRECATED equivalent to OML_COLLECT.
+}}}
+
+== Data Types ==
+
+OML 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.
+
+{{{
+OML_INT32_VALUE (:int32): 32-bit integer;
+OML_UINT32_VALUE (:uint32): unsigned 32-bit integer;
+OML_INT64_VALUE (:int64): 64-bit integer;
+OML_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);
+OML_DOUBLE_VALUE (:double): floating point number;
+OML_STRING_VALUE (:string): character string;
+OML_BLOB_VALUE (:blob): arbitrary binary data;
+OML_GUID_VALUE (:guid): a GUID type used to group measurement tuples together, either within or accross MPs (see omlc_guid_generate );
+OML_BOOL_VALUE (:string): a logical True/False value.
+}}}
+
+=== Vectors ===
+Since 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]@.
+
+=== Deprecated Types ===
+
+{{{
+OML_INTEGER_VALUE (:int): integer which size doesn't really matter; equivalent to OML_INT32_VALUE;
+(:integer): DEPRECATED equivalent to :int;
+(:flag): DEPRECATED equivalent to :boolean
+OML_LONG_VALUE (:long): DEPRECATED cast to OML_INT32_VALUE;
+OML_FLOAT_VALUE (:float): DEPRECATED cast to OML_DOUBLE_VALUE;
+OML_REAL_VALUE (:real): DEPRECATED cast to OML_DOUBLE_VALUE.
+}}}