[diamon-discuss] CTF2-BASICATTRS-1.0: Basic CTF 2 user attributes

[Philippe Proulx <pproulx@efficios.com>]

HTML version:

    http://diamon.org/ctf/files/CTF2-BASICATTRS-1.0.html

Philippe Proulx
EfficiOS Inc.
http://www.efficios.com/

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

= CTF2-BASICATTRS-1.0: Basic CTF{nbsp}2 user attributes
Philippe Proulx <pproulx@efficios.com>
v1.0, 21 October 2016
:toc:
:toclevels: 5
:docid: did:CTF2-BASICATTRS-1.0

This document defines a set of basic user attributes for compatible
CTF{nbsp}2 mdt:map values, that is, the ones that accept a `user-attrs`
property.

A CTF{nbsp}2 consumer which claims to support {docid} can benefit from
additional information attached to those m-values by CTF{nbsp}2
producers which claim to apply {docid} (see <<compliance,Compliance>>).

{docid} mostly exists to define legacy CTF{nbsp}1 attributes that were
removed in did:CTF2-SPEC-2.0.

.RFC 2119
NOTE: The key words _must_, _must not_, _required_, _shall_, _shall
not_, _should_, _should not_, _recommended_, _may_, and _optional_ in
this document, when emphasized, are to be interpreted as described in
https://www.ietf.org/rfc/rfc2119.txt[RFC 2119].


[[compliance]]
== Compliance

A CTF{nbsp}2 producer is said to _apply {docid}_ if it uses the basic
user attributes <<ns,namespace>> in one or more of the `user-attrs`
properties of the metadata mdt:array values it produces.

A CTF{nbsp}2 consumer is said to _support {docid}_ if it recognizes the
basic user attributes <<ns,namespace>> and adapts its behaviour in
the presence of basic user attributes.


[[ns]]
== Namespace

The namespace under which all the basic user attributes presented here
are nested is the following mdt:string:

    diamon.org/ctf/ns/basic

However, it is possible to define an alias for this specific namespace,
and for any other namespace, using the `ns-aliases`
<<trace-class-fragment-bua,trace class fragment's basic user
attribute>>.

Under this namespace (or its alias), the basic user attributes are
always nested within an mdt:map value.

.Basic user attributes namespace and metadata type
====
JSON representation:

[source,json]
{
  "field-type": "int",
  "user-attrs": {
    "diamon.org/ctf/ns/basic": {
      "...": "..."
    }
  },
  "...": "..."
}
====


== Common basic user attributes

The following basic user attributes can be used within any CTF{nbsp}2
mdt:map which accepts a `user-attrs` property.

.Common basic user attributes mdt:map properties
[options="header"]
|===
|Name |Type |Description

|`description`
|mdt:string
|Textual description of the mdt:map (fragment, field type, etc.) in
which this user attribute is placed.
|===


[[trace-class-fragment-bua]]
== Trace class fragment's basic user attributes

.Trace class fragment's basic user attributes mdt:map properties
[options="header"]
|===
|Name |Type |Description

|`description`
|mdt:string
|Textual description of the trace class fragment.

|`supported`
|mdt:null
|This property indicates that {docid} must be considered by a consumer
when reading the various user attributes of the metadata mdt:array.

|`date`
|mdt:string
|Date on which this trace class fragment is produced.

The date's format is not specified.

|`ns-aliases`
|mdt:map with mdt:string values
|Namespace aliases.

This property defines new namespaces which are aliases of other
namespaces for the rest of the metadata mdt:array. Each key of the
mdt:map is an alias and its mdt:string value is the aliased fully
qualified namespace.

Note that the namespace of the trace class fragment's basic user
attributes cannot be aliases since this property is part of it: it must
be the fully qualified namespace, `diamon.org/ctf/ns/basic`.

|`producer-id`
|<<producer-id,Producer ID mdt:map>>
|Producer identification information.

|`sys-id`
|<<sys-id,System ID mdt:map>>
|Instrumented system identification information.

|`dist-id`
|<<dist-id,Distribution ID mdt:map>>
|Distribution identification information.

|`log-level-names`
|mdt:map with mdt:int values
|Log level name to value association.

This property assigns log level integer values to log level names.

A given log level integer value _must not_ be assigned multiple
log level names.
|===

