Universal Logging System

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== Data Types, Units & Logical Data Structure =====



==== Data Types ====

Different basic data types can be sent to the ULS-server and stored as values.

  * numbers, as quantity of (a finite subset of) rational numbers
  * strings with up to 32000 characters
  * files up to 1GB of size

Derived data types are identified and interpreted by the used unit and its contents:

  * integer numbers, as quantity of the subset of natural numbers and non-zero natural numbers, 10 digits max
  * floating point numbers, as an approximation to real numbers, 20 significant digits
  * numbers in combination with si-related units (e.g. ''km'', ''m'', ''mm''; or ''°C'', ''°F'', ''K''), 200 characters max
  * timing tuples, as tuples of start- and stop-timing events, bound together with the same time stamp, 200 characters max
  * timestamps in ISO notation (yyyy-mm-dd HH:MM:SS) (use unit ''{DT}'') or seconds since unix epoch (use unit ''{TT}'').
  * strings rendered in monospaced font in the web browser, can e.g. be used for tabular data, 32000 characters max
  * images (.jpg, .png, .gif, ...) are shown as images in the web browser, other files are represented as web links for download


-----

==== Units ====

Units have to be managed by an ULS administrator. The are a lot of 
units already defined in ULS, but your specific ones may not be present 
and you can add your own units.

Each value **must** have a unit, a blank (space) as unit is used for text values. 

-----


=== Default Units ===

