CTF2-BASICATTRS-1.0: Basic CTF 2 user attributes

This document defines a set of basic user attributes for compatible CTF 2 m‑map values, that is, the ones that accept a user-attrs property.

A CTF 2 consumer which claims to support CTF2-BASICATTRS-1.0 can benefit from additional information attached to those m-values by CTF 2 producers which claim to apply CTF2-BASICATTRS-1.0 (see Compliance).

CTF2-BASICATTRS-1.0 mostly exists to define legacy CTF 1 attributes that were removed in CTF2-SPEC-2.0.

Note	RFC 2119 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 RFC 2119.

Compliance

A CTF 2 producer is said to apply CTF2-BASICATTRS-1.0 if it uses the basic user attributes namespace in one or more of the user-attrs properties of the metadata m‑array values it produces.

A CTF 2 consumer is said to support CTF2-BASICATTRS-1.0 if it recognizes the basic user attributes namespace and adapts its behaviour in the presence of basic user attributes.

Namespace

The namespace under which all the basic user attributes presented here are nested is the following m‑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’s basic user attribute.

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

Example 1. Basic user attributes namespace and metadata type

JSON representation:

{
  "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 2 m‑map which accepts a user-attrs property.

Table 1. Common basic user attributes `m‑map` properties
Name	Type	Description
`description`	`m‑string`	Textual description of the `m‑map` (fragment, field type, etc.) in which this user attribute is placed.

Trace class fragment’s basic user attributes

Table 2. Trace class fragment’s basic user attributes `m‑map` properties
Name	Type	Description
`description`	`m‑string`	Textual description of the trace class fragment.
`supported`	`m‑null`	This property indicates that CTF2-BASICATTRS-1.0 must be considered by a consumer when reading the various user attributes of the metadata `m‑array`.
`date`	`m‑string`	Date on which this trace class fragment is produced. The date’s format is not specified.
`ns-aliases`	`m‑map` with `m‑string` values	Namespace aliases. This property defines new namespaces which are aliases of other namespaces for the rest of the metadata `m‑array`. Each key of the `m‑map` is an alias and its `m‑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 `m‑map`	Producer identification information.
`sys-id`	System ID `m‑map`	Instrumented system identification information.
`dist-id`	Distribution ID `m‑map`	Distribution identification information.
`log-level-names`	`m‑map` with `m‑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.

Table 3. Producer ID `m‑map` properties
Name	Type	Description	Required?	Default m-value
`name`	`m‑string`	Producer’s name.	Optional	Unknown producer’s name.
`description`	`m‑string`	Producer’s description.	Optional	Unknown producer’s description.
`url`	`m‑string`	Producer’s URL.	Optional	Unknown producer’s URL.
`major`	`m‑int`	Producer’s major version number.	Optional	0
`minor`	`m‑int`	Producer’s minor version number.	Optional	0
`patch`	`m‑int`	Producer’s patch version number.	Optional	0
`extra`	`m‑string`	Producer’s extra version number.	Optional	No producer’s extra version number.

Table 4. System ID `m‑map` properties
Name	Type	Description	Required?	Default m-value
`name`	`m‑string`	System’s name.	Optional	Unknown system’s name.
`node-name`	`m‑string`	Network node hostname.	Optional	Unknown network node hostname.
`release`	`m‑string`	System’s release.	Optional	Unknown system’s release.
`version`	`m‑string`	System’s version.	Optional	Unknown system’s version.
`machine`	`m‑string`	Machine hardware name.	Optional	Unknown machine hardware name.
`processor`	`m‑string`	Processor type.	Optional	Unknown processor type.
`hw-platform`	`m‑string`	Hardware platform.	Optional	Unknown hardware platform.
`os`	`m‑string`	Operating system.	Optional	Unknown operating system.

Table 5. Distribution ID `m‑map` properties
Name	Type	Description	Required?	Default m-value
`id`	`m‑string`	Distributor ID.	Optional	Unknown distributor ID.
`description`	`m‑string`	Distribution’s description.	Optional	Unknown distribution’s description.
`release`	`m‑string`	Distribution’s release number.	Optional	Unknown distribution’s release number.
`codename`	`m‑string`	Distribution’s code name.	Optional	Unknown distribution’s code name.

Example 2. Trace class fragment’s basic user attributes

JSON representation:

{
  "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 m‑array uses CTF2-BASICATTRS-1.0.

Data stream class fragment’s basic user attributes

Table 6. Data stream class fragment’s basic user attributes `m‑map` properties
Name	Type	Description
`description`	`m‑string`	Textual description of the data stream class fragment.

Example 3. Data stream class fragment’s basic user attributes

JSON representation:

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

Event record class fragment’s basic user attributes

Table 7. Event record class fragment’s basic user attributes `m‑map` properties
Name	Type	Description	Required?	Default m-value
`description`	`m‑string`	Textual description of the event record class fragment.	Optional	No description.
`name`	`m‑string`	Event record class’s name or instrumentation point’s name.	Optional	No name.
`major`	`m‑int`	Event record class’s major version number.	Optional	0
`minor`	`m‑int`	Event record class’s minor version number.	Optional	0
`patch`	`m‑int`	Event record class’s patch version number.	Optional	0
`extra`	`m‑string`	Event record class’s extra version number.	Optional	No event record class’s extra version number.
`log-level`	`m‑int` or `m‑string`	Event record class’s (instrumentation point’s) log level. Any `m‑int` value is valid. If an `m‑string` value is used, it must name an existing key in the `log-level-names` property of the trace class fragment’s basic user attributes (same metadata `m‑array`).	Optional	No log level.
`emf-uri`	`m‑string`	Event record class’s EMF URI.	Optional	No EMF URI.

Example 4. Event record class fragment’s basic user attributes

JSON representation:

{
  "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’s basic user attributes

Table 8. Data stream clock class fragment’s basic user attributes `m‑map` properties
Name	Type	Description	Required?	Default m-value
`description`	`m‑string`	Textual description of the data stream clock class fragment.	Optional	No description.

Example 5. Data stream clock class fragment’s basic user attributes

JSON representation:

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

Integer, enumeration, variable-length integer, and variable-length enumeration field type’s basic user attributes

Table 9. Integer, enumeration, variable-length integer, and variable-length enumeration field type’s basic user attributes `m‑map` properties
Name	Type	Description	Required?	Default m-value
`description`	`m‑string`	Textual description of the integer field type class fragment.	Optional	No description.
`display-radix`	`m‑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

Example 6. Integer field type’s basic user attributes

JSON representation:

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