[[producer-id]]
.Producer ID mdt:map properties
[options="header"]
|===
|Name |Type |Description |Required? |Default m-value

|`name`
|mdt:string
|Producer's name.
|Optional
|Unknown producer's name.

|`description`
|mdt:string
|Producer's description.
|Optional
|Unknown producer's description.

|`url`
|mdt:string
|Producer's URL.
|Optional
|Unknown producer's URL.

|`major`
|mdt:int
|Producer's major version number.
|Optional
|0

|`minor`
|mdt:int
|Producer's minor version number.
|Optional
|0

|`patch`
|mdt:int
|Producer's patch version number.
|Optional
|0

|`extra`
|mdt:string
|Producer's extra version number.
|Optional
|No producer's extra version number.
|===

[[sys-id]]
.System ID mdt:map properties
[options="header"]
|===
|Name |Type |Description |Required? |Default m-value

|`name`
|mdt:string
|System's name.
|Optional
|Unknown system's name.

|`node-name`
|mdt:string
|Network node hostname.
|Optional
|Unknown network node hostname.

|`release`
|mdt:string
|System's release.
|Optional
|Unknown system's release.

|`version`
|mdt:string
|System's version.
|Optional
|Unknown system's version.

|`machine`
|mdt:string
|Machine hardware name.
|Optional
|Unknown machine hardware name.

|`processor`
|mdt:string
|Processor type.
|Optional
|Unknown processor type.

|`hw-platform`
|mdt:string
|Hardware platform.
|Optional
|Unknown hardware platform.

|`os`
|mdt:string
|Operating system.
|Optional
|Unknown operating system.
|===

[[dist-id]]
.Distribution ID mdt:map properties
[options="header"]
|===
|Name |Type |Description |Required? |Default m-value

|`id`
|mdt:string
|Distributor ID.
|Optional
|Unknown distributor ID.

|`description`
|mdt:string
|Distribution's description.
|Optional
|Unknown distribution's description.

|`release`
|mdt:string
|Distribution's release number.
|Optional
|Unknown distribution's release number.

|`codename`
|mdt:string
|Distribution's code name.
|Optional
|Unknown distribution's code name.
|===

.Trace class fragment's basic user attributes
====
JSON representation:

[source,json]
{
  "fragment": "trace-class",
  "user-attrs": {
    "diamon.org/ctf/ns/basic": {
      "description": "This is a very nice trace class fragment.",
      "supported": null,
      "date": "Thu Oct 20 01:03:44 EDT 2016",
      "ns-aliases": {
        "basic": "diamon.org/ctf/ns/basic",
        "myns": "9032c3c7-13f9-4d41-9758-dc3331c55bd7",
        "bare": "barectf.org/ns"
      },
      "producer-id": {
        "name": "LTTng-modules",
        "description": "LTTng kernel modules are Linux kernel modules which make LTTng kernel tracing possible.",
        "url": "http://lttng.org/",
        "major": 2,
        "minor": 8,
        "patch": 3
      },
      "sys-id": {
        "name": "Linux",
        "node-name": "janinelaptop",
        "release": "3.13.0-95-generic",
        "version": "#142-Ubuntu SMP Fri Aug 12 17:00:09 UTC 2016",
        "machine": "x86_64",
        "os": "GNU/Linux"
      },
      "dist-id": {
        "id": "Ubuntu",
        "description": "Ubuntu 14.04.4 LTS",
        "release": "14.04",
        "codename": "trusty"
      },
      "log-level-names": {
        "TRACE_EMERG": 0,
        "TRACE_ALERT": 1,
        "TRACE_CRIT": 2,
        "TRACE_ERR": 3,
        "TRACE_WARNING": 4,
        "TRACE_NOTICE": 5,
        "TRACE_INFO": 6,
        "TRACE_DEBUG_SYSTEM": 7,
        "TRACE_DEBUG_PROGRAM": 8,
        "TRACE_DEBUG_PROCESS": 9,
        "TRACE_DEBUG_MODULE": 10,
        "TRACE_DEBUG_UNIT": 11,
        "TRACE_DEBUG_FUNCTION": 12,
        "TRACE_DEBUG_LINE": 13,
        "TRACE_DEBUG": 14
      }
    }
  },
  "...": "..."
}

