CTF2-BASICATTRS-1.0: Basic CTF 2 user attributes
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 <[email protected]>
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 consumerwhen 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
} },
"...": "..."
}
====
Philippe Proulx
Quoted 15 lines · Philippe Proulx
[[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.
Quoted 6 lines
|`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
Philippe Proulx
Quoted 15 lines · Philippe Proulx
[[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.
Quoted 6 lines
|`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
[email protected]
https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev