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

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

[Philippe Proulx]

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
    }
  },
  "...": "..."
}
====

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

[Philippe Proulx]

Philippe Proulx
On Tue, Oct 25, 2016 at 2:27 PM, Philippe Proulx <pproulx@efficios.com> wrote:
>
> [[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.
>

Should we also put a namespace for the event record class fragment
itself here? I'm talking about an `ns` property as a basic user
attribute, e.g.:

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

This could avoid eventual name clashes between tracers, and also allow
different tracers to output the "same" event records. Let me illustrate
both scenarios:

1. Consider this event record class fragment:

       {
         "fragment": "event-record-class",
         "user-attrs": {
           "diamon.org/ctf/ns/basic": {
             "name": "new_msg",
             "major": 1,
             "minor": 1,
             "patch": 3,
             ...
           }
         },
         ...
       }

   Assume that this is produced by LTTng-UST. An analysis reads this
   and is able to know that it's an event record class named `new_msg`,
   version 1.1.

   However, without a namespace, the analysis has to rely on the tracer
   information found in the user attributes of the trace class fragment
   (`producer-id`), which is optional by the way, to make sure that it's
   event record class `new_msg` produced by some known tracer(s).

   This is not super reliable. You should never rely on the producer ID,
   it's just extra information about the origin of the trace. This is
   the equivalent of relying on the `tracer_name` environment entry
   in CTF 1.x.

2. Consider the same event record class fragment as in #1.

   What if multiple tracers can emit the specific events described by
   this class (same name, same version, same meaning). Then every
   analysis needs to know that this and this specific tracer can produce
   this event record class.

   If a future tracer also wants to produce this, then all the analyses
   must be updated to support this new producer.

If you namespace the event record class itself, then you have a solution
for points 1 and 2 above:

1. No need to rely on the producer ID: use the unique event record
   class's namespace (and its name within this namespace) to know its
   meaning.
2. Multiple producers with different producer IDs can write the
   same event record class fragment with a given namespace and name.

The `ns-aliases` trace class fragment basic user attribute could or
could not have an effect on this `ns` attribute. If it does, here's an
example:

    {
      "fragment": "trace-class",
      "user-attrs": {
        "diamon.org/ctf/ns/basic": {
          ...
          "ns-aliases": {
            "basic": "diamon.org/ctf/ns/basic",
            "modules": "lttng.org/ns/ctf/modules"
          },
          ...
        }
      },
      ...
    }

    ...

    {
      "fragment": "event-record-class",
      "user-attrs": {
        "basic": {
          "ns": "modules",
          "name": "sched_switch",
          "major": 1,
          "minor": 0,
          "patch": 2,
          ...
        }
      },
      ...
    }

Thoughts about this?

Philippe Proulx

Re: CTF2-BASICATTRS-1.0: Basic CTF 2 user attributes

[Philippe Proulx]

Philippe Proulx
On Tue, Oct 25, 2016 at 2:27 PM, Philippe Proulx <pproulx@efficios.com> wrote:
>
> [[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.
>

Should we also put a namespace for the event record class fragment
itself here? I'm talking about an `ns` property as a basic user
attribute, e.g.:

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

This could avoid eventual name clashes between tracers, and also allow
different tracers to output the "same" event records. Let me illustrate
both scenarios:

1. Consider this event record class fragment:

       {
         "fragment": "event-record-class",
         "user-attrs": {
           "diamon.org/ctf/ns/basic": {
             "name": "new_msg",
             "major": 1,
             "minor": 1,
             "patch": 3,
             ...
           }
         },
         ...
       }

   Assume that this is produced by LTTng-UST. An analysis reads this
   and is able to know that it's an event record class named `new_msg`,
   version 1.1.

   However, without a namespace, the analysis has to rely on the tracer
   information found in the user attributes of the trace class fragment
   (`producer-id`), which is optional by the way, to make sure that it's
   event record class `new_msg` produced by some known tracer(s).

   This is not super reliable. You should never rely on the producer ID,
   it's just extra information about the origin of the trace. This is
   the equivalent of relying on the `tracer_name` environment entry
   in CTF 1.x.

2. Consider the same event record class fragment as in #1.

   What if multiple tracers can emit the specific events described by
   this class (same name, same version, same meaning). Then every
   analysis needs to know that this and this specific tracer can produce
   this event record class.

   If a future tracer also wants to produce this, then all the analyses
   must be updated to support this new producer.

If you namespace the event record class itself, then you have a solution
for points 1 and 2 above:

1. No need to rely on the producer ID: use the unique event record
   class's namespace (and its name within this namespace) to know its
   meaning.
2. Multiple producers with different producer IDs can write the
   same event record class fragment with a given namespace and name.

The `ns-aliases` trace class fragment basic user attribute could or
could not have an effect on this `ns` attribute. If it does, here's an
example:

    {
      "fragment": "trace-class",
      "user-attrs": {
        "diamon.org/ctf/ns/basic": {
          ...
          "ns-aliases": {
            "basic": "diamon.org/ctf/ns/basic",
            "modules": "lttng.org/ns/ctf/modules"
          },
          ...
        }
      },
      ...
    }

    ...

    {
      "fragment": "event-record-class",
      "user-attrs": {
        "basic": {
          "ns": "modules",
          "name": "sched_switch",
          "major": 1,
          "minor": 0,
          "patch": 2,
          ...
        }
      },
      ...
    }

Thoughts about this?

Philippe Proulx
_______________________________________________
lttng-dev mailing list
lttng-dev@lists.lttng.org
https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev