interface¶
Type of operation: Metadata
Description¶
Map fields of this dataset to a pre-defined interface.
For each well-defined interface, some number of field:type mappings are defined, which makes the dataset work according to the needs of that interface. The most common such interface is “metric” which makes Observe calculate summaries of the metrics, and present them in the metric browser. Each named field in the interface is also referred to as a interface field name because the name identifies a particular role for the field (for example “this field is the name of this metric.”)
The “metric” interface requires the following fields:
Name |
Type |
Meaning |
|---|---|---|
metric |
string |
The metric name. |
value |
float64 |
The metric value. |
If a column of the expected name and type already exists, it will be picked up as the “right” column, whereas if the intended column has another name, you will need to specify it:
interface "metric", metric:my_name, value:the_reading
This interface can currently bind these interface field names to fields with
different names, without renaming the columns, such as shown in one of the
examples below. For example, there may be a field named “my_name” that is bound
to the “metric” interface field name because it contains the metric name in
this dataset. Because using a differently-named column for the particular
interface field can be confusing, Observe strongly recommends making the name
of the field be the same as the name of the interface field – use rename_col metric:my_name before declaring interface "metric".
Some metric data sources may provide useful metadata. If the metric type, unit size, and description are available or can be defined in OPAL, you can add them to the metrics interface. When these options are defined, Observe can find the metric metadata in the columns for these optional string fields.
Name |
Meaning |
|---|---|
metricType |
The type of metric, such as gauge or histogram |
metricUnit |
The unit size of the metric, such as bits or kilobytes |
metricDescription |
A description of the metric |
Note that interface is transitive, meaning child datasets will inherit the interface from their parents. This makes datasets available for exploration without requiring an explicit declaration on every dataset definition.
Usage¶
interface interfaceName, fieldBinding_1, fieldBinding_2, ...
Argument |
Type |
Optional |
Repeatable |
Restrictions |
|---|---|---|---|---|
interfaceName |
string |
no |
no |
none |
fieldBinding |
expression |
no |
yes |
none |
Accelerable¶
interface is always accelerable if the input is accelerable. A dataset that only uses accelerable verbs can be accelerated, making queries on the dataset respond faster.
Examples¶
make_col metric:string(FIELDS.metric_name), value:float64(FIELDS.sample_value)
interface "metric"
Make this dataset implement the ‘metric’ interface, after first extracting the metric name and metric value from the FIELDS object. Because the columns have names matching the interface needs, they don’t need to be named again.
interface "metric", metric:metricNameColumn, value:metricValueColumn
Make this dataset implement the ‘metric’ interface. Bind the existing column containing metric names (‘metricNameColumn’) to the ‘metric’ interfaceName, and the existing column containing ‘float64’ metric values (‘metricValueColumn’) to the ‘value’ interfaceName.
make_col log:string(FIELDS.log_msg)
interface "log"
Make this dataset implement the ‘log’ interface, after first extracting the log message from the FIELDS object. Because the column name matches the interface expectation of “log”, it does not need to be named again.