With the trace class fragment's basic user attributes above, the
`ns-aliases` property gives the alias `basic` to the fully qualified
namespace `diamon.org/ctf/ns/basic`. This means that `basic` (as well as
`diamon.org/ctf/ns/basic`) can be used as the namespace of the
_following_ basic user attributes. `myns` can also be used instead of
`9032c3c7-13f9-4d41-9758-dc3331c55bd7`, and `bare` can be used instead
of `barectf.org/ns`.

Also note that the `supported` property is used here. This is needed to
indicate to the consumers that this metadata mdt:array uses {docid}.
====


[[data-stream-class-fragment-bua]]
== Data stream class fragment's basic user attributes

.Data stream class fragment's basic user attributes mdt:map properties
[options="header"]
|===
|Name |Type |Description

|`description`
|mdt:string
|Textual description of the data stream class fragment.
|===

.Data stream class fragment's basic user attributes
====
JSON representation:

[source,json]
{
  "fragment": "data-stream-class",
  "user-attrs": {
    "diamon.org/ctf/ns/basic": {
      "description": "Some channel."
    }
  },
  "...": "..."
}
====


[[event-record-class-fragment-bua]]
== Event record class fragment's basic user attributes

.Event record class fragment's basic user attributes mdt:map properties
[options="header"]
|===
|Name |Type |Description |Required? |Default m-value

|`description`
|mdt:string
|Textual description of the event record class fragment.
|Optional
|No description.

|`name`
|mdt:string
|Event record class's name or instrumentation point's name.
|Optional
|No name.

|`major`
|mdt:int
|Event record class's major version number.
|Optional
|0

|`minor`
|mdt:int
|Event record class's minor version number.
|Optional
|0

|`patch`
|mdt:int
|Event record class's patch version number.
|Optional
|0

|`extra`
|mdt:string
|Event record class's extra version number.
|Optional
|No event record class's extra version number.

|`log-level`
|mdt:int or mdt:string
|Event record class's (instrumentation point's) log level.

Any mdt:int value is valid.

If an mdt:string value is used, it must name an existing key in the
`log-level-names` property of the <<trace-class-fragment-bua,trace class
fragment's basic user attributes>> (same metadata mdt:array).
|Optional
|No log level.

|`emf-uri`
|mdt:string
|Event record class's http://www.eclipse.org/modeling/emf/[EMF] URI.
|Optional
|No EMF URI.
|===

.Event record class fragment's basic user attributes
====
JSON representation:

[source,json]
{
  "fragment": "event-record-class",
  "user-attrs": {
    "diamon.org/ctf/ns/basic": {
      "description": "My favorite event record class.",
      "name": "sched_switch",
      "major": 1,
      "minor": 0,
      "patch": 2,
      "log-level": "TRACE_CRIT"
    }
  },
  "...": "..."
}
====


[[data-stream-clock-class-fragment-bua]]
== Data stream clock class fragment's basic user attributes

.Data stream clock class fragment's basic user attributes mdt:map properties
[options="header"]
|===
|Name |Type |Description |Required? |Default m-value

|`description`
|mdt:string
|Textual description of the data stream clock class fragment.
|Optional
|No description.
|===

.Data stream clock class fragment's basic user attributes
====
JSON representation:

[source,json]
{
  "fragment": "data-stream-clock-class",
  "user-attrs": {
    "diamon.org/ctf/ns/basic": {
      "description": "Cycle counter synchronized across CPUs."
    }
  },
  "...": "..."
}
====


[[int-field-type-bua]]
== Integer, enumeration, variable-length integer, and variable-length enumeration field type's basic user attributes

.Integer, enumeration, variable-length integer, and variable-length enumeration field type's basic user attributes mdt:map properties
[options="header"]
|===
|Name |Type |Description |Required? |Default m-value

|`description`
|mdt:string
|Textual description of the integer field type class fragment.
|Optional
|No description.

|`display-radix`
|mdt:int
|Radix to prefer using when displaying the value of a field decoded
using this integer field type.

Valid m-values are: 2, 8, 10, and 16.
|Optional
|10
|===

.Integer field type's basic user attributes
====
JSON representation:

[source,json]
{
  "field-type": "int",
  "user-attrs": {
    "diamon.org/ctf/ns/basic": {
      "description": "What an int!",
      "display-radix": 16
    }
  },
  "...": "..."
}
====