This list of units is available by default. Some special units are described further in [[uls:structure#Special Units]] below.

^ unit           ^ SI-unit        ^ sifaktor           ^ sioffset      ^ remark                                     ^
|                |                |                  0 |             0 | (a blank) text                             |
| #              | #              |                  1 |             0 | pseudo unit for unit-less values like counter or ratios  |
| #/s            | #/s            |                  1 |             0 |                                            |
| %              | %              |                  1 |             0 |                                            |
| 1/min          | 1/s            | 0.0166666666666667 |             0 | per minute                                 |
| 1/s            | 1/s            |                  1 |             0 | per second                                 |
| A              | A              |                  1 |             0 | ampere                                     |
| Anzahl         | Anzahl         |                  1 |             0 | count                                      |
| bar            | Pa             |                0.1 |             0 | bar                                        |
| BLOB           |                |                  0 |             0 | pseudo unit for blobs                      |
| boolean        | boolean        |                  1 |             0 | to represent true and false as 0 and 1     |
| Byte           | kByte          |       0.0009765625 |             0 | Byte                                       |
| Byte/s         | kB/s           |              0.001 |             0 | Byte/s                                     |
| Bytes          | kByte          |       0.0009765625 |             0 | Byte                                       |
| Bytes/s        | kB/s           |              0.001 |             0 | Byte/s                                     |
| cm             | m              |               0.01 |             0 | centimeter                                 |
| COUNTER        | COUNTER        |                  1 |             0 | pseudo unit for counter                    |
| d              | s              |              86400 |             0 | days                                       |
| dm             | m              |                0.1 |             0 | decimeter                                  |
| files          | files          |                  1 |             0 |                                            |
| g              | kg             |              0.001 |             0 | gram                                       |
| GB             | kByte          |            1048576 |             0 |                                            |
| GB/s           | kB/s           |            1048576 |             0 |                                            |
| GByte          | kByte          |            1048576 |             0 |                                            |
| GBytes         | kByte          |            1048576 |             0 | GigaByte                                   |
| GHz            | kHz            |            1000000 |             0 |                                            |
| h              | s              |               3600 |             0 |                                            |
| hPa            | Pa             |                100 |             0 | Hektopascal                                |
| IMAGE          |                |                  0 |             0 | pseudo unit for images                     |
| K              | K              |                  1 |             0 | Kelvin                                     |
| kA             | A              |               1000 |             0 | Kiloampere                                 |
| kB             | kByte          |                  1 |             0 |                                            |
| kB/s           | kB/s           |                  1 |             0 |                                            |
| kByte          | kByte          |                  1 |             0 |                                            |
| kg             | kg             |                  1 |             0 |                                            |
| kHz            | kHz            |                  1 |             0 |                                            |
| km             | m              |               1000 |             0 | kilometer                                  |
| km/h           | m/s            |                3.6 |             0 | kilometers per hour                        |
| kV             | V              |               1000 |             0 | kilovolt                                   |
| kW             | W              |               1000 |             0 | kilowatt                                   |
| kWh            | Wh             |               1000 |             0 | kilowatt hours                             |
| m              | m              |                  1 |             0 |                                            |
| m/s            | m/s            |                  1 |             0 | meter/second                               |
| mA             | A              |              0.001 |             0 | milliampere                                |
| MB             | kByte          |               1024 |             0 |                                            |
| MB/s           | kB/s           |               1024 |             0 |                                            |
| mbar           | Pa             |                100 |             0 | millibar                                   |
| MByte          | kByte          |               1024 |             0 |                                            |
| MBytes         | kByte          |               1024 |             0 | MegaByte                                   |
| MBytes/s       | MBytes/s       |                  1 |             0 |                                            |
| min            | s              |                 60 |             0 | minute                                     |
| mm             | m              |              0.001 |             0 | millimeter                                 |
| ms             | s              |              0.001 |             0 | milli second                               |
| ms/MB          | ms/MB          |                  1 |             0 | ms/MB                                      |
| mV             | V              |              0.001 |             0 | milli volt                                 |
| MW             | W              |            1000000 |             0 | Megawatt                                   |
| MWh            | Wh             |            1000000 |             0 | Megawatt hours                             |
| Pa             | Pa             |                  1 |             0 | pascal                                     |
| pages          | pages          |                  1 |             0 |                                            |
| RPM            | 1/s            | 0.0166666666666667 |             0 | revolutions per minute                     |
| s              | s              |                  1 |             0 | second                                     |
| Stunden        | Stunden        |                  1 |             0 | hours                                      |
| Tage           | s              |              86400 |             0 | days                                       |
| TB             | kByte          |            1048576 |             0 |                                            |
| TByte          | kByte          |            1048576 |             0 |                                            |
| TBytes         | kByte          |         1073741824 |             0 | TeraByte                                   |
| V              | V              |                  1 |             0 | volt                                       |
| W              | W              |                  1 |             0 | watt                                       |
| Wh             | Wh             |                  1 |             0 | watt hours                                 |
| [#]            | [#]            |                  1 |             0 | pseudo unit for unit-less values like ratios  |
| [/]            | [/]            |                  1 |             0 | ratio (last/average)                       |
| [E]            | [E]            |                  0 |             0 | "value unit", SI-factor must be 0!         |
| [N]            |                |                  0 |             0 | text (space separation)                    |
| [T]            |                |                  0 |             0 | text (tabular separation)                  |
| [UTTID]        |                |                  0 |             0 | pseudo unit for a link to a UTT            |
| []             | []             |                  1 |             0 | pseudo unit for unit-less values like counter or ratios, uses a point in graphs, not a line as '#' |
| _              |                |                  0 |             0 | monospaced text                            |
| _N             |                |                  0 |             0 | multiple text expressions, separated by empty line |
| _T             |                |                  0 |             0 | tabular text expressions                   |
| {DT}           |                |                  0 |             0 | time stamp in the format: yyyy-mm-dd hh:mm:ss[{+-}hh:mm]   |
| {E} #:Laufwerk | {E} #:Laufwerk |                  0 |             0 | time interval + drive/unit #               |
| {E} :Lw        | {E} :Lw        |                  0 |             0 | time interval + drive                      |
| {T}            | {T}            |                  0 |             0 | time interval                              |
| {T} :Node      | {T} :Node      |                  0 |             0 | time interval + nodes (SCCL)               |
| {TT}           |                |                  0 |             0 | time stamp, seconds since unix big bang    |
| °              | °              |                  1 |             0 | degrees                                    |
| °C             | K              |                  1 |        273.15 | degrees Celsius                            |
| °F             | K              |        0.555555555 | 255.372222222 | degrees Fahrenheit                         |
| °Ra            | K              |        0.555555555 |             0 | degrees Rankine                            |
| °Ré            | K              |               1.25 |        273.15 | degrees Réaumur                            |
| °Rø            | K              |        1.904761904 |        258.86 | degrees Rømer                              |

-----

=== Special Units ===

Here is a table of all special units. These have a special meaning 
and should not be changed or removed from the unit list. 

{|
! unit
! value type
! description
|-
| #
| numeric
| Counter, for numbers without units, but allows graphical representation.
|-
| [#]
| numeric
| Like #, but uses a single box for each value
 (instead of a line connecting all values) in graphical representations.
|-
| [/]
| numeric
| Ratio of values, no unit is displayed, but allows graphical representation.
|-
| {DT}
| timestamp
| the value is interpreted as time stamp. Format is "YYYY-MM-DD hh:mm:ss[{+|-}hh:mm]". 
 There is no graphical representation but limits and aggregations in combination  
 with function "age" may be applied.
|-
| [E]
| numeric
| Special unit for values which are acquired in different (although related) units.
 Example: a length is measured, the measuring equipment returns the value
 in m (meter) or in km (kilometer) depending on the length. You may send that
 value as "<value> <unit>" ("2.54 km") and specify "[E]" as unit for ULS. 
 Then, the ULS-server  shows all "<value> <unit>" pairs in the grid 
 and graphs can be generated of these values. 
 The values are calculated to a base unit (si-unit) which is also used as unit for the respective y-axis.
 **BUT**: details having this unit do currently only support the 
 comparisons: last, first, count, differ in limit definitions!
 And not all aggregations are supported!
|-
| {E}
| time
| timing tuple with additional attributes, example:
 value: "Start YYYY-MM-DD hh:mm:ss[{+|-}hh:mm] <expression>" 
 or "Stop YYYY-MM-DD hh:mm:ss[{+|-}hh:mm] <expression>", 
 unit: "{E} <y-axis unit>:<y-axis title>"
|-
| {T}
| time
| marks a timing tuple, the values must be in the format 
 "Start YYYY-MM-DD hh:mm:ss[{+|-}hh:mm]" for the time stamp of the start of an action
 or "Stop YYYY-MM-DD hh:mm:ss[{+|-}hh:mm]" for the time stamp of the stop of an action. 
 Both values **must** be related to the same time stamp (of the value, not of the action). 
 The timing tuple is represented as a horizontal bar in graphs
|-
| {TT}
| timestamp
| the value is interpreted as time stamp. It must be the number of seconds since unix epoch (1970-01-01 00:00:00 UTC). 
 There is no graphical representation but limits and aggregations in combination  
 with function "age" may be applied.
|-
| ' ' (space)
| string
| for text expressions in proportional font, same as no unit at all
|-
| [ ] (space in square brackets)
| string
| for short text expressions in proportional font, max 200 characters
|-
| [N]
| string
| ???
|-
| [T]
| string
| Several lines for the same timestamp. ALL details MUST be filled with details, 
 no matter in what sequence the details are filled.
|-
| _ (underscore)
| string
| for text expressions in monospaced font
|-
| [_] (underscore in square brackets)
| string
| for short text expressions in monospaced font, max 200 characters
|-
| _N
| string
| like underscore, all values **for the same time stamp** will be 
 separated by empty lines. That is intended only for better readability.
|-
| _T
| 
| ???
|-
| __ (2 underscores)
| string
| for text expressions, will be kept forever. This is deprecated, 
 use an adequate retention policy for your values.
|}

-----

==== Unit Management ====

The ULS administrator manages the units. Log in as ULS administrator and
move to 'system --> edit units'.

The list of units looks like (just an example):

^name     ^si-unit      ^si-factor     ^si-offset   ^printflag   ^plotstyle   ^remark              ^
|boolean  |boolean      |1             |0           |[x]         |impulses    |                    |
|Byte     |kByte        |0.0009765625  |0           |[x]         |lines       |Byte                |
|hPa      |Pa           |100           |0           |[x]         |lines       |Hectopascal         |
|°C       |K            |1             |273.15      |[x]         |lines       |degrees centigrade  |


Units (name) can be defined as a simple function to base units (si-unit) 
by using factors (si-factor).

:TODO: how about a dynamically evaluateable equation where x is replaced by the <value>

<value> [<name>] * <si-factor> = <value2> [<si-unit>]

If you are creating a new unit and its si-unit does not exist yet, 
then leave "si-unit" blank and change it after 
the si-unit has been created initially.

(new in version 1.7.0)

Units (name) can be defined as a simple function to base units (si-unit) 
by using factors (si-factor) and offsets (si-offset). 

<value> [<name>] * <si-factor> + <si-offset> = <value2> [<si-unit>]

SI-Units can be used for manual scaling of different base units in graphs
or in definitions of derived or calculated details.

-----

==== Logical Data Structure ====

Each value in the ULS corresponds to a combination of the attributes:

{|
!attribute
!description
|-
|timestamp: 
|Each value **must** have a time stamp. Only values that are 
 provided with a time stamp can be processed by the ULS. The 
 minimum resolution is one second.
|-
|source: 
|The source of the values, e.g. a ''server'', a 'car park' or a 'marathon'. A source can have many different sections.
|-
|section: 
|Comprises related teststeps, e.g. 'system performance', a 'car' or a 'marathon participant'.
|-
|teststep:  
|Comprises related details, e.g. 'system load', 
 'refueling' or 'key body indicators'.
 It may consist of several level, each separated by a colon.
|-
|detail:  
|The attribute to which the value belongs, e.g. '%idle', 'gallons' or 'heartbeat'
|-
|value:   
|That is the (measured) value, e.g. '73.8', '13.234', '82'. 
 The decimal point is **ALWAYS** :!: a decimal point.
|-
|unit:  
|The unit of the value, e.g. '%', 'gal', '1/s'
|-
|access: 
|This attribute may restrict the access of ULS-users to this detail.
 Only ULS-users that have been granted this access privilege 
 will be able to see the detail.
 Only an ULS-administrator can set privileges of ULS-users.
|}

The domain is derived from the source, it is a constant, manually defined relation.
A domain is a collection of one to many (value-) sources which belong 
somehow together. User access and privileges are bound to the domain.

The logical data structure is similar to the representation in the 
ULS user interface (interactive webbrowser-based analysis):

<file>
<domain>
  │
  └──►<source>
      │
      └──►<section>
            │
            └──►<teststep>  | time stamp           |  detail  |  detail  |
                            |                      |  unit    |  unit    |
                            | ---------------------|----------|----------|
                            | yyyy-mm-dd hh:mi:ss  |  value   |  value   |
                            | yyyy-mm-dd hh:mi:ss  |  value   |  value   |
                            | yyyy-mm-dd hh:mi:ss  |  value   |  value   |
</file>

The relation between domains and sources must be kept manually, all other 
relations are automatically determined by the values that are transferred to the ULS and 
do not need any administrative activities.
Universal Logging System

User Tools

Site Tools

Page Tools
